import java.lang.annotation.Target;
/**
+ * This annotation is used to declare an array of application classes which are
+ * passed to a {@link javax.servlet.ServletContainerInitializer}.
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@SuppressWarnings("unchecked") // Spec API does not use generics
public @interface HandlesTypes {
+
+ /**
+ * @return array of classes
+ */
Class[] value();
+
}
import javax.servlet.annotation.ServletSecurity.TransportGuarantee;
/**
+ * This annotation represents the security constraints that are applied to all
+ * requests with HTTP protocol method types that are not otherwise represented
+ * by a corresponding {@link javax.servlet.annotation.HttpMethodConstraint} in a
+ * {@link javax.servlet.annotation.ServletSecurity} annotation.
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface HttpConstraint {
+
+ /**
+ * The EmptyRoleSemantic determines the behaviour when the rolesAllowed list
+ * is empty.
+ *
+ * @return empty role semantic
+ */
EmptyRoleSemantic value() default EmptyRoleSemantic.PERMIT;
+
+ /**
+ * Determines whether SSL/TLS is required to process the current request.
+ *
+ * @return transport guarantee
+ */
TransportGuarantee transportGuarantee() default TransportGuarantee.NONE;
+
+ /**
+ * The authorized roles' names. The container may discard duplicate role
+ * names during processing of the annotation. N.B. The String "*" does not
+ * have a special meaning if it occurs as a role name.
+ *
+ * @return array of names. The array may be of zero length, in which case
+ * the EmptyRoleSemantic applies; the returned value determines
+ * whether access is to be permitted or denied regardless of the
+ * identity and authentication state in either case, PERMIT or DENY.<br />
+ * Otherwise, when the array contains one or more role names access
+ * is permitted if the user a member of at least one of the named
+ * roles. The EmptyRoleSemantic is not applied in this case.
+ *
+ */
String[] rolesAllowed() default {};
+
}
import javax.servlet.annotation.ServletSecurity.TransportGuarantee;
/**
+ * Specific security constraints can be applied to different types of request,
+ * differentiated by the HTTP protocol method type by using this annotation
+ * inside the {@link javax.servlet.annotation.ServletSecurity} annotation.
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ *
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface HttpMethodConstraint {
+
+ /**
+ * HTTP Protocol method name (e.g. POST, PUT)
+ *
+ * @return method name
+ */
String value();
+
+ /**
+ * The EmptyRoleSemantic determines the behaviour when the rolesAllowed list
+ * is empty.
+ *
+ * @return empty role semantic
+ */
EmptyRoleSemantic emptyRoleSemantic() default EmptyRoleSemantic.PERMIT;
+
+ /**
+ * Determines whether SSL/TLS is required to process the current request.
+ *
+ * @return transport guarantee
+ */
TransportGuarantee transportGuarantee() default TransportGuarantee.NONE;
+
+ /**
+ * The authorized roles' names. The container may discard duplicate role
+ * names during processing of the annotation. N.B. The String "*" does not
+ * have a special meaning if it occurs as a role name.
+ *
+ * @return array of names. The array may be of zero length, in which case
+ * the EmptyRoleSemantic applies; the returned value determines
+ * whether access is to be permitted or denied regardless of the
+ * identity and authentication state in either case, PERMIT or DENY.<br />
+ * Otherwise, when the array contains one or more role names access
+ * is permitted if the user a member of at least one of the named
+ * roles. The EmptyRoleSemantic is not applied in this case.
+ */
String[] rolesAllowed() default {};
}
import java.lang.annotation.Target;
/**
+ * This annotation is used to indicate that the {@link javax.servlet.Servlet} on
+ * which it is declared expects requests to made using the {@code
+ * multipart/form-data} MIME type. <br />
+ * <br />
+ *
+ * {@link javax.servlet.http.Part} components of a given {@code
+ * multipart/form-data} request are retrieved by a Servlet annotated with
+ * {@code MultipartConfig} by calling
+ * {@link javax.servlet.http.HttpServletRequest#getPart} or
+ * {@link javax.servlet.http.HttpServletRequest#getParts}.<br />
+ * <br />
+ *
+ * E.g. <code>@WebServlet("/upload")}</code><br />
+ *
+ * <code>@MultipartConfig()</code> <code>public class UploadServlet extends
+ * HttpServlet ... } </code><br />
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MultipartConfig {
+
+ /**
+ * @return location in which the Container stores temporary files
+ */
String location() default "";
+
+ /**
+ * @return the maximum size allowed for uploaded files (in bytes)
+ */
long maxFileSize() default -1L;
+
+ /**
+ * @return the maximum size of the request allowed for {@code
+ * multipart/form-data}
+ */
long maxRequestSize() default -1L;
+
+ /**
+ * @return the size threshold at which the file will be written to the disk
+ */
int fileSizeThreshold() default 0;
}
import java.lang.annotation.Target;
/**
+ * Declare this annotation on a {@link javax.servlet.Servlet} implementation
+ * class to enforce security constraints on HTTP protocol requests.<br />
+ * The container applies constraints to the URL patterns mapped to each Servlet
+ * which declares this annotation.<br />
+ * <br />
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
*/
@Inherited
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ServletSecurity {
+
+ /**
+ * Represents the two possible values of the empty role semantic, active
+ * when a list of role names is empty.
+ */
enum EmptyRoleSemantic {
+
+ /**
+ * Access MUST be permitted, regardless of authentication state or
+ * identity
+ */
PERMIT,
+
+ /**
+ * Access MUST be denied, regardless of authentication state or identity
+ */
DENY
}
+
+ /**
+ * Represents the two possible values of data transport, encrypted or not.
+ */
enum TransportGuarantee {
+
+ /**
+ * User data must not be encrypted by the container during transport
+ */
NONE,
+
+ /**
+ * The container MUST encrypt user data during transport
+ */
CONFIDENTIAL
}
+
+ /**
+ * The default constraint to apply to requests not handled by specific
+ * method constraints
+ *
+ * @return http constraint
+ */
HttpConstraint value() default @HttpConstraint;
+
+ /**
+ * An array of HttpMethodContraint objects to which the security constraint
+ * will be applied
+ *
+ * @return array of http method constraint
+ */
HttpMethodConstraint[] httpMethodConstraints() default {};
}
*/
package javax.servlet.annotation;
+import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
-import java.lang.annotation.Documented;
import javax.servlet.DispatcherType;
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * The annotation used to declare a Servlet {@link javax.servlet.Filter}. <br />
+ * <br />
+ *
+ * This annotation will be processed by the container during deployment, the
+ * Filter class in which it is found will be created as per the configuration
+ * and applied to the URL patterns, {@link javax.servlet.Servlet}s and
+ * {@link javax.servlet.DispatcherType}s.<br />
+ * <br/>
+ *
+ * If the name attribute is not defined, the fully qualified name of the class
+ * is used.<br/>
+ * <br/>
+ *
+ * At least one URL pattern MUST be declared in either the {@code value} or
+ * {@code urlPattern} attribute of the annotation, but not both.<br/>
+ * <br/>
+ *
+ * The {@code value} attribute is recommended for use when the URL pattern is
+ * the only attribute being set, otherwise the {@code urlPattern} attribute
+ * should be used.<br />
+ * <br />
+ *
+ * The annotated class MUST implement {@link javax.servlet.Filter}.
+ *
+ * E.g.
+ *
+ * <code>@WebFilter("/path/*")</code><br />
+ * <code>public class AnExampleFilter implements Filter { ... </code><br />
+ *
+ * @since Servlet 3.0 (Section 8.1.2)
+ *
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebFilter {
+
+ /**
+ * @return description of the Filter, if present
+ */
String description() default "";
+
+ /**
+ * @return display name of the Filter, if present
+ */
String displayName() default "";
+
+ /**
+ * @return array of initialization params for this Filter
+ */
WebInitParam[] initParams() default {};
+
+ /**
+ * @return name of the Filter, if present
+ */
String filterName() default "";
+
+ /**
+ * @return small icon for this Filter, if present
+ */
String smallIcon() default "";
+
+ /**
+ * @return the large icon for this Filter, if present
+ */
String largeIcon() default "";
+
+ /**
+ * @return array of Servlet names to which this Filter applies
+ */
String[] servletNames() default {};
+
+ /**
+ * A convenience method, to allow extremely simple annotation of a class.
+ *
+ * @return array of URL patterns
+ * @see #urlPatterns()
+ */
String[] value() default {};
+
+ /**
+ * @return array of URL patterns to which this Filter applies
+ */
String[] urlPatterns() default {};
+
+ /**
+ * @return array of DispatcherTypes to which this filter applies
+ */
DispatcherType[] dispatcherTypes() default {DispatcherType.REQUEST};
+
+ /**
+ * @return asynchronous operation supported by this Filter
+ */
boolean asyncSupported() default false;
}
*/
package javax.servlet.annotation;
+import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
-import java.lang.annotation.Documented;
/**
+ * The annotation used to declare an initialization parameter on a
+ * {@link javax.servlet.Servlet} or {@link javax.servlet.Filter}, within a
+ * {@link javax.servlet.annotation.WebFilter} or
+ * {@link javax.servlet.annotation.WebServlet} annotation.<br />
+ * <br />
+ *
+ * E.g.
+ * <code>@WebServlet(name="TestServlet", urlPatterns={"/test"},initParams={@WebInitParam(name="test", value="true")})
+ * public class TestServlet extends HttpServlet { ... </code><br />
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebInitParam {
+
+ /**
+ * @return name of the initialization parameter
+ */
String name();
+
+ /**
+ * @return value of the initialization parameter
+ */
String value();
+
+ /**
+ * @return description of the initialization parameter
+ */
String description() default "";
}
*/
package javax.servlet.annotation;
+import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
-import java.lang.annotation.Documented;
/**
+ * The annotation used to declare a listener for various types of event, in a
+ * given web application context.<br />
+ * <br />
+ *
+ * The class annotated MUST implement one, (or more), of the following
+ * interfaces: {@link javax.servlet.http.HttpSessionAttributeListener},
+ * {@link javax.servlet.http.HttpSessionListener},
+ * {@link javax.servlet.ServletContextAttributeListener},
+ * {@link javax.servlet.ServletContextListener},
+ * {@link javax.servlet.ServletRequestAttributeListener},
+ * {@link javax.servlet.ServletRequestListener} <br />
+ * <br />
+ *
+ * E.g. <code>@WebListener</code><br />
+ * <code>public TestListener implements ServletContextListener {</code><br />
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebListener {
+
+ /**
+ * @return description of the listener, if present
+ */
String value() default "";
}
*/
package javax.servlet.annotation;
+import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
-import java.lang.annotation.Documented;
/**
- * @since Servlet 3.0
- * TODO SERVLET3 - Add comments
+ * This annotation is used to declare the configuration of an
+ * {@link javax.servlet.Servlet}. <br/>
+ *
+ * If the name attribute is not defined, the fully qualified name of the class
+ * is used.<br/>
+ * <br/>
+ *
+ * At least one URL pattern MUST be declared in either the {@code value} or
+ * {@code urlPattern} attribute of the annotation, but not both.<br/>
+ * <br/>
+ *
+ * The {@code value} attribute is recommended for use when the URL pattern is
+ * the only attribute being set, otherwise the {@code urlPattern} attribute
+ * should be used.<br />
+ * <br />
+ *
+ * The class on which this annotation is declared MUST extend
+ * {@link javax.servlet.http.HttpServlet}. <br />
+ * <br />
+ *
+ * E.g. <code>@WebServlet("/path")}<br />
+ * public class TestServlet extends HttpServlet ... {</code><br />
+ *
+ * E.g.
+ * <code>@WebServlet(name="TestServlet", urlPatterns={"/path", "/alt"}) <br />
+ * public class TestServlet extends HttpServlet ... {</code><br />
+ *
+ * @since Servlet 3.0 (Section 8.1.1)
+ *
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface WebServlet {
+
+ /**
+ * @return name of the Servlet
+ */
String name() default "";
+
+ /**
+ * A convenience method, to allow extremely simple annotation of a class.
+ *
+ * @return array of URL patterns
+ * @see #urlPatterns()
+ */
String[] value() default {};
+
+ /**
+ * @return array of URL patterns to which this Filter applies
+ */
String[] urlPatterns() default {};
+
+ /**
+ * @return load on startup ordering hint
+ */
int loadOnStartup() default -1;
+
+ /**
+ * @return array of initialization params for this Servlet
+ */
WebInitParam[] initParams() default {};
+
+ /**
+ * @return asynchronous operation supported by this Servlet
+ */
boolean asyncSupported() default false;
+
+ /**
+ * @return small icon for this Servlet, if present
+ */
String smallIcon() default "";
+
+ /**
+ * @return large icon for this Servlet, if present
+ */
String largeIcon() default "";
+
+ /**
+ * @return description of this Servlet, if present
+ */
String description() default "";
+
+ /**
+ * @return display name of this Servlet, if present
+ */
String displayName() default "";
}
projects / tomcat7.0 / commitdiff