lib/servlet-api/javax/servlet/annotation/WebFilter.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one or more
   3  * contributor license agreements.  See the NOTICE file distributed with
   4  * this work for additional information regarding copyright ownership.
   5  * The ASF licenses this file to You under the Apache License, Version 2.0
   6  * (the "License"); you may not use this file except in compliance with
   7  * the License.  You may obtain a copy of the License at
   8  *
   9  *      http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17 package javax.servlet.annotation;
  18
  19 import java.lang.annotation.Documented;
  20 import java.lang.annotation.ElementType;
  21 import java.lang.annotation.Retention;
  22 import java.lang.annotation.RetentionPolicy;
  23 import java.lang.annotation.Target;
  24
  25 import javax.servlet.DispatcherType;
  26
  27 /**
  28  * The annotation used to declare a Servlet {@link javax.servlet.Filter}. <br />
  29  * <br />
  30  *
  31  * This annotation will be processed by the container during deployment, the
  32  * Filter class in which it is found will be created as per the configuration
  33  * and applied to the URL patterns, {@link javax.servlet.Servlet}s and
  34  * {@link javax.servlet.DispatcherType}s.<br />
  35  * <br/>
  36  *
  37  * If the name attribute is not defined, the fully qualified name of the class
  38  * is used.<br/>
  39  * <br/>
  40  *
  41  * At least one URL pattern MUST be declared in either the {@code value} or
  42  * {@code urlPattern} attribute of the annotation, but not both.<br/>
  43  * <br/>
  44  *
  45  * The {@code value} attribute is recommended for use when the URL pattern is
  46  * the only attribute being set, otherwise the {@code urlPattern} attribute
  47  * should be used.<br />
  48  * <br />
  49  *
  50  * The annotated class MUST implement {@link javax.servlet.Filter}.
  51  *
  52  * E.g.
  53  *
  54  * <code>@WebFilter("/path/*")</code><br />
  55  * <code>public class AnExampleFilter implements Filter { ... </code><br />
  56  *
  57  * @since Servlet 3.0 (Section 8.1.2)
  58  *
  59  */
  60 @Target({ElementType.TYPE})
  61 @Retention(RetentionPolicy.RUNTIME)
  62 @Documented
  63 public @interface WebFilter {
  64
  65     /**
  66      * @return description of the Filter, if present
  67      */
  68     String description() default "";
  69
  70     /**
  71      * @return display name of the Filter, if present
  72      */
  73     String displayName() default "";
  74
  75     /**
  76      * @return array of initialization params for this Filter
  77      */
  78     WebInitParam[] initParams() default {};
  79
  80     /**
  81      * @return name of the Filter, if present
  82      */
  83     String filterName() default "";
  84
  85     /**
  86      * @return small icon for this Filter, if present
  87      */
  88     String smallIcon() default "";
  89
  90     /**
  91      * @return the large icon for this Filter, if present
  92      */
  93     String largeIcon() default "";
  94
  95     /**
  96      * @return array of Servlet names to which this Filter applies
  97      */
  98     String[] servletNames() default {};
  99
 100     /**
 101      * A convenience method, to allow extremely simple annotation of a class.
 102      *
 103      * @return array of URL patterns
 104      * @see #urlPatterns()
 105      */
 106     String[] value() default {};
 107
 108     /**
 109      * @return array of URL patterns to which this Filter applies
 110      */
 111     String[] urlPatterns() default {};
 112
 113     /**
 114      * @return array of DispatcherTypes to which this filter applies
 115      */
 116     DispatcherType[] dispatcherTypes() default {DispatcherType.REQUEST};
 117
 118     /**
 119      * @return asynchronous operation supported by this Filter
 120      */
 121     boolean asyncSupported() default false;
 122 }