[jbossweb-commits] JBossWeb SVN: r1162 - in trunk/java/javax/servlet: annotation and 1 other directory.

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(); }