Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Tomcat Developers List" <dev@tomcat.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r933183 - in /tomcat/trunk/java/javax/servlet/annotation:
 HandlesTypes.java HttpConstraint.java HttpMethodConstraint.java
 MultipartConfig.java ServletSecurity.java WebFilter.java WebInitParam.java
 WebListener.java WebServlet.java
Date: Mon, 12 Apr 2010 10:34:09 -0000
To: dev@tomcat.apache.org
From: markt@apache.org
Message-Id: <20100412103409.F048923889BB@eris.apache.org>

Author: markt
Date: Mon Apr 12 10:34:09 2010
New Revision: 933183

URL: http://svn.apache.org/viewvc?rev=933183&view=rev
Log:
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=49086
Add Javadocs to javax.servlet.annotation
Patch provided by Pid.

Modified:
    tomcat/trunk/java/javax/servlet/annotation/HandlesTypes.java
    tomcat/trunk/java/javax/servlet/annotation/HttpConstraint.java
    tomcat/trunk/java/javax/servlet/annotation/HttpMethodConstraint.java
    tomcat/trunk/java/javax/servlet/annotation/MultipartConfig.java
    tomcat/trunk/java/javax/servlet/annotation/ServletSecurity.java
    tomcat/trunk/java/javax/servlet/annotation/WebFilter.java
    tomcat/trunk/java/javax/servlet/annotation/WebInitParam.java
    tomcat/trunk/java/javax/servlet/annotation/WebListener.java
    tomcat/trunk/java/javax/servlet/annotation/WebServlet.java

Modified: tomcat/trunk/java/javax/servlet/annotation/HandlesTypes.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/HandlesTypes.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/HandlesTypes.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/HandlesTypes.java Mon Apr 12 10:34:09 2010
@@ -22,12 +22,19 @@ import java.lang.annotation.RetentionPol
 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();
+
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/HttpConstraint.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/HttpConstraint.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/HttpConstraint.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/HttpConstraint.java Mon Apr 12 10:34:09 2010
@@ -24,13 +24,46 @@ import javax.servlet.annotation.ServletS
 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 {};
+
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/HttpMethodConstraint.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/HttpMethodConstraint.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/HttpMethodConstraint.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/HttpMethodConstraint.java Mon Apr 12 10:34:09 2010
@@ -24,14 +24,51 @@ import javax.servlet.annotation.ServletS
 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 {};
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/MultipartConfig.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/MultipartConfig.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/MultipartConfig.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/MultipartConfig.java Mon Apr 12 10:34:09 2010
@@ -22,14 +22,47 @@ import java.lang.annotation.RetentionPol
 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;
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/ServletSecurity.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/ServletSecurity.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/ServletSecurity.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/ServletSecurity.java Mon Apr 12 10:34:09 2010
@@ -24,22 +24,67 @@ import java.lang.annotation.RetentionPol
 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 {};
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/WebFilter.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/WebFilter.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/WebFilter.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/WebFilter.java Mon Apr 12 10:34:09 2010
@@ -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}. <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;
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/WebInitParam.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/WebInitParam.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/WebInitParam.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/WebInitParam.java Mon Apr 12 10:34:09 2010
@@ -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.<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 "";
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/WebListener.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/WebListener.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/WebListener.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/WebListener.java Mon Apr 12 10:34:09 2010
@@ -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.<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 "";
 }

Modified: tomcat/trunk/java/javax/servlet/annotation/WebServlet.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/javax/servlet/annotation/WebServlet.java?rev=933183&r1=933182&r2=933183&view=diff
==============================================================================
--- tomcat/trunk/java/javax/servlet/annotation/WebServlet.java (original)
+++ tomcat/trunk/java/javax/servlet/annotation/WebServlet.java Mon Apr 12 10:34:09 2010
@@ -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}. <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 "";
 }


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org