From 78748c392ec8582e37b0e343b711406d32bca883 Mon Sep 17 00:00:00 2001 From: markt Date: Mon, 12 Apr 2010 10:34:09 +0000 Subject: [PATCH] Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=49086 Add Javadocs to javax.servlet.annotation Patch provided by Pid. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@933183 13f79535-47bb-0310-9956-ffa450edef68 --- java/javax/servlet/annotation/HandlesTypes.java | 9 ++- java/javax/servlet/annotation/HttpConstraint.java | 35 ++++++++- .../servlet/annotation/HttpMethodConstraint.java | 39 +++++++++- java/javax/servlet/annotation/MultipartConfig.java | 35 ++++++++- java/javax/servlet/annotation/ServletSecurity.java | 47 ++++++++++++- java/javax/servlet/annotation/WebFilter.java | 82 +++++++++++++++++++++- java/javax/servlet/annotation/WebInitParam.java | 25 ++++++- java/javax/servlet/annotation/WebListener.java | 23 +++++- java/javax/servlet/annotation/WebServlet.java | 76 +++++++++++++++++++- 9 files changed, 356 insertions(+), 15 deletions(-) diff --git a/java/javax/servlet/annotation/HandlesTypes.java b/java/javax/servlet/annotation/HandlesTypes.java index f0fc1df37..4818f4f95 100644 --- a/java/javax/servlet/annotation/HandlesTypes.java +++ b/java/javax/servlet/annotation/HandlesTypes.java @@ -22,12 +22,19 @@ import java.lang.annotation.RetentionPolicy; 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(); + } diff --git a/java/javax/servlet/annotation/HttpConstraint.java b/java/javax/servlet/annotation/HttpConstraint.java index 39045074e..2223e9294 100644 --- a/java/javax/servlet/annotation/HttpConstraint.java +++ b/java/javax/servlet/annotation/HttpConstraint.java @@ -24,13 +24,46 @@ import javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic; 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.
+ * 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 {}; + } diff --git a/java/javax/servlet/annotation/HttpMethodConstraint.java b/java/javax/servlet/annotation/HttpMethodConstraint.java index 58b49eb27..4175a7c52 100644 --- a/java/javax/servlet/annotation/HttpMethodConstraint.java +++ b/java/javax/servlet/annotation/HttpMethodConstraint.java @@ -24,14 +24,51 @@ import javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic; 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.
+ * 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 {}; } diff --git a/java/javax/servlet/annotation/MultipartConfig.java b/java/javax/servlet/annotation/MultipartConfig.java index dbd19f571..4b8bb2f54 100644 --- a/java/javax/servlet/annotation/MultipartConfig.java +++ b/java/javax/servlet/annotation/MultipartConfig.java @@ -22,14 +22,47 @@ import java.lang.annotation.RetentionPolicy; 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.
+ *
+ * + * {@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}.
+ *
+ * + * E.g. @WebServlet("/upload")}
+ * + * @MultipartConfig() public class UploadServlet extends + * HttpServlet ... }
+ * * @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; } diff --git a/java/javax/servlet/annotation/ServletSecurity.java b/java/javax/servlet/annotation/ServletSecurity.java index b66b656e9..cebb072c6 100644 --- a/java/javax/servlet/annotation/ServletSecurity.java +++ b/java/javax/servlet/annotation/ServletSecurity.java @@ -24,22 +24,67 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * Declare this annotation on a {@link javax.servlet.Servlet} implementation + * class to enforce security constraints on HTTP protocol requests.
+ * The container applies constraints to the URL patterns mapped to each Servlet + * which declares this annotation.
+ *
+ * * @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 {}; } diff --git a/java/javax/servlet/annotation/WebFilter.java b/java/javax/servlet/annotation/WebFilter.java index bc066252d..aaac99487 100644 --- a/java/javax/servlet/annotation/WebFilter.java +++ b/java/javax/servlet/annotation/WebFilter.java @@ -16,31 +16,107 @@ */ 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}.
+ *
+ * + * 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.
+ *
+ * + * If the name attribute is not defined, the fully qualified name of the class + * is used.
+ *
+ * + * At least one URL pattern MUST be declared in either the {@code value} or + * {@code urlPattern} attribute of the annotation, but not both.
+ *
+ * + * 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.
+ *
+ * + * The annotated class MUST implement {@link javax.servlet.Filter}. + * + * E.g. + * + * @WebFilter("/path/*")
+ * public class AnExampleFilter implements Filter { ...
+ * + * @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; } diff --git a/java/javax/servlet/annotation/WebInitParam.java b/java/javax/servlet/annotation/WebInitParam.java index 9a2315a5c..b99fa1cca 100644 --- a/java/javax/servlet/annotation/WebInitParam.java +++ b/java/javax/servlet/annotation/WebInitParam.java @@ -16,21 +16,42 @@ */ 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.
+ *
+ * + * E.g. + * @WebServlet(name="TestServlet", urlPatterns={"/test"},initParams={@WebInitParam(name="test", value="true")}) + * public class TestServlet extends HttpServlet { ...
+ * * @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 ""; } diff --git a/java/javax/servlet/annotation/WebListener.java b/java/javax/servlet/annotation/WebListener.java index 0463bd6c6..eeed16d4c 100644 --- a/java/javax/servlet/annotation/WebListener.java +++ b/java/javax/servlet/annotation/WebListener.java @@ -16,19 +16,38 @@ */ 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.
+ *
+ * + * 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}
+ *
+ * + * E.g. @WebListener
+ * public TestListener implements ServletContextListener {
+ * * @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 ""; } diff --git a/java/javax/servlet/annotation/WebServlet.java b/java/javax/servlet/annotation/WebServlet.java index 1d3a77978..53f9b4c02 100644 --- a/java/javax/servlet/annotation/WebServlet.java +++ b/java/javax/servlet/annotation/WebServlet.java @@ -16,28 +16,98 @@ */ 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}.
+ * + * If the name attribute is not defined, the fully qualified name of the class + * is used.
+ *
+ * + * At least one URL pattern MUST be declared in either the {@code value} or + * {@code urlPattern} attribute of the annotation, but not both.
+ *
+ * + * 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.
+ *
+ * + * The class on which this annotation is declared MUST extend + * {@link javax.servlet.http.HttpServlet}.
+ *
+ * + * E.g. @WebServlet("/path")}
+ * public class TestServlet extends HttpServlet ... {
+ * + * E.g. + * @WebServlet(name="TestServlet", urlPatterns={"/path", "/alt"})
+ * public class TestServlet extends HttpServlet ... {
+ * + * @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 ""; } -- 2.11.0