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"},initparam...@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: [email protected]
For additional commands, e-mail: [email protected]
