6:25 a.m.
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><absolute-file-path-on-disk>/WEB-INF/lib/<name-of-jar>!/META-INF/resources/<path></tt>,
- * where <tt><path></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"));