Change Log

This document is the maintenance review of the Java Servlet 2.5 Servlet specification developed under the Java Community ProcessSM (JCP).

Changes Since Servlet 2.4

1. Session Clarification

Clarified SRV.7.3 "Session Scope" to allow for better support of session ids being used in more than one context. This was done to support the Portlet specification (JSR 168). Added the following paragraph at the end of SRV.7.3 "Session Scope":

 

"Additionally, sessions of a context must be resumable by requests into that context regardless of whether their associated context was being accessed directly or as the target of a request dispatch at the time the sessions were created."

 

Made the changes in SRV.8.3 "The Include Method" by replacing the following text:

 

"It cannot set headers or call any method that affects the headers of the response. Any attempt to do so must be ignored."

 

with the following:

 

"It cannot set headers or call any method that affects the headers of the response, with the exception of the HttpServletRequest.getSession() and HttpServletRequest.getSession(boolean) methods. Any attempt to set the headers must be ignored, and any call to HttpServletRequest.getSession() or HttpServletRequest.getSession(boolean) that would require adding a Cookie response header must throw an IllegalStateException if the response has been committed."

2. Filter All Dispatches

Modified SRV.6.2.5 "Filters and the RequestDispatcher" to clarify a way to map a filter to all servlet dispatches by appending the following text to the end of the section:

 

Finally, the following code uses the special servlet name '*':

 

<filter-mapping>

<filter-name>All Dispatch Filter</filter-name>

<servlet-name>*</servlet-name>

<dispatcher>FORWARD</dispatcher>

</filter-mapping>

 

This code would result in the All Dispatch Filter being invoked on request dispatcher forward() calls for all request dispatchers obtained by name or by path.

3. Multiple Occurrences of Servlet Mappings

Previous versions of the servlet schema allows only a single url-pattern or servlet name per servlet mapping. For servlets mapped to multiple URLs this results in needless repetition of whole mapping clauses.

The deployment descriptor servlet-mappingType was updated to:

 

<xsd:complexType name="servlet-mappingType">

<xsd:sequence>

<xsd:element name="servlet-name" type="j2ee:servlet-nameType"/>

<xsd:element name="url-pattern" type="j2ee:url-patternType" minOccurs="1"

maxOccurs="unbounded"/>

</xsd:sequence>

<xsd:attribute name="id" type="xsd:ID"/>

</xsd:complexType>

4. Multiple Occurrences Filter Mappings

Previous versions of the servlet schema allows only a single url-pattern in a filter mapping. For filters mapped to multiple URLs this results in needless repetition of whole mapping clauses.

 

The deployment descriptor schema the filter-mappingType was updated to:

 

<xsd:complexType name="filter-mappingType">

<xsd:sequence>

<xsd:element name="filter-name" type="j2ee:filter-nameType"/>

<xsd:choice minOccurs="1" maxOccurs="unbounded">

<xsd:element name="url-pattern" type="j2ee:url-patternType"/>

<xsd:element name="servlet-name" type="j2ee:servlet-nameType"/>

</xsd:choice>

<xsd:element name="dispatcher" type="j2ee:dispatcherType" minOccurs="0"

maxOccurs="4"/>

</xsd:sequence>

<xsd:attribute name="id" type="xsd:ID"/>

</xsd:complexType>

 

This change allows multiple patterns and servlet names to be defined in a single mapping as can be seen in the following example:

 

<filter-mapping>

<filter-name>Demo Filter</filter-name>

<url-pattern>/foo/*</url-pattern>

<url-pattern>/bar/*</url-pattern>

<servlet-name>Logger</servlet-name>

<dispatcher>REQUEST</dispatcher>

<dispatcher>ERROR</dispatcher>

</filter-mapping>

 

SRV.6.2.4 "Configuration of Filters in a Web Application" was updated to clarify the cases where there are multiple mappings with the following text:

 

"If a filter mapping contains both <servlet-name> and <url-pattern>, the container must expand the filter mapping into multiple filter mappings (one for each <servlet-name> and <url-pattern>), preserving the order of the <servlet-name> and <url-pattern> elements."

 

An examples was also provided to clarify cases when there are multiple mappings.

5. Support Alternative HTTP Methods with Authorization Constraints

The previous Servlet 2.4 schema restricted HTTP methods to GET, POST, PUT, DELETE, HEAD, OPTIONS, and TRACE. The schema http-methodType was changed from:

 

<xsd:complexType name="http-methodType">

...

<xsd:simpleContent>

<xsd:restriction base="j2ee:string">

<xsd:enumeration value="GET"/>

<xsd:enumeration value="POST"/>

<xsd:enumeration value="PUT"/>

<xsd:enumeration value="DELETE"/>

<xsd:enumeration value="HEAD"/>

<xsd:enumeration value="OPTIONS"/>

<xsd:enumeration value="TRACE"/>

</xsd:restriction>

</xsd:simpleContent>

</xsd:complexType>

 

To the following:

 

<xsd:simpleType name="http-methodType">

<xsd:annotation>

<xsd:documentation>

A HTTP method type as defined in HTTP 1.1 section 2.2.

</xsd:documentation>

</xsd:annotation>

 

<xsd:restriction base="xsd:token">

<xsd:pattern value="[\p{L}-[\p{Cc}\p{Z}]]+"/>

</xsd:restriction>

</xsd:simpleType>

 

The http-method elements now need to be a token as described in HTTP 1.1 specification section 2.2.

6. Minimum J2SE Requirement

Servlet 2.5 Containers now require J2SE 5.0 as the minimum Java version. SRV.1.2 "What is a Servlet Container?" was updated to reflect this requirement.

7. annotations and Resource Injection

Java EE technology compliant containers require annotations and resource injection on servlets, filters, and listeners. SRV.14.5 "Annotations and Resource Injection" describes the annotations and resource injection in further detail.

 

8. SRV.9.9 ("Error Handling") Requirement Removed

 

SRV.9.9.1 "Request Attributes" defines the following requirement:

 

If the location of the error handler is a servlet or a JSP page:

[...]

The response setStatus method is disabled and ignored if called.

[...]

 

The JSP 2.1 EG has asked that this requirement above be removed to allow JSP error pages to update the response status.

9. HttpServletRequest.isRequestedSessionIdValid() Clarification

The API clarification better describes what happens when a client did not specify a session id. The API documentation in SRV.16.1.3 "HttpServletRequest" was updated to specify when false is returned. The API documentation now states:

 

Returns false if the client did not specify any session ID.

.

10. SRV.5.5 ("Closure of Response Object") Clarification

The behavior in SRV.5.5 "Closure of Response Object" the response's content length is set to 0 via response.setHeader("Content-Length", "0") and any subsequently setHeader() calls are ignored.

 

SRV.5.5 "Closure of Response Object" was updated to allow all headers to be set by changing:

 

"The amount of content specified in the setContentLength method of the response and has been written to the response"

 

To the following:

 

"The amount of content specified in the setContentLength method of the response has been greater than zero and has been written to the response"

 

11. ServletRequest.setCharacterEncoding() Clarified

The API in SRV.15.2.16 "ServletRequest" was updated to described the behavior if the method is called after the getReader() was called. If the getReader() is called there will be no effect.

12. Java Enterprise Edition Requirements

SRV.14 "Java Enterprise Edition 5 Containers" details all requirements of a Java EE container. Previously the requirements were mixed into each chapter.

13. Servlet 2.4 MR Change Log Updates Added

Added the changes from the Servlet 2.4 Maintenance Review. These changes include grammar and typographical fixes.