Author: remy.maucherat(a)jboss.com
Date: 2009-09-04 06:37:30 -0400 (Fri, 04 Sep 2009)
New Revision: 1162
Modified:
trunk/java/javax/servlet/Registration.java
trunk/java/javax/servlet/ServletContainerInitializer.java
trunk/java/javax/servlet/ServletContext.java
trunk/java/javax/servlet/ServletRequest.java
trunk/java/javax/servlet/annotation/HandlesTypes.java
Log:
- Javadoc update.
Modified: trunk/java/javax/servlet/Registration.java
===================================================================
--- trunk/java/javax/servlet/Registration.java 2009-09-02 12:50:53 UTC (rev 1161)
+++ trunk/java/javax/servlet/Registration.java 2009-09-04 10:37:30 UTC (rev 1162)
@@ -43,6 +43,19 @@
* Interface through which a {@link Servlet} or {@link Filter} may be
* further configured.
*
+ * <p>A Registration object whose {@link #getClassName} method returns null
+ * is considered <i>preliminary</i>. Servlets and Filters whose
implementation
+ * class is container implementation specific may be declared without
+ * any <tt>servlet-class</tt> or <tt>filter-class</tt> elements,
respectively,
+ * and will be represented as preliminary Registration objects.
+ * Preliminary registrations must be completed by calling one of the
+ * <tt>addServlet</tt> or <tt>addFilter</tt> methods on
+ * {@link ServletContext}, and passing in the Servlet or Filter name
+ * (obtained via {@link #getName}) along with the supporting Servlet or Filter
+ * implementation class name, Class object, or instance, respectively.
+ * In most cases, preliminary registrations will be completed by an
+ * appropriate, container-provided {@link ServletContainerInitializer}.
+ *
* @since Servlet 3.0
*/
public interface Registration {
@@ -61,7 +74,8 @@
* is represented by this Registration.
*
* @return the fully qualified class name of the Servlet or Filter
- * that is represented by this Registration
+ * that is represented by this Registration, or null if this
+ * Registration is preliminary
*/
public String getClassName();
Modified: trunk/java/javax/servlet/ServletContainerInitializer.java
===================================================================
--- trunk/java/javax/servlet/ServletContainerInitializer.java 2009-09-02 12:50:53 UTC (rev
1161)
+++ trunk/java/javax/servlet/ServletContainerInitializer.java 2009-09-04 10:37:30 UTC (rev
1162)
@@ -39,14 +39,20 @@
import java.util.Set;
/**
- * Interface which may be implemented by a library/runtime in order
- * to be notified by the container of any of the classes/interfaces
- * in which it has expressed interest via the
- * {@link javax.servlet.annotation.HandlesTypes HandlesTypes} annotation.
+ * Interface which allows a library/runtime to be notified of a web
+ * application's startup phase and perform any required programmatic
+ * registration of servlets, filters, and listeners in response to it.
*
- * <p>If an implementation of this interface does not have any such
- * annotation, the container must pass a <tt>null</tt> set of classes to
- * its {@link #onStartup} method.
+ * <p>Implementations of this interface may be annotated with
+ * {@link javax.servlet.annotation.HandlesTypes HandlesTypes}, in order to
+ * receive (at their {@link #onStartup} method) the Set of application
+ * classes that implement, extend, or have been annotated with the class
+ * types specified by the annotation.
+ *
+ * <p>If an implementation of this interface does not use this annotation,
+ * or none of the application classes match the ones specified
+ * by the annotation, the container must pass a <tt>null</tt> Set of classes
+ * to {@link #onStartup}.
*
* <p>Implementations of this interface may be declared by a JAR file
* resource located inside the <tt>META-INF/services</tt> directory and
@@ -73,14 +79,16 @@
* its <tt>onStartup</tt> method will be invoked every time an
* application is started.
*
- * @param c The set of classes in which this
- * <tt>ServletContainerInitializer</tt> has expressed interest via
- * the <tt>HandlesTypes</tt> annotation, or <tt>null</tt> if
this
- * <tt>ServletContainerInitializer</tt> does not have any such
- * annotation
+ * @param c the Set of application classes that extend, implement, or
+ * have been annotated with the class types specified by the
+ * {@link javax.servlet.annotation.HandlesTypes HandlesTypes} annotation,
+ * or <tt>null</tt> if there are no matches, or this
+ * <tt>ServletContainerInitializer</tt> has not been annotated with
+ * <tt>HandlesTypes</tt>
*
- * @param ctx The <tt>ServletContext</tt> instance in which the types
- * defined via the <tt>HandlesTypes</tt> annotation were found.
+ * @param ctx the <tt>ServletContext</tt> of the web application that
+ * is being started and in which the classes contained in <tt>c</tt>
+ * were found
*
* @throws ServletException if an error has occurred
*/
Modified: trunk/java/javax/servlet/ServletContext.java
===================================================================
--- trunk/java/javax/servlet/ServletContext.java 2009-09-02 12:50:53 UTC (rev 1161)
+++ trunk/java/javax/servlet/ServletContext.java 2009-09-04 10:37:30 UTC (rev 1162)
@@ -743,12 +743,18 @@
* classloader associated with the application represented by this
* ServletContext.
*
+ * <p>If this ServletContext already contains a preliminary
+ * ServletRegistration for a servlet with the given
<tt>servletName</tt>,
+ * it will be completed (by assigning the given <tt>className</tt> to
it)
+ * and returned.
+ *
* @param servletName the name of the servlet
* @param className the fully qualified class name of the servlet
*
* @return a ServletRegistration object that may be used to further
* configure the registered servlet, or <tt>null</tt> if this
- * ServletContext already contains a servlet with a matching name
+ * ServletContext already contains a complete ServletRegistration for
+ * a servlet with the given <tt>servletName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
@@ -772,15 +778,20 @@
* <p>The registered servlet may be further configured via the returned
* {@link ServletRegistration} object.
*
+ * <p>If this ServletContext already contains a preliminary
+ * ServletRegistration for a servlet with the given
<tt>servletName</tt>,
+ * it will be completed (by assigning the class name of the given servlet
+ * instance to it) and returned.
+ *
* @param servletName the name of the servlet
* @param servlet the servlet instance to register
*
* @return a ServletRegistration object that may be used to further
* configure the given servlet, or <tt>null</tt> if this
- * ServletContext already contains a servlet with a matching name,
- * or if the same servlet instance has already been registered with
- * this or another ServletContext that is part of the same servlet
- * container
+ * ServletContext already contains a complete ServletRegistration for a
+ * servlet with the given <tt>servletName</tt> or if the same servlet
+ * instance has already been registered with this or another
+ * ServletContext in the same container
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
@@ -807,13 +818,19 @@
* <p>The registered servlet may be further configured via the returned
* {@link ServletRegistration} object.
*
+ * <p>If this ServletContext already contains a preliminary
+ * ServletRegistration for a servlet with the given
<tt>servletName</tt>,
+ * it will be completed (by assigning the name of the given
+ * <tt>servletClass</tt> to it) and returned.
+ *
* @param servletName the name of the servlet
* @param servletClass the class object from which the servlet will be
* instantiated
*
* @return a ServletRegistration object that may be used to further
* configure the registered servlet, or <tt>null</tt> if this
- * ServletContext already contains a servlet with a matching name
+ * ServletContext already contains a complete ServletRegistration for
+ * the given <tt>servletName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
@@ -831,14 +848,18 @@
/**
- * Instantiates the given Servlet class and performs any required
- * resource injection into the new Servlet instance before returning
- * it.
+ * Instantiates the given Servlet class.
*
+ * <p>This method must support all annotations applicable to Servlets
+ * as defined by the Servlet specification.
+ *
* <p>The returned Servlet instance may be further customized before it
* is registered with this ServletContext via a call to
* {@link #addServlet(String,Servlet)}.
*
+ * <p>The given Servlet class must define a zero argument constructor,
+ * which is used to instantiate it.
+ *
* @param clazz the Servlet class to instantiate
*
* @return the new Servlet instance
@@ -861,9 +882,9 @@
* Gets the ServletRegistration corresponding to the servlet with the
* given <tt>servletName</tt>.
*
- * @return the ServletRegistration corresponding to the servlet with the
- * given <tt>servletName</tt>, or null if no ServletRegistration exists
- * under that name in this ServletContext
+ * @return the (complete or preliminary) ServletRegistration for the
+ * servlet with the given <tt>servletName</tt>, or null if no
+ * ServletRegistration exists under that name
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
@@ -889,8 +910,9 @@
* <p>Any changes to the returned Map must not affect this
* ServletContext.
*
- * @return Map of the ServletRegistration objects corresponding
- * to all servlets currently registered with this ServletContext
+ * @return Map of the (complete and preliminary) ServletRegistration
+ * objects corresponding to all servlets currently registered with this
+ * ServletContext
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
@@ -914,12 +936,18 @@
* classloader associated with the application represented by this
* ServletContext.
*
+ * <p>If this ServletContext already contains a preliminary
+ * FilterRegistration for a filter with the given <tt>filterName</tt>,
+ * it will be completed (by assigning the given <tt>className</tt> to
it)
+ * and returned.
+ *
* @param filterName the name of the filter
* @param className the fully qualified class name of the filter
*
* @return a FilterRegistration object that may be used to further
* configure the registered filter, or <tt>null</tt> if this
- * ServletContext already contains a filter with a matching name
+ * ServletContext already contains a complete FilterRegistration for
+ * a filter with the given <tt>filterName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
@@ -943,15 +971,20 @@
* <p>The registered filter may be further configured via the returned
* {@link FilterRegistration} object.
*
+ * <p>If this ServletContext already contains a preliminary
+ * FilterRegistration for a filter with the given <tt>filterName</tt>,
+ * it will be completed (by assigning the class name of the given filter
+ * instance to it) and returned.
+ *
* @param filterName the name of the filter
* @param filter the filter instance to register
*
* @return a FilterRegistration object that may be used to further
* configure the given filter, or <tt>null</tt> if this
- * ServletContext already contains a filter with a matching name,
- * or if the same filter instance has already been registered with
- * this or another ServletContext that is part of the same servlet
- * container
+ * ServletContext already contains a complete FilterRegistration for a
+ * filter with the given <tt>filterName</tt> or if the same filter
+ * instance has already been registered with this or another
+ * ServletContext in the same container
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
@@ -975,13 +1008,19 @@
* <p>The registered filter may be further configured via the returned
* {@link FilterRegistration} object.
*
+ * <p>If this ServletContext already contains a preliminary
+ * FilterRegistration for a filter with the given <tt>filterName</tt>,
+ * it will be completed (by assigning the name of the given
+ * <tt>filterClass</tt> to it) and returned.
+ *
* @param filterName the name of the filter
* @param filterClass the class object from which the filter will be
* instantiated
*
* @return a FilterRegistration object that may be used to further
* configure the registered filter, or <tt>null</tt> if this
- * ServletContext already contains a filter with a matching name
+ * ServletContext already contains a complete FilterRegistration for a
+ * filter with the given <tt>filterName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
@@ -999,14 +1038,18 @@
/**
- * Instantiates the given Filter class and performs any required
- * resource injection into the new Filter instance before returning
- * it.
+ * Instantiates the given Filter class.
*
+ * <p>This method must support all annotations applicable to Filters
+ * as defined by the Servlet specification.
+ *
* <p>The returned Filter instance may be further customized before it
* is registered with this ServletContext via a call to
* {@link #addFilter(String,Filter)}.
*
+ * <p>The given Filter class must define a zero argument constructor,
+ * which is used to instantiate it.
+ *
* @param clazz the Filter class to instantiate
*
* @return the new Filter instance
@@ -1030,9 +1073,9 @@
* Gets the FilterRegistration corresponding to the filter with the
* given <tt>filterName</tt>.
*
- * @return the FilterRegistration corresponding to the filter with the
- * given <tt>filterName</tt>, or null if no FilterRegistration exists
- * under that name in this ServletContext
+ * @return the (complete or preliminary) FilterRegistration for the
+ * filter with the given <tt>filterName</tt>, or null if no
+ * FilterRegistration exists under that name
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
@@ -1058,8 +1101,9 @@
* <p>Any changes to the returned Map must not affect this
* ServletContext.
*
- * @return Map of the FilterRegistration objects corresponding
- * to all filters currently registered with this ServletContext
+ * @return Map of the (complete and preliminary) FilterRegistration
+ * objects corresponding to all filters currently registered with this
+ * ServletContext
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
@@ -1318,9 +1362,7 @@
/**
- * Instantiates the given EventListener class and performs any
- * required resource injection into the new EventListener instance
- * before returning it.
+ * Instantiates the given EventListener class.
*
* <p>The specified EventListener class must implement at least one of
* the <code>{@link ServletContextListener}</code>,
@@ -1331,10 +1373,16 @@
* <code>{@link javax.servlet.http.HttpSessionAttributeListener}</code>
* interfaces.
*
+ * <p>This method must support all annotations applicable to the above
+ * listener interfaces as defined by the Servlet specification.
+ *
* <p>The returned EventListener instance may be further customized
* before it is registered with this ServletContext via a call to
* {@link #addListener(EventListener)}.
*
+ * <p>The given EventListener class must define a zero argument
+ * constructor, which is used to instantiate it.
+ *
* @param clazz the EventListener class to instantiate
*
* @return the new EventListener instance
Modified: trunk/java/javax/servlet/ServletRequest.java
===================================================================
--- trunk/java/javax/servlet/ServletRequest.java 2009-09-02 12:50:53 UTC (rev 1161)
+++ trunk/java/javax/servlet/ServletRequest.java 2009-09-04 10:37:30 UTC (rev 1162)
@@ -56,14 +56,9 @@
package javax.servlet;
-import java.io.BufferedReader;
-import java.io.IOException;
-import java.util.Enumeration;
-import java.util.Locale;
-import java.util.Map;
+import java.io.*;
+import java.util.*;
-
-
/**
* Defines an object to provide client request information to a servlet. The
* servlet container creates a <code>ServletRequest</code> object and passes
@@ -83,9 +78,6 @@
public interface ServletRequest {
-
-
-
/**
*
* Returns the value of the named attribute as an <code>Object</code>,
@@ -157,12 +149,12 @@
*
* @param env <code>String</code> containing the name of
* the character encoding.
- * @throws java.io.UnsupportedEncodingException if this
+ * @throws UnsupportedEncodingException if this
* ServletRequest is still in a state where a
* character encoding may be set, but the specified
* encoding is invalid
*/
- public void setCharacterEncoding(String env) throws
java.io.UnsupportedEncodingException;
+ public void setCharacterEncoding(String env) throws UnsupportedEncodingException;
Modified: trunk/java/javax/servlet/annotation/HandlesTypes.java
===================================================================
--- trunk/java/javax/servlet/annotation/HandlesTypes.java 2009-09-02 12:50:53 UTC (rev
1161)
+++ trunk/java/javax/servlet/annotation/HandlesTypes.java 2009-09-04 10:37:30 UTC (rev
1162)
@@ -44,8 +44,9 @@
import java.lang.annotation.RetentionPolicy;
/**
- * This annotation is used to declare the types an instance of the
- * ServletContainerInitializer can handle.
+ * This annotation is used to declare the class types that a
+ * {@link javax.servlet.ServletContainerInitializer
+ * ServletContainerInitializer} can handle.
*
* @see javax.servlet.ServletContainerInitializer
*
@@ -54,11 +55,18 @@
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface HandlesTypes {
+
/**
- * The types that a <tt>ServletContainerInitializer</tt> expresses
interesst in. When this annotation
- * is applied on an implementation of
<tt>ServletContainerInitializer</tt> the <tt>onStartup</tt>
method
- * of the ServletContainerInitializer instance will get a <tt>Set</tt> of
classes that were either annotated
- * with, or extends / implements the types listed via this annotation.
+ * The classes in which a {@link javax.servlet.ServletContainerInitializer
+ * ServletContainerInitializer} has expressed interest.
+ *
+ * <p>If an implementation of <tt>ServletContainerInitializer</tt>
+ * specifies this annotation, the Servlet container must pass the
+ * <tt>Set</tt> of application classes that extend, implement, or have
+ * been annotated with the class types listed by this annotation to
+ * the {@link javax.servlet.ServletContainerInitializer#onStartup}
+ * method of the ServletContainerInitializer (if no matching classes
+ * are found, <tt>null</tt> must be passed instead)
*/
Class[] value();
}