Hi,
The attached file is updates to the Servlet 2.4 API and XML Schema.
Changes are:
jsr154/src/share/dtd/web-app_2_4.xsd
- Arbitrary order of sub elements under <web-app>
- Reformatted indentation
jsr154/src/share/javax/servlet/ServletContext.java
- Change "2.3" to "2.4" in getMajorVersion() and getMinorVersion()
jsr154/src/share/javax/servlet/ServletContextAttributeListener.java
- Fix typo
jsr154/src/share/javax/servlet/ServletContextListener.java
- Clarification of contextInitialized() and contextDestroyed()
jsr154/src/share/javax/servlet/ServletRequest.java
- Clarification of getServerName(), getServerPort(), getRemoteAddr()
getRemoteHost(), getRequestDispatcher()
- Add @return in the latest addition of getLocaleName(), getLocalAddr(),
and getLocalPort()
jsr154/src/share/javax/servlet/ServletRequestWrapper.java
- Fix the inappropriate comments of the getLocalName(), getLocalAddr(),
and getLocalPort()
jsr154/src/share/javax/servlet/ServletResponse.java
- Internationalization clarification
jsr154/src/share/javax/servlet/SingleThreadModel.java
- Deprecate SingleThreadModel
jsr154/src/share/javax/servlet/http/HttpServlet.java
- Change the URL of HTTP/1.1 to RFC2616
jsr154/src/share/javax/servlet/http/HttpServletRequest.java
- Allow vendor specific auth type in getAuthType()
- Clarification of getHeader(), getPathInfo(), getPathTranslated(),
getRequestedSessionId(), getServletPath()
jsr154/src/share/javax/servlet/http/HttpServletResponse.java
- Clarification of sendError()
- Add recommendation of RFC2047 in setHeader() and addHeader()
jsr154/src/share/javax/servlet/http/HttpSessionListener.java
- Change the sessionDestroyed() to notify *before* the session
is invalidated.
--------------
Yutaka Yoshida
Java/XML Software Group
Sun Microsystems Inc.
Index: jsr154/src/share/dtd/web-app_2_4.xsd
===================================================================
RCS file: /home/cvspublic/jakarta-servletapi-5/jsr154/src/share/dtd/web-app_2_4.xsd,v
retrieving revision 1.8
diff -u -r1.8 web-app_2_4.xsd
--- jsr154/src/share/dtd/web-app_2_4.xsd 14 Feb 2003 19:34:44 -0000 1.8
+++ jsr154/src/share/dtd/web-app_2_4.xsd 5 Mar 2003 03:33:16 -0000
@@ -8,7 +8,7 @@
version="2.4">
<xsd:annotation>
<xsd:documentation>
- @(#)web-app_2_4.xsds 1.54 03/02/11
+ @(#)web-app_2_4.xsds 1.55 03/02/19
</xsd:documentation>
</xsd:annotation>
@@ -109,7 +109,19 @@
<xsd:documentation>
The web-app element is the root of the deployment
- descriptor for a web application.
+ descriptor for a web application. Note that the sub-elements
+ of this element can be in the arbitrary order. Because of
+ that, the multiplicity of the elements of distributable,
+ session-config, welcome-file-list, jsp-config, login-config,
+ and locale-encoding-mapping-list was changed from "?" to "*"
+ in this schema. However, the deployment descriptor instance
+ file must not contain multiple elements of session-config,
+ jsp-config, and login-config. When there are multiple elements of
+ welcome-file-list or locale-encoding-mapping-list, the container
+ must concatinate the element contents. The multiple occurance
+ of the element distributable is redundant and the container
+ treats that case exactly in the same way when there is only
+ one distributable.
</xsd:documentation>
</xsd:annotation>
@@ -1119,14 +1131,13 @@
<xsd:complexType name="web-appType">
- <xsd:sequence>
+ <xsd:choice minOccurs="0" maxOccurs="unbounded">
<xsd:group ref="j2ee:descriptionGroup"/>
<xsd:element name="distributable"
- type="j2ee:emptyType"
- minOccurs="0"/>
+ type="j2ee:emptyType"/>
<xsd:element name="context-param"
- type="j2ee:param-valueType"
- minOccurs="0" maxOccurs="unbounded">
+ type="j2ee:param-valueType">
+
<xsd:annotation>
<xsd:documentation>
@@ -1139,62 +1150,37 @@
</xsd:element>
<xsd:element name="filter"
- type="j2ee:filterType"
- minOccurs="0" maxOccurs="unbounded"/>
+ type="j2ee:filterType"/>
<xsd:element name="filter-mapping"
- type="j2ee:filter-mappingType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:filter-mappingType"/>
<xsd:element name="listener"
- type="j2ee:listenerType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:listenerType"/>
<xsd:element name="servlet"
- type="j2ee:servletType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:servletType"/>
<xsd:element name="servlet-mapping"
- type="j2ee:servlet-mappingType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:servlet-mappingType"/>
<xsd:element name="session-config"
- type="j2ee:session-configType"
- minOccurs="0"/>
+ type="j2ee:session-configType"/>
<xsd:element name="mime-mapping"
- type="j2ee:mime-mappingType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:mime-mappingType"/>
<xsd:element name="welcome-file-list"
- type="j2ee:welcome-file-listType"
- minOccurs="0"/>
+ type="j2ee:welcome-file-listType"/>
<xsd:element name="error-page"
- type="j2ee:error-pageType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:error-pageType"/>
<xsd:element name="jsp-config"
- type="j2ee:jsp-configType"
- minOccurs="0"/>
+ type="j2ee:jsp-configType"/>
<xsd:element name="security-constraint"
- type="j2ee:security-constraintType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:security-constraintType"/>
<xsd:element name="login-config"
- type="j2ee:login-configType"
- minOccurs="0"/>
+ type="j2ee:login-configType"/>
<xsd:element name="security-role"
- type="j2ee:security-roleType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:security-roleType"/>
<xsd:group ref="j2ee:jndiEnvironmentRefsGroup"/>
<xsd:element name="message-destination"
- type="j2ee:message-destinationType"
- minOccurs="0"
- maxOccurs="unbounded"/>
+ type="j2ee:message-destinationType"/>
<xsd:element name="locale-encoding-mapping-list"
- type="j2ee:locale-encoding-mapping-listType"
- minOccurs="0"
- maxOccurs="1"/>
- </xsd:sequence>
+ type="j2ee:locale-encoding-mapping-listType"/>
+ </xsd:choice>
<xsd:attribute name="version"
type="j2ee:web-app-versionType"
Index: jsr154/src/share/javax/servlet/ServletContext.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/ServletContext.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 ServletContext.java
--- jsr154/src/share/javax/servlet/ServletContext.java 13 Aug 2002 16:21:43 -0000
1.1.1.1
+++ jsr154/src/share/javax/servlet/ServletContext.java 5 Mar 2003 03:33:17 -0000
@@ -133,7 +133,7 @@
/**
* Returns the major version of the Java Servlet API that this
* servlet container supports. All implementations that comply
- * with Version 2.3 must have this method
+ * with Version 2.4 must have this method
* return the integer 2.
*
* @return 2
@@ -147,10 +147,10 @@
/**
* Returns the minor version of the Servlet API that this
* servlet container supports. All implementations that comply
- * with Version 2.3 must have this method
- * return the integer 3.
+ * with Version 2.4 must have this method
+ * return the integer 4.
*
- * @return 3
+ * @return 4
*
*/
Index: jsr154/src/share/javax/servlet/ServletContextAttributeListener.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/ServletContextAttributeListener.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 ServletContextAttributeListener.java
--- jsr154/src/share/javax/servlet/ServletContextAttributeListener.java 13 Aug 2002
16:21:43 -0000 1.1.1.1
+++ jsr154/src/share/javax/servlet/ServletContextAttributeListener.java 5 Mar 2003
03:33:17 -0000
@@ -13,7 +13,7 @@
public interface ServletContextAttributeListener extends EventListener {
/** Notification that a new attribute was added to the servlet context. Called
after the attribute is added.*/
public void attributeAdded(ServletContextAttributeEvent scab);
- /** Notification that an existing attribute has been remved from the servlet
context. Called after the attribute is removed.*/
+ /** Notification that an existing attribute has been removed from the servlet
context. Called after the attribute is removed.*/
public void attributeRemoved(ServletContextAttributeEvent scab);
/** Notification that an attribute on the servlet context has been replaced.
Called after the attribute is replaced. */
public void attributeReplaced(ServletContextAttributeEvent scab);
Index: jsr154/src/share/javax/servlet/ServletContextListener.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/ServletContextListener.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 ServletContextListener.java
--- jsr154/src/share/javax/servlet/ServletContextListener.java 13 Aug 2002 16:21:43
-0000 1.1.1.1
+++ jsr154/src/share/javax/servlet/ServletContextListener.java 5 Mar 2003 03:33:17
-0000
@@ -71,11 +71,18 @@
*/
public interface ServletContextListener extends EventListener {
- /** Notification that the web application is ready to process requests.*/
+ /** Notification that the web application initialization
+ ** process is starting.
+ ** All ServletContextListeners are notified of context
+ ** initialisation before any filter or servlet in the web
+ ** application is initialized.
+ */
public void contextInitialized ( ServletContextEvent sce );
- /** Notification that the servlet context is about to be shut down. */
+ /** Notification that the servlet context is about to be shut down. All
servlets
+ have been dstroy()ed before any ServletContextListeners are notified of context
+ destruction. */
public void contextDestroyed ( ServletContextEvent sce );
}
Index: jsr154/src/share/javax/servlet/ServletRequest.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/ServletRequest.java,v
retrieving revision 1.2
diff -u -r1.2 ServletRequest.java
--- jsr154/src/share/javax/servlet/ServletRequest.java 5 Mar 2003 02:20:46 -0000
1.2
+++ jsr154/src/share/javax/servlet/ServletRequest.java 5 Mar 2003 03:33:17 -0000
@@ -350,12 +350,12 @@
/**
- * Returns the host name of the server that received the request.
- * For HTTP servlets, same as the value of the CGI variable
- * <code>SERVER_NAME</code>.
+ * Returns the host name of the server to which the request was sent.
+ * It is the value of the part before ":" in the <code>Host</code>
+ * header, if any, or the resolved server name, or the server IP address.
*
* @return a <code>String</code> containing the name
- * of the server to which the request was sent
+ * of the server
*/
public String getServerName();
@@ -364,9 +364,10 @@
/**
- * Returns the port number on which this request was received.
- * For HTTP servlets, same as the value of the CGI variable
- * <code>SERVER_PORT</code>.
+ * Returns the port number to which the request was sent.
+ * It is the value of the part after ":" in the <code>Host</code>
+ * header, if any, or the server port where the client connection
+ * was accepted on.
*
* @return an integer specifying the port number
*
@@ -407,7 +408,8 @@
/**
* Returns the Internet Protocol (IP) address of the client
- * that sent the request. For HTTP servlets, same as the value of the
+ * or last proxy that sent the request.
+ * For HTTP servlets, same as the value of the
* CGI variable <code>REMOTE_ADDR</code>.
*
* @return a <code>String</code> containing the
@@ -421,14 +423,15 @@
/**
- * Returns the fully qualified name of the client that sent the
- * request. If the engine cannot or chooses not to resolve the hostname
+ * Returns the fully qualified name of the client
+ * or the last proxy that sent the request.
+ * If the engine cannot or chooses not to resolve the hostname
* (to improve performance), this method returns the dotted-string form of
* the IP address. For HTTP servlets, same as the value of the CGI variable
* <code>REMOTE_HOST</code>.
*
* @return a <code>String</code> containing the fully
- * qualified name of the client
+ * qualified name of the client
*
*/
@@ -447,7 +450,7 @@
* package names. Names beginning with <code>java.*</code>,
* <code>javax.*</code>, and <code>com.sun.*</code>, are
* reserved for use by Sun Microsystems.
- *<br> If the value passed in is null, the effect is the same as
+ *<br> If the object passed in is null, the effect is the same as
* calling [EMAIL PROTECTED] #removeAttribute}.
*
*
@@ -559,7 +562,8 @@
* relative path.
*
* @param path a <code>String</code> specifying the pathname
- * to the resource
+ * to the resource. If it is relative, it must be
+ * relative against the current servlet.
*
* @return a <code>RequestDispatcher</code> object
* that acts as a wrapper for the resource
@@ -595,12 +599,19 @@
/**
* Returns the host name of the Internet Protocol (IP) interface on
* which the request was received.
+ *
+ * @return a <code>String</code> containing the host
+ * name of the IP on which the request was received.
*/
public String getLocalName();
/**
* Returns the Internet Protocol (IP) address of the interface on
* which the request was received.
+ *
+ * @return a <code>String</code> containing the
+ * IP address on which the request was received.
+ *
*/
public String getLocalAddr();
@@ -608,6 +619,8 @@
/**
* Returns the Internet Protocol (IP) port number of the interface
* on which the request was received.
+ *
+ * @return an integer specifying the port number
*/
public int getLocalPort();
Index: jsr154/src/share/javax/servlet/ServletRequestWrapper.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/ServletRequestWrapper.java,v
retrieving revision 1.2
diff -u -r1.2 ServletRequestWrapper.java
--- jsr154/src/share/javax/servlet/ServletRequestWrapper.java 5 Mar 2003 02:20:46
-0000 1.2
+++ jsr154/src/share/javax/servlet/ServletRequestWrapper.java 5 Mar 2003 03:33:17
-0000
@@ -401,8 +401,8 @@
}
/**
- * Returns the Internet Protocol (IP) source port of the client
- * or last proxy that sent the request.
+ * The default behavior of this method is to return
+ * getRemotePort() on the wrapped request object.
*/
public int getRemotePort(){
return this.request.getRemotePort();
@@ -410,16 +410,16 @@
/**
- * Returns the host name of the Internet Protocol (IP) interface on
- * which the request was received.
+ * The default behavior of this method is to return
+ * getLocalName() on the wrapped request object.
*/
public String getLocalName(){
return this.request.getLocalName();
}
/**
- * Returns the Internet Protocol (IP) address of the interface on
- * which the request was received.
+ * The default behavior of this method is to return
+ * getLocalAddr() on the wrapped request object.
*/
public String getLocalAddr(){
return this.request.getLocalAddr();
@@ -427,8 +427,8 @@
/**
- * Returns the Internet Protocol (IP) port number of the interface
- * on which the request was received.
+ * The default behavior of this method is to return
+ * getLocalPort() on the wrapped request object.
*/
public int getLocalPort(){
return this.request.getLocalPort();
Index: jsr154/src/share/javax/servlet/ServletResponse.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/ServletResponse.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 ServletResponse.java
--- jsr154/src/share/javax/servlet/ServletResponse.java 13 Aug 2002 16:21:42 -0000
1.1.1.1
+++ jsr154/src/share/javax/servlet/ServletResponse.java 5 Mar 2003 03:33:17 -0000
@@ -79,16 +79,19 @@
* <code>ServletOutputStream</code> and manage the character sections
* manually.
*
- * <p>The charset for the MIME body response can be specified with
- * [EMAIL PROTECTED] #setContentType}. For example, "text/html; charset=Shift_JIS".
- * The charset can alternately be set using [EMAIL PROTECTED] #setLocale}.
- * If no charset is specified, ISO-8859-1 will be used.
- * The <code>setContentType</code> or <code>setLocale</code> method
- * must be called before <code>getWriter</code> for the charset to
- * affect the construction of the writer.
+ * <p>The charset for the MIME body response can be specified
+ * explicitly using the [EMAIL PROTECTED] #setCharacterEncoding} and
+ * [EMAIL PROTECTED] #setContentType} methods, or implicitly
+ * using the [EMAIL PROTECTED] #setLocale} method.
+ * Explicit specifications take precedence over
+ * implicit specifications. If no charset is specified, ISO-8859-1 will be
+ * used. The <code>setCharacterEncoding</code>,
+ * <code>setContentType</code>, or <code>setLocale</code> method must
+ * be called before <code>getWriter</code> and before committing
+ * the response for the character encoding to be used.
*
* <p>See the Internet RFCs such as
- * <a href="http://info.internet.isi.edu/in-notes/rfc/files/rfc2045.txt";>
+ * <a href="http://www.ietf.org/rfc/rfc2045.txt";>
* RFC 2045</a> for more information on MIME. Protocols such as SMTP
* and HTTP define profiles of MIME, and those standards
* are still evolving.
@@ -105,33 +108,51 @@
/**
- * Returns the name of the charset used for
- * the MIME body sent in this response.
- *
- * <p>If no charset has been assigned, it is implicitly
- * set to <code>ISO-8859-1</code> (<code>Latin-1</code>).
- *
- * <p>See RFC 2047 (http://ds.internic.net/rfc/rfc2045.txt)
+ * Returns the name of the character encoding (MIME charset)
+ * used for the body sent in this response.
+ * The character encoding may have been specified explicitly
+ * using the [EMAIL PROTECTED] #setCharacterEncoding} or
+ * [EMAIL PROTECTED] #setContentType} methods, or implicitly using the
+ * [EMAIL PROTECTED] #setLocale} method. Explicit specifications take
+ * precedence over implicit specifications. Calls made
+ * to these methods after <code>getWriter</code> has been
+ * called or after the response has been committed have no
+ * effect on the character encoding. If no character encoding
+ * has been specified, <code>ISO-8859-1</code> is returned.
+ * <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
* for more information about character encoding and MIME.
*
* @return a <code>String</code> specifying the
- * name of the charset, for
- * example, <code>ISO-8859-1</code>
+ * name of the character encoding, for
+ * example, <code>UTF-8</code>
*
*/
public String getCharacterEncoding();
+
+
/**
- * Overrides the name of the character encoding used in the body
- * of the request. This method must be called prior to reading
- * request parameters or reading input using getReader().
- *
- * @param charset String containing the name of the chararacter encoding.
+ * Returns the content type used for the MIME body
+ * sent in this response. The content type proper must
+ * have been specified using [EMAIL PROTECTED] #setContentType}
+ * before the response is committed. If no content type
+ * has been specified, this method returns null.
+ * If a content type has been specified and a
+ * character encoding has been explicitly or implicitly
+ * specified as described in [EMAIL PROTECTED] #getCharacterEncoding},
+ * the charset parameter is included in the string returned.
+ * If no character encoding has been specified, the
+ * charset parameter is omitted.
*
+ * @return a <code>String</code> specifying the
+ * content type, for example,
+ * <code>text/html; charset=UTF-8</code>,
+ * or null
*/
- public void setCharacterEncoding(String charset);
+ public String getContentType();
+
/**
@@ -160,37 +181,38 @@
/**
- * Returns a <code>PrintWriter</code> object that
- * can send character text to the client.
- * The character encoding used is the one specified
- * in the <code>charset=</code> property of the
- * [EMAIL PROTECTED] #setContentType} method, which must be called
- * <i>before</i> calling this method for the charset to take effect.
- *
- * <p>If necessary, the MIME type of the response is
- * modified to reflect the character encoding used.
- *
- * <p> Calling flush() on the PrintWriter commits the response.
- *
+ * Returns a <code>PrintWriter</code> object that
+ * can send character text to the client.
+ * The <code>PrintWriter</code> uses the character
+ * encoding returned by [EMAIL PROTECTED] #getCharacterEncoding}.
+ * If the response's character encoding has not been
+ * specified as described in <code>getCharacterEncoding</code>
+ * (i.e., the method just returns the default value
+ * <code>ISO-8859-1</code>), <code>getWriter</code>
+ * updates it to <code>ISO-8859-1</code>.
+ * <p>Calling flush() on the <code>PrintWriter</code>
+ * commits the response.
* <p>Either this method or [EMAIL PROTECTED] #getOutputStream} may be called
* to write the body, not both.
*
*
- * @return a <code>PrintWriter</code> object that
- * can return character data to the client
- *
- * @exception UnsupportedEncodingException if the charset specified in
- * <code>setContentType</code> cannot be
- * used
+ * @return a <code>PrintWriter</code> object that
+ * can return character data to the client
*
- * @exception IllegalStateException if the <code>getOutputStream</code>
- * method has already been called
for this
- * response object
+ * @exception UnsupportedEncodingException
+ * if the character encoding returned
+ * by <code>getCharacterEncoding</code> cannot be used
+ *
+ * @exception IllegalStateException
+ * if the <code>getOutputStream</code>
+ * method has already been called for this
+ * response object
*
- * @exception IOException if an input or output exception
occurred
+ * @exception IOException
+ * if an input or output exception occurred
*
- * @see #getOutputStream
- * @see #setContentType
+ * @see #getOutputStream
+ * @see #setCharacterEncoding
*
*/
@@ -199,6 +221,35 @@
+ /**
+ * Sets the character encoding (MIME charset) of the response
+ * being sent to the client, for example, to UTF-8.
+ * If the character encoding has already been set by
+ * [EMAIL PROTECTED] #setContentType} or [EMAIL PROTECTED] #setLocale},
+ * this method overrides it.
+ * Calling [EMAIL PROTECTED] #setContentType} with the <code>String</code>
+ * of <code>text/html</code> and calling
+ * this method with the <code>String</code> of <code>UTF-8</code>
+ * is equivalent with calling
+ * <code>setContentType</code> with the <code>String</code> of
+ * <code>text/html; charset=UTF-8</code>.
+ * <p>This method has no effect if it is called after
+ * <code>getWriter</code> has been
+ * called or after the response has been committed.
+ *
+ * @param charset a String specifying only the character set
+ * defined by IANA Character Sets
+ * (http://www.iana.org/assignments/character-sets)
+ *
+ * @see #setContentType
+ * #setLocale
+ *
+ */
+
+ public void setCharacterEncoding(String charset);
+
+
+
/**
* Sets the length of the content body in the response
@@ -217,16 +268,22 @@
/**
* Sets the content type of the response being sent to
- * the client. The content type may include the type of character
- * encoding used, for example, <code>text/html; charset=ISO-8859-4</code>.
- *
- * <p>If obtaining a <code>PrintWriter</code>, this method should be
- * called first.
- *
+ * the client, if the response has not been committed yet.
+ * The given content type may include a character encoding
+ * specification, for example, <code>text/html;charset=UTF-8</code>.
+ * The response's character encoding is only set from the given
+ * content type if this method is called before <code>getWriter</code>
+ * is called.
+ * <p>This method has no effect if called after the response
+ * has been committed. It does not set the response's character
+ * encoding if it is called after <code>getWriter</code>
+ * has been called or after the response has been committed.
*
* @param type a <code>String</code> specifying the MIME
* type of the content
*
+ * @see #setLocale
+ * @see #setCharacterEncoding
* @see #getOutputStream
* @see #getWriter
*
@@ -234,24 +291,6 @@
public void setContentType(String type);
- /**
- * Returns the MIME type of the body of the request, or null if
- * the type is not known. For HTTP servlets, same as the value of
- * the CGI variable CONTENT_TYPE.
- *
- * @return a String containing the name of the MIME type of the
- * request, or null if the type is not known
- *
- * <p> The content type may include the type of character
- * encoding used, for example, <code>text/html; charset=ISO-8859-4</code>.
- *
- * @see #getOutputStream
- * @see #getWriter
- *
- */
-
- public String getContentType();
-
/**
* Sets the preferred buffer size for the body of the response.
@@ -266,7 +305,8 @@
* quickly.
*
* <p>This method must be called before any response body content is
- * written; if content has been written, this method throws an
+ * written; if content has been written or the response object has
+ * been committed, this method throws an
* <code>IllegalStateException</code>.
*
* @param size the preferred buffer size
@@ -374,14 +414,32 @@
/**
- * Sets the locale of the response, setting the headers (including the
- * Content-Type's charset) as appropriate. This method should be called
- * before a call to [EMAIL PROTECTED] #getWriter}. By default, the response
locale
- * is the default locale for the server.
+ * Sets the locale of the response, setting the
+ * <code>Content-Language</code> header,
+ * if the response has not been committed yet.
+ * It also sets the response's character encoding appropriately
+ * for the locale, if the character encoding has not been
+ * explicitly set using [EMAIL PROTECTED] #setContentType} or
+ * [EMAIL PROTECTED] #setCharacterEncoding}, <code>getWriter</code> hasn't
+ * been called yet, and the response hasn't been committed yet.
+ * If the deployment descriptor contains a
+ * <code>locale-encoding-mapping-list</code> element,
+ * and that element provides a mapping for the given locale,
+ * that mapping is used. Otherwise, the mapping from locale to
+ * character encoding is container dependent.
+ * <p>This method has no effect if called after the response has been
+ * committed. It does not set the response's character encoding if
+ * it is called after <code>setContentType</code> has been called
+ * with a charset specification, after
+ * <code>setCharacterEncoding</code> has been called, after
+ * <code>getWriter</code> has been called, or after the response
+ * has been committed.
*
* @param loc the locale of the response
*
* @see #getLocale
+ * @see #setContentType
+ * @see #setCharacterEncoding
*
*/
@@ -390,8 +448,11 @@
/**
- * Returns the locale assigned to the response.
- *
+ * Returns the locale specified for this response
+ * using the [EMAIL PROTECTED] #setLocale} method. Calls made to
+ * <code>setLocale</code> after the response is committed
+ * have no effect. If no locale has been specified,
+ * the container's default locale is returned.
*
* @see #setLocale
*
Index: jsr154/src/share/javax/servlet/SingleThreadModel.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/SingleThreadModel.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 SingleThreadModel.java
--- jsr154/src/share/javax/servlet/SingleThreadModel.java 13 Aug 2002 16:21:43
-0000 1.1.1.1
+++ jsr154/src/share/javax/servlet/SingleThreadModel.java 5 Mar 2003 03:33:17
-0000
@@ -71,15 +71,22 @@
* instance of the servlet, or by maintaining a pool of servlet
* instances and dispatching each new request to a free servlet.
*
- * <p>This interface does not prevent
- * synchronization problems that result from servlets accessing shared
- * resources such as static class variables or classes outside
- * the scope of the servlet.
+ * <p>Note that SingleThreadModel does not solve all thread safety
+ * issues. For example, session attributes and static variables can
+ * still be accessed by multiple requests on multiple threads
+ * at the same time, even when SingleThreadModel servlets are used.
+ * It is recommended that a developer take other means to resolve
+ * those issues instead of implementing this interface, such as
+ * avoiding the usage of an instance variable or synchronizing
+ * the block of the code accessing those resources.
+ * This interface is deprecated in Servlet API version 2.4.
*
*
* @author Various
* @version $Version$
*
+ * @deprecated As of Java Servlet API 2.4, with no direct
+ * replacement.
*/
public interface SingleThreadModel {
Index: jsr154/src/share/javax/servlet/http/HttpServlet.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/http/HttpServlet.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 HttpServlet.java
--- jsr154/src/share/javax/servlet/http/HttpServlet.java 13 Aug 2002 16:21:46
-0000 1.1.1.1
+++ jsr154/src/share/javax/servlet/http/HttpServlet.java 5 Mar 2003 03:33:17
-0000
@@ -410,8 +410,8 @@
* Content-MD5, and Content-Range). If your method cannot
* handle a content header, it must issue an error message
* (HTTP 501 - Not Implemented) and discard the request.
- * For more information on HTTP 1.1, see RFC 2068
- * <a href="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc2068.txt";></a>.
+ * For more information on HTTP 1.1, see RFC 2616
+ * <a href="http://www.ietf.org/rfc/rfc2616.txt";></a>.
*
* <p>This method does not need to be either safe or idempotent.
* Operations that <code>doPut</code> performs can have side
Index: jsr154/src/share/javax/servlet/http/HttpServletRequest.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/http/HttpServletRequest.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 HttpServletRequest.java
--- jsr154/src/share/javax/servlet/http/HttpServletRequest.java 13 Aug 2002 16:21:44
-0000 1.1.1.1
+++ jsr154/src/share/javax/servlet/http/HttpServletRequest.java 5 Mar 2003 03:33:17
-0000
@@ -111,8 +111,9 @@
*
* @return one of the static members BASIC_AUTH,
* FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH
- * (suitable for == comparison)
- * indicating the authentication scheme, or
+ * (suitable for == comparison) or
+ * the container-specific string indicating
+ * the authentication scheme, or
* <code>null</code> if the request was
* not authenticated.
*
@@ -186,6 +187,8 @@
* Returns the value of the specified request header
* as a <code>String</code>. If the request did not include a header
* of the specified name, this method returns <code>null</code>.
+ * If there are multiple headers with the same name, this method
+ * returns the first head in the request.
* The header name is case insensitive. You can use
* this method with any request header.
*
@@ -316,8 +319,10 @@
* Returns any extra path information associated with
* the URL the client sent when it made this request.
* The extra path information follows the servlet path
- * but precedes the query string.
- * This method returns <code>null</code> if there
+ * but precedes the query string and will start with
+ * a "/" character.
+ *
+ * <p>This method returns <code>null</code> if there
* was no extra path information.
*
* <p>Same as the value of the CGI variable PATH_INFO.
@@ -345,9 +350,11 @@
* path. Same as the value of the CGI variable PATH_TRANSLATED.
*
* <p>If the URL does not have any extra path information,
- * this method returns <code>null</code>.
+ * this method returns <code>null</code> or the servlet container
+ * cannot translate the virtual path to a real path for any reason
+ * (such as when the web application is executed from an archive).
*
- * The web container does not decode thins string.
+ * The web container does not decode this string.
*
*
* @return a <code>String</code> specifying the
@@ -466,11 +473,9 @@
/**
*
* Returns the session ID specified by the client. This may
- * not be the same as the ID of the actual session in use.
- * For example, if the request specified an old (expired)
- * session ID and the server has started a new session, this
- * method gets a new session with a new ID. If the request
- * did not specify a session ID, this method returns
+ * not be the same as the ID of the current valid session
+ * for this request.
+ * If the client did not specify a session ID, this method returns
* <code>null</code>.
*
*
@@ -542,17 +547,22 @@
/**
*
* Returns the part of this request's URL that calls
- * the servlet. This includes either the servlet name or
- * a path to the servlet, but does not include any extra
- * path information or a query string. Same as the value
- * of the CGI variable SCRIPT_NAME.
- *
+ * the servlet. This path starts with a "/" character
+ * and includes either the servlet name or a path to
+ * the servlet, but does not include any extra path
+ * information or a query string. Same as the value of
+ * the CGI variable SCRIPT_NAME.
+ *
+ * <p>This method will return an empty string ("") if the
+ * servlet used to process this request was matched using
+ * the "/*" pattern.
*
* @return a <code>String</code> containing
* the name or path of the servlet being
* called, as specified in the request URL,
- * decoded.
- *
+ * decoded, or an empty string if the servlet
+ * used to process the request is matched
+ * using the "/*" pattern.
*
*/
@@ -564,7 +574,7 @@
/**
*
* Returns the current <code>HttpSession</code>
- * associated with this request or, if if there is no
+ * associated with this request or, if there is no
* current session and <code>create</code> is true, returns
* a new session.
*
Index: jsr154/src/share/javax/servlet/http/HttpServletResponse.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/http/HttpServletResponse.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 HttpServletResponse.java
--- jsr154/src/share/javax/servlet/http/HttpServletResponse.java 13 Aug 2002
16:21:46 -0000 1.1.1.1
+++ jsr154/src/share/javax/servlet/http/HttpServletResponse.java 5 Mar 2003
03:33:18 -0000
@@ -176,8 +176,9 @@
/**
* Sends an error response to the client using the specified
- * status clearing the buffer. The server defaults to creating the
- * response to look like an HTML-formatted server error page containing the
specified message, setting the content type
+ * status. The server defaults to creating the
+ * response to look like an HTML-formatted server error page
+ * containing the specified message, setting the content type
* to "text/html", leaving cookies and other headers unmodified.
*
* If an error-page declaration has been made for the web application
@@ -229,7 +230,8 @@
*
* @param location the redirect location URL
* @exception IOException If an input or output exception occurs
- * @exception IllegalStateException If the response was committed
+ * @exception IllegalStateException If the response was committed or
+ if a partial URL is given and cannot be converted into a valid URL
*/
public void sendRedirect(String location) throws IOException;
@@ -276,7 +278,9 @@
* value.
*
* @param name the name of the header
- * @param value the header value
+ * @param value the header value If it contains octet string,
+ * it should be encoded according to RFC 2047
+ * (http://www.ietf.org/rfc/rfc2047.txt)
*
* @see #containsHeader
* @see #addHeader
@@ -289,7 +293,10 @@
* This method allows response headers to have multiple values.
*
* @param name the name of the header
- * @param value the additional header value
+ * @param value the additional header value If it contains
+ * octet string, it should be encoded
+ * according to RFC 2047
+ * (http://www.ietf.org/rfc/rfc2047.txt)
*
* @see #setHeader
*/
Index: jsr154/src/share/javax/servlet/http/HttpSessionListener.java
===================================================================
RCS file:
/home/cvspublic/jakarta-servletapi-5/jsr154/src/share/javax/servlet/http/HttpSessionListener.java,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 HttpSessionListener.java
--- jsr154/src/share/javax/servlet/http/HttpSessionListener.java 13 Aug 2002
16:21:44 -0000 1.1.1.1
+++ jsr154/src/share/javax/servlet/http/HttpSessionListener.java 5 Mar 2003
03:33:18 -0000
@@ -80,7 +80,7 @@
public void sessionCreated ( HttpSessionEvent se );
/**
- * Notification that a session was invalidated.
+ * Notification that a session is about to be invalidated.
* @param se the notification event
*/
public void sessionDestroyed ( HttpSessionEvent se );
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
