Author: remy.maucherat(a)jboss.com Date: 2009-06-03 07:25:08 -0400 (Wed, 03 Jun 2009) New Revision: 1075 Modified: trunk/java/javax/servlet/ServletContainerInitializer.java trunk/java/javax/servlet/ServletContext.java trunk/java/javax/servlet/annotation/MultipartConfig.java trunk/java/javax/servlet/http/HttpServletRequest.java trunk/java/javax/servlet/http/HttpServletRequestWrapper.java trunk/java/org/apache/catalina/connector/Request.java trunk/java/org/apache/catalina/connector/RequestFacade.java Log: - Update the API (super minor). Modified: trunk/java/javax/servlet/ServletContainerInitializer.java =================================================================== --- trunk/java/javax/servlet/ServletContainerInitializer.java 2009-06-02 16:17:09 UTC (rev 1074) +++ trunk/java/javax/servlet/ServletContainerInitializer.java 2009-06-03 11:25:08 UTC (rev 1075) @@ -40,13 +40,20 @@ import java.util.Set; /** - * An implementation of this interface can be provided by a library / - * runtime to get notified by the container for the classes / interfaces - * that it expresses interest via the <tt>@HandlesTypes</tt> annotation. If - * there is no <tt>@HandlesTypes</tt> annotation on an implementation of this - * interface, the container MUST invoke the <tt>onStartup</tt> method once for - * every webapp passing it a <tt>null</tt> set of classes. + * 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. * + * <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 declared by a JAR file + * resource located inside the <tt>META-INF/services</tt> directory and + * named for the fully qualified class name of this interface, and will be + * discovered using the runtime's service provider lookup mechanism. + * * @see javax.servlet.annotation.HandlesTypes * * @since Servlet 3.0 @@ -54,12 +61,27 @@ public interface ServletContainerInitializer { /** - * @param c The set of classes that an implementation of ServletContainerInitializer expressed interest on - * via the <tt>HandlesTypes</tt> annotation. If there is no <tt>HandlesTypes</tt> annotation on the implementation - * of the ServletContainerInitializer, a <tt>null</tt> set of classes will be passed + * Notifies this <tt>ServletContainerInitializer</tt> of the startup + * of the application represented by the given <tt>ServletContext</tt>. * - * @param ctx The <tt>ServletContext</tt> instance in which the types defined via the <tt>HandlesTypes</tt> - * are found. + * <p>If this <tt>ServletContainerInitializer</tt> is bundled in a JAR + * file inside the <tt>WEB-INF/lib</tt> directory of an application, + * its <tt>onStartup</tt> method will be invoked only once during the + * startup of the bundling application. If this + * <tt>ServletContainerInitializer</tt> is bundled inside a JAR file + * outside of any <tt>WEB-INF/lib</tt> directory, but still + * discoverable by the runtime's service provider lookup mechanism, + * 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 ctx The <tt>ServletContext</tt> instance in which the types + * defined via the <tt>HandlesTypes</tt> annotation were found. */ public void onStartup(Set<Class<?>> c, ServletContext ctx); } Modified: trunk/java/javax/servlet/ServletContext.java =================================================================== --- trunk/java/javax/servlet/ServletContext.java 2009-06-02 16:17:09 UTC (rev 1074) +++ trunk/java/javax/servlet/ServletContext.java 2009-06-03 11:25:08 UTC (rev 1075) @@ -471,13 +471,13 @@ * appropriate to the computer and operating system on * which the servlet container is running, including the * proper path separators. - * Paths to resources located inside the <tt>/META-INF/resources</tt> - * directory of a JAR file inside the application's <tt>/WEB-INF/lib</tt> - * directory are returned using this format: - * <tt>&lt;absolute-file-path-on-disk&gt;/WEB-INF/lib/&lt;name-of-jar&gt;!/META-INF/resources/&lt;path&gt;</tt>, - * where <tt>&lt;path&gt;</tt> corresponds to the <tt>path</tt> - * argument passed to this method. * + * <p>Resources inside the <tt>/META-INF/resources</tt> + * directories of JAR files bundled in the application's + * <tt>/WEB-INF/lib</tt> directory must be considered only if the + * container has unpacked them from their containing JAR file, in + * which case the path to the unpacked location must be returned. + * * <p>This method returns <code>null</code> if the servlet container * is unable to translate the given <i>virtual</i> path to a * <i>real</i> path. Modified: trunk/java/javax/servlet/annotation/MultipartConfig.java =================================================================== --- trunk/java/javax/servlet/annotation/MultipartConfig.java 2009-06-02 16:17:09 UTC (rev 1074) +++ trunk/java/javax/servlet/annotation/MultipartConfig.java 2009-06-03 11:25:08 UTC (rev 1075) @@ -47,25 +47,26 @@ /** * The directory location where files will be stored - * */ String location() default ""; /** - * the maximum size allowed for files uploaded - * + * The maximum size allowed for uploaded files. + * + * <p>The default is <tt>-1L</tt>, which means unlimited. */ - long maxFileSize() default 0L; + long maxFileSize() default -1L; /** - * The maximum size of a multi-part/form-data request allowed - * + * The maximum size allowed for <tt>multipart/form-data</tt> + * requests + * + * <p>The default is <tt>-1L</tt>, which means unlimited. */ - long maxRequestSize() default 0L; + long maxRequestSize() default -1L; /** * The size threshold after which the file will be written to disk - * */ int fileSizeThreshold() default 0; } Modified: trunk/java/javax/servlet/http/HttpServletRequest.java =================================================================== --- trunk/java/javax/servlet/http/HttpServletRequest.java 2009-06-02 16:17:09 UTC (rev 1074) +++ trunk/java/javax/servlet/http/HttpServletRequest.java 2009-06-03 11:25:08 UTC (rev 1075) @@ -737,6 +737,8 @@ * NOT establish the message and * HTTP status code to be returned * to the user). + * + * @since Servlet 3.0 */ public boolean authenticate(HttpServletResponse response) throws IOException,ServletException; @@ -776,6 +778,8 @@ * to the call to login), or if * validation of the provided * username and password fails. + * + * @since Servlet 3.0 */ public void login(String username, String password) throws ServletException; @@ -786,30 +790,59 @@ * <code>getUserPrincipal</code>, <code>getRemoteUser</code>, * and <code>getAuthType</code> is called on the request. * - * @exception ServletException ff logout fails. + * @exception ServletException if logout fails + * + * @since Servlet 3.0 */ public void logout() throws ServletException; + /** - * Retrieves all the parts of the multi-part/form-data http message + * Gets all the {@link Part} components of this request, provided + * that it is of type <tt>multipart/form-data</tt>. * - * @return An <code>Iterable</code> for all the parts of the multi-part/form-data request + * <p>If this request is of type <tt>multipart/form-data</tt>, but + * does not contain any Part components, the returned + * <tt>Iterable</tt> will be empty. + * + * @return A (possibly empty) <code>Iterable</code> over all the + * Part components of this request + * + * @throws ServletException if this request is not of type + * <tt>multipart/form-data</tt> + * @throws IllegalStateException if the request body is larger than + * <tt>maxRequestSize</tt>, or any Part in the request is larger than + * <tt>maxFileSize</tt> + * + * @see javax.servlet.annotation.MultipartConfig#maxFileSize + * @see javax.servlet.annotation.MultipartConfig#maxRequestSize + * + * @since Servlet 3.0 */ - public Iterable<Part> getParts(); + public Iterable<Part> getParts() throws ServletException; + /** - * Returns the part specified by the name. + * Gets the {@link Part} with the given name. * - * @param name the name of the part - * @return The part being requested for by name. - * @exception IllegalArgumentException If the name specified does not exist + * @param name the name of the requested Part * + * @return The Part with the given name, or <tt>null</tt> if this + * request is of type <tt>multipart/form-data</tt>, but does not + * contain the requested Part + * + * @throws ServletException if this request is not of type + * <tt>multipart/form-data</tt> + * @throws IllegalStateException if the request body is larger than + * <tt>maxRequestSize</tt>, or any Part in the request is larger than + * <tt>maxFileSize</tt> + * + * @see javax.servlet.annotation.MultipartConfig#maxFileSize + * @see javax.servlet.annotation.MultipartConfig#maxRequestSize + * + * @since Servlet 3.0 */ - public Part getPart(String name) throws IllegalArgumentException; - - - - + public Part getPart(String name) throws ServletException; } Modified: trunk/java/javax/servlet/http/HttpServletRequestWrapper.java =================================================================== --- trunk/java/javax/servlet/http/HttpServletRequestWrapper.java 2009-06-02 16:17:09 UTC (rev 1074) +++ trunk/java/javax/servlet/http/HttpServletRequestWrapper.java 2009-06-03 11:25:08 UTC (rev 1075) @@ -303,6 +303,8 @@ /** * The default behavior of this method is to call authenticate on the * wrapped request object. + * + * @since Servlet 3.0 */ public boolean authenticate(HttpServletResponse response) throws IOException, ServletException { @@ -312,7 +314,9 @@ /** * The default behavior of this method is to call login on the wrapped - * request object + * request object. + * + * @since Servlet 3.0 */ public void login(String username, String password) throws ServletException { @@ -322,33 +326,33 @@ /** * The default behavior of this method is to call login on the wrapped - * request object + * request object. + * + * @since Servlet 3.0 */ public void logout() throws ServletException { this._getHttpServletRequest().logout(); } /** - * Retrieves all the parts of the multi-part/form-data http message + * The default behavior of this method is to call getParts on the wrapped + * request object. * - * @return An <code>Iterable</code> for all the parts of the multi-part/form-data request + * @since Servlet 3.0 */ - public Iterable<Part> getParts() { + public Iterable<Part> getParts() throws ServletException { return this._getHttpServletRequest().getParts(); } /** - * Returns the part specified by the name. + * The default behavior of this method is to call getPart on the wrapped + * request object. * - * @param name the name of the part - * @return The part being requested for by name. - * @exception IllegalArgumentException If the name specified does not exist - * + * @since Servlet 3.0 */ - public Part getPart(String name) throws IllegalArgumentException { + public Part getPart(String name) throws ServletException { return this._getHttpServletRequest().getPart(name); } - } Modified: trunk/java/org/apache/catalina/connector/Request.java =================================================================== --- trunk/java/org/apache/catalina/connector/Request.java 2009-06-02 16:17:09 UTC (rev 1074) +++ trunk/java/org/apache/catalina/connector/Request.java 2009-06-03 11:25:08 UTC (rev 1075) @@ -3041,20 +3041,21 @@ } - public Part getPart(String name) throws IllegalArgumentException { + public Part getPart(String name) throws ServletException { if (parts == null) { parseMultipart(); } Part result = parts.get(name); if (result == null) { - throw new IllegalArgumentException(); + // FIXME: error message + throw new ServletException(); } else { return result; } } - public Iterable<Part> getParts() { + public Iterable<Part> getParts() throws ServletException { if (parts == null) { parseMultipart(); } Modified: trunk/java/org/apache/catalina/connector/RequestFacade.java =================================================================== --- trunk/java/org/apache/catalina/connector/RequestFacade.java 2009-06-02 16:17:09 UTC (rev 1074) +++ trunk/java/org/apache/catalina/connector/RequestFacade.java 2009-06-03 11:25:08 UTC (rev 1075) @@ -1122,7 +1122,7 @@ } - public Part getPart(String name) throws IllegalArgumentException { + public Part getPart(String name) throws ServletException { if (request == null) { throw new IllegalStateException( sm.getString("requestFacade.nullRequest")); @@ -1132,7 +1132,7 @@ } - public Iterable<Part> getParts() { + public Iterable<Part> getParts() throws ServletException { if (request == null) { throw new IllegalStateException( sm.getString("requestFacade.nullRequest"));