<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>The 2.4 Servlet Specfication</title><link rel="stylesheet" href="jetty.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.62.0"></head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1"></a>The 2.4 Servlet Specfication</h2></div><div><h3 class="subtitle"><i>The Good, the Bad and the Ugly <span class="author"><span class="firstname">Greg</span> <span class="surname">Wilkins</span></span></i></h3></div></div><div></div><hr></div><div class="toc"><dl><dt><span class="sect1"><a href="#d0e16">1. Introduction</a></span></dt><dt><span class="sect1"><a href="#d0e21">2. New Features</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e47">2.1. XML Schema for web.xml</a></span></dt><dd><dl><dt><span class="sect3"><a href="#d0e52">2.1.1. Schema's Declaration</a></span></dt><dt><span class="sect3"><a href="#d0e67">2.1.2. Validation</a></span></dt><dt><span class="sect3"><a href="#d0e94">2.1.3. Order Independence</a></span></dt><dt><span class="sect3"><a href="#d0e129">2.1.4. New Descriptor Elements</a></span></dt><dt><span class="sect3"><a href="#d0e229">2.1.5. J2EE Schema's</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e249">2.2. Filter Mapping Enhancements</a></span></dt><dd><dl><dt><span class="sect3"><a href="#d0e254">2.2.1. The Problem</a></span></dt><dt><span class="sect3"><a href="#d0e289">2.2.2. The Solution</a></span></dt><dt><span class="sect3"><a href="#d0e321">2.2.3. No Silver Bullet</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e326">2.3. RequestDispatcher Forward Attributes</a></span></dt><dt><span class="sect2"><a href="#d0e358">2.4. New Event Listeners</a></span></dt><dd><dl><dt><span class="sect3"><a href="#d0e363">2.4.1. Request Event & Listener</a></span></dt><dt><span class="sect3"><a href="#d0e390">2.4.2. Request Attribute Event & Listener</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e407">2.5. New APIs</a></span></dt><dd><dl><dt><span class="sect3"><a href="#d0e412">2.5.1. Client Connection Methods</a></span></dt><dt><span class="sect3"><a href="#d0e426">2.5.2. Internationalization</a></span></dt></dl></dd></dl></dd><dt><span class="sect1"><a href="#d0e463">3. Missing Features</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e468">3.1. Programmatic Authentication</a></span></dt><dt><span class="sect2"><a href="#d0e494">3.2. Extensible Deployment Descriptors</a></span></dt><dt><span class="sect2"><a href="#d0e533">3.3. NIO Support</a></span></dt><dt><span class="sect2"><a href="#d0e548">3.4. SingleThreadModel Deprecated</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d0e553">4. Updates & Clarifications</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e556">4.1. Java & HTTP Versions</a></span></dt><dt><span class="sect2"><a href="#d0e563">4.2. Path Mappings & Path Parameters</a></span></dt><dt><span class="sect2"><a href="#d0e590">4.3. Error pages</a></span></dt><dt><span class="sect2"><a href="#d0e611">4.4. Welcome Files</a></span></dt><dt><span class="sect2"><a href="#d0e629">4.5. Life Cycles & Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d0e647">5. New and Unresolved Problems</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e652">5.1. Welcome Files</a></span></dt><dt><span class="sect2"><a href="#d0e711">5.2. RequestDispatchers vs Wrappers</a></span></dt><dd><dl><dt><span class="sect3"><a href="#d0e743">5.2.1. Wrap Over vs Wrap Under</a></span></dt><dt><span class="sect3"><a href="#d0e786">5.2.2. Resolution of RequestDispatchers vs Wrappers</a></span></dt></dl></dd><dt><span class="sect2"><a href="#d0e805">5.3. Distributable Web Applications</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d0e822">6. Conclusion</a></span></dt><dt><span class="appendix"><a href="#d0e831">A. References</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e16"></a>1. Introduction</h2></div></div><div></div></div><p>After a longer and more difficult process than expected, the 2.4 version of the Servlet Specification has been completed by JSR-154 and is due for release before the end of 2003. The aims of this revision of the specification were some modest feature enhancements, improved deployment descriptors and general clarifications of existing functionality. These aims, with some notable exceptions have largely been met. This article reviews the most important additions, changes, omissions and remaining problems in the specification. The key new features are introduced and some explanations are given for those that are missing in action. Problem areas that remain in the specification and those that have newly been added are also discussed.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e21"></a>2. New Features</h2></div></div><div></div></div><p>Developers fearing revolution, need not be worried by the 2.4 servlet specification as it introduces no new functionality. However, existing mechanisms have been extended and enhanced with sometime powerful results. The short list of new features includes:</p><div class="itemizedlist"><ul type="disc"><li><p>XML Schema definition of the deployment descriptor.</p></li><li><p>Increased (improved?) integration with other J2EE specification and components.</p></li><li><p>Filtering of RequestDispatchers and Error pages.</p></li><li><p>Event listeners for requests and request attributes.</p></li><li><p>Methods to query client connection details.</p></li><li><p>Improved internationalization methods.</p></li></ul></div><p>Of these changes, only those to the RequestDispatcher and internationalization methods are likely to be relevant to your average servlet developer.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e47"></a>2.1. XML Schema for web.xml</h3></div></div><div></div></div><p>The 2.4 servlet deployment descriptor is now defined by an XML schema rather that a DTD (as used for all previous versions). Relatively few new elements are introduced in 2.4, but the schema's means that there are some subtle yet significant changes to all elements in the descriptor.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e52"></a>2.1.1. Schema's Declaration</h4></div></div><div></div></div><p>For many developers the change to schema's will mean little more than an change of the mantra used at the start of the web.xml file ( and an increase in the number of times they download xercesImpl.jar). To use the 2.4 schema's, the XML envelope of the deployment descriptor must change from the DTD form of:</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"><!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd" >
<web-app>
<!-- deployment elements go here -->
</web-app></pre></blockquote></div><p>to the even less readable:</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"><?xml version="1.0" encoding="ISO-8859-1"?>
<web-app
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<!-- deployment elements go here -->
</web-app></pre></blockquote></div><p>Most developers need not concern themselves with the exact meaning of this envelope and can simply copy it verbatim or indeed have it generated for them from their IDE, by Xdoclet or similar. The older DTD based descriptors are still supported, but the new features of the 2.4 deployment schema will not be usable unless the 2.4 envelope is used.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e67"></a>2.1.2. Validation</h4></div></div><div></div></div><p>With previous DTD based versions of the deployment descriptor, validation was optional and many containers defaulted to no validation. But with the introduction of schema's, validation has been made a requirement for all J2EE containers:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.13.2 “<span class="quote">The containers and tools that are part of J2EE technology-compliant implementation are required to validate deployment descriptor against the XML schema for structural correctness. The validation is recommended, but not required for the web containers and tools that are not part of J2EE technology-compliant implementation.</span>”</p></blockquote></div><p>Schema validation is significantly more powerful than DTD validation and more than simply document structure is checked:</p><div class="itemizedlist"><ul type="disc"><li><p>String values such as mime-types and URL patterns are checked for allowed characters.</p></li><li><p>Numerical values are check for numeric only characters and for the allowed sign.</p></li><li><p>Names for elements such as Servlet, Filter, EJB-Ref, etc. are checked for uniqueness.</p></li><li><p>Enumerations (e.g. user-data-constraints: NONE, INTEGRAL & CONFIDENTIAL) are checked for allowed values.</p></li></ul></div><p>The increase rigour of schema validation should assist development by detecting errors earlier in the process and reduce portability issues as less container specific validation implementation is required. Because of the accepting nature of unvalidated XML, it is likely that many validation errors will be detected when converting descriptors that were generated by hand and never validated. For developers that generate their descriptors or use XML aware editors, the transition should be mostly painless.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e94"></a>2.1.3. Order Independence</h4></div></div><div></div></div><p>One of the reasons that validation is often turned off for previous servlet versions, is that the DTDs impose a strict order of top level elements in the web.xml. For example, it is not legal to place a servlet mappings directly after the servlets declaration if you have more than one servlet. The following descriptor has a logical ordering that is illegal with the DTD based validation:</p><pre class="programlisting"><web-app>
...
<servlet>
<servlet-name>ServletA</servlet-name>
<servlet-class>org.mortbay.servlet.ServletA</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>ServletA</servlet-name>
<url-pattern>/aaa/*</url-pattern>
</servlet-mapping>
<servlet> <!-- ILLEGAL in specs<=2.3 as all servlet elements must be together -->
<servlet-name>ServletB</servlet-name>
<servlet-class>org.mortbay.servlet.ServletB</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>ServletB</servlet-name>
<url-pattern>/bbb/*</url-pattern>
</servlet-mapping>
...
</web-app></pre><p>The 2.4 schema has been written so that all top level elements may now occur in any order and in any number. So the above descriptor will now be legal and more logical descriptor layouts and simpler generation will be possible. It still would have been better if the original descriptor specification had allowed url-patterns in the <tt class="computeroutput"><servlet></tt> element, but that's history now.</p><p>As a side effect of arbitrary element ordering, all top level elements may now occur 0 or many times. While this is logical for most elements, some additional interpretation is required for some elements:</p><div class="itemizedlist"><ul type="disc"><li><p>Multiple instances of the list elements like welcome-file-list and the new locale-encoding-mapping-list result in concatenated lists.</p></li><li><p>Multiple instances of <tt class="constant"><jsp-config></tt>, <tt class="constant"><login-config></tt> and <tt class="constant"><session-config></tt> are errors that must be detected and reported by the container rather than XML validation.</p></li><li><p>Multiple instances of the distributable element are treated the same as a single occurrence.</p></li></ul></div><p>It is hoped that this relaxation of ordering will avoid a major source of invalid descriptors now that validation is required for J2EE containers.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e129"></a>2.1.4. New Descriptor Elements</h4></div></div><div></div></div><p>There are only a few new elements in the 2.4 deployment descriptor, which are summarized below.</p><div class="table"><a name="d0e134"></a><p class="title"><b>Table 1. New Deployment Descriptor Elements</b></p><table summary="New Deployment Descriptor Elements" border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><i class="medialabel">New Element</i></td><td><i class="medialabel">Parent Element</i></td><td><i class="medialabel">Description</i></td></tr><tr><td><tt class="constant"><dispatcher></tt></td><td><tt class="constant"><filter-mapping></tt></td><td>Defines the request type that a filter mapping applies to (see 2.2 below).</td></tr><tr><td><tt class="constant"><locale-encoding-mapping-list></tt></td><td><tt class="constant"><web-app></tt></td><td>Defines list of locale to character encoding mappings.</td></tr><tr><td><tt class="constant"><locale-encoding-mapping></tt></td><td><tt class="constant"><locale-encoding-mapping-list></tt></td><td>Defines entry in locale encoding list.</td></tr><tr><td><tt class="constant"><locale></tt></td><td><tt class="constant"><locale-encoding-mapping></tt></td><td>The name of a locale in a locale encoding mapping.</td></tr><tr><td><tt class="constant"><encoding></tt></td><td><tt class="constant"><locale-encoding-mapping></tt></td><td>The character encoding of a locale encoding mapping.</td></tr><tr><td><tt class="constant"><message-destination></tt></td><td><tt class="constant"><web-app></tt></td><td>Declaration of a message destination resource. Defined in J2EE specification.</td></tr><tr><td><tt class="constant"><message-destination-ref></tt></td><td><tt class="constant"><web-app></tt></td><td>Declaration of a reference to a message destination resource. Defined in J2EE specification.</td></tr><tr><td><tt class="constant"><service-ref></tt></td><td><tt class="constant"><web-app></tt></td><td>Declares a reference to a Web service. Defined in J2EE specification.</td></tr></tbody></table></div><p>The nested elements of the J2EE elements (e.g. <tt class="constant"><ejb-ref></tt>) and JSP related elements (e.g. <tt class="constant"><jsp-config></tt>) are no longer defined in the servlet specification itself but by other specifications from J2EE and the JCP.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e229"></a>2.1.5. J2EE Schema's</h4></div></div><div></div></div><p>The design of the deployment descriptor schema's for servlets represents more than just technical changes. The decision to make the schema's dependant on other J2EE schema's represents a significant and not completely welcome change in the specification process.</p><p>Prior to 2.4, the web application deployment descriptor was specified entirely by servlet specification and was the responsibility of the relevant JSR. With the 2.4 schema definitions, significant portions of the definitions are imported from the schema's produced by other parts of the J2EE specification and under the guidance of other JSRs.</p><p>The practical benefit of this change is that a single consistent definition of deployment descriptor elements may be used for JSPs, EJB, Web Services etc. Furthermore, these elements will be defined by the JSRs responsible for the technologies to which they apply to (e.g. the JSP descriptor schema is produced by JSR152 (JSPs) not JSR-154 (Servlets)). But some major concerns about this approach have been expressed regarding how this change effects the Servlet specification and the whole JCP process.</p><p>Importing J2EE schema's means that the servlet specification is no longer standalone and can only be considered as a subordinate specification of J2EE. Apart from the questionable object oriented design of a component having dependencies on it's container, this represents an administrative change that was forced on JSR-154 by the managers of the Java Community Process. The result being that the complete contents of the servlet deployment descriptor is now beyond the control of the servlet JSR and expert panel.</p><p>Servlets are much more than just a component of J2EE and many (if not most) deployments are on J2SE. There are even implementations for some J2ME profiles. By making J2EE the controlling specification for servlets, it has left J2SE implementation with a less definitive specification and with concerns that their interests may not be given equal consideration in future revisions of the specification.</p><p>This conflict of interests may have be the result of earlier mistakes in the servlet specification and is very much related to the discussion of extensible schema's later in this article. It could be argued that EJB elements should not have been added to the servlet specification, nor should JSPs have been given "favoured son" status over other content generation technologies. The <tt class="constant">WEB-INF</tt> directory could easily have been used as the home of separate deployment descriptors for servlet related technology without extending servlet deployment descriptor and specification itself.</p><p>The next revision of the specification may be a difficult one, as it has both significant technical and political issues that it must deal with. It is the authors hope that the result will be a servlet specification with clear J2ME, J2SE and J2EE profiles and a clear and reasonable dependency tree between them.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e249"></a>2.2. Filter Mapping Enhancements</h3></div></div><div></div></div><p>When Filters were introduced in the 2.3 specification, they only applied to requests as they enter the container. Thus this powerful feature was not available to forwarded or included requests. Additionally it was undefined how they applied to error pages and welcome files. The 2.4 specification corrects this by allowing a filter to be mapped to specific types of requests and by clarifying the specification of the error page and welcome file mechanisms.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e254"></a>2.2.1. The Problem</h4></div></div><div></div></div><p>Consider the use of a filter to transform xml content as it is served from a web application. The transform could be to HTML, WML or whatever mark up is appropriate for the client. Using 2.3, the following descriptor elements could be defined:</p><pre class="programlisting"> <filter>
<filter-name>Transform</filter-name>
<filter-class>com.acme.TransformFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Transform</filter-name>
<url-pattern>*.xml</url-pattern>
</filter-mapping>
<error-page>
<error-code>404</error-code>
<location>/error404.xml</location>
</error-page>
<error-page>
<exception-type>java.lang.Exception</exception-type>
<location>/except.xml</location>
</error-page>
<welcome-file-list>
<welcome-file>index.xml</welcome-file>
</welcome-file-list></pre><p>A request for an XML resource that exists (e.g. <tt class="constant">/foo/bar.xml</tt>) will match the Transform filter the content served will be handled by that filter as desired. Additionally, for many 2.3 containers this also worked for non-existent XML URIs (e.g. <tt class="constant">/doesNotExist.xml</tt>) which also matched the filter mapping and thus transformed the <tt class="constant">error404.xml</tt> error page that was served from the error-page mapping.</p><p>Unfortunately, this configuration fails for errors for non XML URIs. If a request for <tt class="constant">/doesNotExist.JPG</tt> is received, this does not match the *.xml filter mapping so the Transform filter should not be applied. This results in the error404.xml file being served without transformation.</p><p>A similar problem exists for welcome files, as a request to a URI like /foo/ may be handled by serving the <tt class="constant">/foo/index.xml</tt> resource, but it is unclear if the *.xml filter mapping should apply. For a container that uses a HTTP redirect to a welcome file, the filter would be applied as that results in a new request entering the container. For containers that serve welcome files directly, the filter should not be applied.</p><p>Finally, if a controller style servlet is introduced, where requests to URIs like <tt class="constant">/controller/info</tt> are dispatched as forwards or includes to the xml generating resource. The decision whether or not to apply the Transform filter cannot be made until the Controller servlet has selected a resource to which to dispatch.</p><p>Developers wanting to use 2.3 filters for such uses have often ended up applying the filter to all URIs and the filter itself decides if it applies to any particular request. This works well if your application mostly serves content that requires transformation, but is very inefficient in any mixed media environment. It also makes poor usage of the filter mapping mechanism.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e289"></a>2.2.2. The Solution</h4></div></div><div></div></div><p>To better support flexible filter usage, the 2.4 specification now allows one or more <tt class="constant"><dispatcher></tt> sub elements to optionally be added to a <tt class="constant"><filter-mapping></tt> element. Each <tt class="constant"><dispatcher></tt> element specifies a value of <tt class="constant">REQUEST</tt>, <tt class="constant">FORWARD</tt>, <tt class="constant">INCLUDE</tt> or <tt class="constant">ERROR</tt> to indicate to which type of request the filter mapping applies.</p><p>For the above example, the filter mapping in the deployment descriptor can now be written as:</p><pre class="programlisting"> <filter-mapping>
<filter-name>Transform</filter-name>
<url-pattern>*.xml</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>INCLUDE</dispatcher>
<dispatcher>ERROR</dispatcher>
</filter-mapping></pre><p>This specifies that the Transform filter applies to any *.xml request that is received as a normal request, is the target of a RequestDispatcher.forward, is the target of a RequestDispatcher.include or is served as an error page.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e321"></a>2.2.3. No Silver Bullet</h4></div></div><div></div></div><p>The enhanced filter mapping mechanism will make it easier to use filters for clever applications, but it does not absolve the developer totally from the practise of careful design. The main problem now is to avoid situations where the same filter is applied more than once. For example, if an exception was thrown during the generation of a XML resource, then the Transform filter may get applied twice: once for the original request and again for the error page dispatch. Thus simply applying filters to all types of requests will not always be the solution.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e326"></a>2.3. RequestDispatcher Forward Attributes</h3></div></div><div></div></div><p>The current specification of the RequestDispatcher.forward method does not well define the request methods that need to change when a request is forwarded:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.8.4 “<span class="quote">The path elements of the request object exposed to the target servlet must reflect the path used to obtain the RequestDispatcher.</span>”</p></blockquote></div><p>This has resulted various implementation for the getRequestURI() method as it was unclear if getRequestURI was a path method or not. However, the issue is resolved elsewhere in the specification where it states:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.4.4 “<span class="quote">It is important to note that, except for URL encoding differences between the request URI and the path parts, the following equation is always true: <tt class="constant">requestURI = contextPath + servletPath + pathInfo</tt></span>”</p></blockquote></div><p>Thus the value returned by HttpServletRequest.getRequestURI() must change after a forward to reflect the resource used to obtain the RequestDispatcher. This resulted in the situation where the target of a forward was unable to easily determine the original URI of the request, as used by the client. This made it very difficult to generate URL links based on the request that the client had issued.</p><p>To resolve this, the 2.4 specification has added a set of forward attributs that are set the first time a request is forwarded:</p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p>javax.servlet.forward.request_uri<br>
javax.servlet.forward.context_path <br>
javax.servlet.forward.servlet_path <br>
javax.servlet.forward.path_info<br>
javax.servlet.forward.query_string</p></div></blockquote></div><p>These attributes capture the path values and query string as originally received by the container and are not hidden by any subsequent forwards or includes of the request. Thus the original request paths will always be available.</p><p>Unfortunately, the result is that if a servlet is to be portable and reusable, it now needs to double check getRequestURI to determine the URI that the client used and the URI (or context, servlet or info path) of the resource to be served:</p><pre class="programlisting">public void doGet(HttpServletRequest request, HttpServletResponse response)
{
String uriUsedByClient=(String)
request.getAttribute("javax.servlet.forward.request_uri");
if (uriUsedByClient==null)
uriUsedByClient=request.getRequestURI();
String uriToServe=(String)
request.getAttribute("javax.servlet.include.request_uri");
if (uriToServe==null)
uroToServer=request.getRequestURI();
// ...
}</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e358"></a>2.4. New Event Listeners</h3></div></div><div></div></div><p>The servlet event model has been rounded out with new listeners defined for requests and request attributes. However, there is probably very little need for any of these new listeners other than completeness and do not provide anything that could not simply be implemented with a filter.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e363"></a>2.4.1. Request Event & Listener</h4></div></div><div></div></div><p>The <tt class="constant">javax.servlet.ServletRequestListener</tt> and <tt class="constant">javax.servlet.ServletRequestEvent</tt> classes have been introduced for handling events when a request enters and leaves the scope of a web application, which is defined in the javadoc as:</p><div class="blockquote"><blockquote class="blockquote"><p>“<span class="quote">A request is defined as coming into scope when it is about to enter the first servlet or filter in each web application, as going out of scope when it exits the last servlet or the first filter in the chain.</span>”</p></blockquote></div><p>Unfortunately the events themselves were named without considering that a web application can dispatch a request to another, resulting in a request being in scope of more than one web application. Thus instead of names such as <tt class="constant">enterContext</tt>/<tt class="constant">exitContext,</tt> the events are defined as:</p><pre class="programlisting">public interface ServletRequestListener extends EventListener {
/** The request is about to come into scope of the web application. */
public void requestInitialized ( ServletRequestEvent sre );
/** The request is about to go out of scope of the web application. */
public void requestDestroyed ( ServletRequestEvent sre );
}</pre><p>Note that the functionality provided by this listener is also provided by the extended filter mechanism. A trivial filter installed at the default / path equally allows for handling of requests as they enter and exist a web application.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e390"></a>2.4.2. Request Attribute Event & Listener</h4></div></div><div></div></div><p>The <tt class="constant">javax.servlet.ServletRequestAttributeListener</tt> and <tt class="constant">javax.servlet.ServletRequestAttributeEvent</tt> classes have been introduced for handling events when a request attribute is modified while the request is within the scope of a web application:</p><pre class="programlisting">public interface ServletRequestAttributeListener extends EventListener {
/** Notification that a new attribute was added to the
** servlet request. Called after the attribute is added.
*/
public void attributeAdded(ServletRequestAttributeEvent srae);
/** Notification that an existing attribute has been removed from the
** servlet request. Called after the attribute is removed.
*/
public void attributeRemoved(ServletRequestAttributeEvent srae);
/** Notification that an attribute was replaced on the
** servlet request. Called after the attribute is replaced.
*/
public void attributeReplaced(ServletRequestAttributeEvent srae);
}</pre><p>As for the ServletRequestListener, a request can be in scope of multiple web applications and events are generated for all in-scope web applications. Thus if ServletA in context /webappA dispatches a request to ServletB in context /webappB, then ServletRequestListeners in both web applications will receive events if ServletB modifies an attribute.</p><p>As the value of the attribute is passed in the event object, use of this listener may lead to some interesting class loader issues as web applications are passed an object of a class instance that is only available to another web application. However, this is unlikely to ever be an issue, as there is very little need for this event and the author will buy a large beer to anybody that can suggest a real world use-case. Note that this listeners functionality could also have been provided with the extended filter mechanism and request wrapping.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e407"></a>2.5. New APIs</h3></div></div><div></div></div><p>A few minor improvements have been made to the servlet APIs of existing interfaces.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e412"></a>2.5.1. Client Connection Methods</h4></div></div><div></div></div><p>The <tt class="constant">javax.servlet.ServletRequest</tt> interface in 2.3 had a partial set of methods that describe the logical and actual connection of a request. In 2.4 four additional methods have been added to make this part of the API more complete:</p><pre class="programlisting">public interface ServletRequest
{
// Methods about the logical name of the server, as seen by the client.
public String getServerName();
public int getServerPort();
// Methods about the local end of the actual TCP/IP connection
public String getLocalName(); // New in 2.4
public String getLocalAddr(); // New in 2.4
public int getLocalPort(); // New in 2.4
// Methods about the remote end of the actual TCP/IP connection
public String getRemoteAddr();
public String getRemoteHost();
public int getRemotePort(); // NEW in 2.4
...
</pre><p>The ServerName is the name used by the client to create the connection with the server. The LocalName is the DNS name of the interface that the connection was received on, which may have been proxied or otherwise mapped and thus can often be different from the ServerName. The same difference applies to the ServerPort and LocalPort.</p><p>These APIs will not be of much use for most web applications, but are vital for those that need to be aware of their network environment.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e426"></a>2.5.2. Internationalization</h4></div></div><div></div></div><p>Prior to 2.4, the content type and character encoding of a response could be set with a call to setContentType like:</p><pre class="programlisting">response.setContentType("text/html; charset=Shift_JIS");</pre><p>The same result could be achieved with better separation of concerns using setLocale:</p><pre class="programlisting">response.setContentType("test/html");
response.setLocale(Locale.JAPAN);</pre><p>Unfortunately the mapping between Locale and character encoding is not well defined and it was up to each container to provide a reasonable mapping. There was no way to tell if a Locale was known to the container, nor to retrieve the resulting combined content-type to check if a character encoding had been set.</p><p>The 2.4 specification addresses this by firstly allowing the Locale to encoding mapping to be specified in the descriptor using the new <tt class="constant"><locale-encoding-mapping-list></tt> element. Locales may be mapped with either just a language code (e.g. zh), or a language and country code (e.g.. zh_TW):</p><pre class="programlisting"><locale-encoding-mapping-list>
<locale-encoding-mapping>
<locale>ja</locale><encoding>Shift_JIS</encoding>
</locale-encoding-mapping>
<locale-encoding-mapping>
<locale>zh</locale><encoding>GB2312</encoding>
</locale-encoding-mapping>
<locale-encoding-mapping>
<locale>zh_TW</locale><encoding>Big5</encoding>
</locale-encoding-mapping>
</locale-encoding-mapping-list></pre><p>The encoding for a particular locale may still be set by a container default, but the webapp now has the option to override the container or ensure that the locale is supported. There is also a new <tt class="constant">getContentType</tt> method on <tt class="constant">ServletResponse</tt> that allows the resulting content-type string to be observed:</p><pre class="programlisting">response.setContentType("test/html");
response.setLocale(Locale.JAPAN);
assert response.getContentType().indexOf("charset=Shift_JIS")>0;</pre><p>Finally for those that want direct control of the character encoding and do not wish to go via the Locale mechanism, there is a new response <tt class="constant">setCharacterEncoding</tt> method:</p><pre class="programlisting">response.setContentType("test/html");
response.setCharacterEncoding("Shift_JIS");</pre></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e463"></a>3. Missing Features</h2></div></div><div></div></div><p>Some of the features listed in the aims of JSR-154 and that have been much requested by users, did not make it into the 2.4 specification. Mostly this was because they proved to be beyond the scope of a point release</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e468"></a>3.1. Programmatic Authentication</h3></div></div><div></div></div><p>The JSR-154 aims and early drafts of the 2.4 specification contained an API for programmatic authentication of requests, which was dropped during the review process. While all parties agreed that this is a much needed feature, it was not possible to agree a one-size-fits-all solution without some significant changes to the existing security mechanism. Some of the key questions that need to be resolved include:</p><div class="itemizedlist"><ul type="disc"><li><p>What parts of authentication and authorization are the responsibility of the servlet specification? Should it be providing a complete solution or just implementing the HTTP specific protocols and linking them with an externally specified mechanism?</p></li><li><p>Should the servlet security mechanisms be integrated with the java.security.* architecture? If so, how should role based authentication be mapped to the Permission model?</p></li><li><p>What is the scope of Authentication? Is it tied to a URL space, a HTTP Cookie, a HttpSession or a distributed HttpSession? The existing protocols all have different scopes and it is only FORM authentication that tied authentication to a HttpSession.</p></li><li><p>What requests are authenticated? Only those that match an authentication constraint, only those that have security methods called or all requests?</p></li><li><p>Under what circumstances is authentication passed onto a J2EE call?</p></li><li><p>What about JAAS, SAML, single sign on, etc.?</p></li></ul></div><p>These are all tough questions and security is something that you do not wish to get wrong. The result was that programmatic login was thrown into the too hard basket for 2.4. For now programmatic login can be achieved on many containers with a dispatch a request to j_security_check.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e494"></a>3.2. Extensible Deployment Descriptors</h3></div></div><div></div></div><p>The aims of JSR-154 and the early drafts of the 2.4 specification contained a proposal to allow third party extension of the deployment descriptor. The intent was to avoid the need for multiple descriptors when adding container specific deployment.</p><p>It is a attribute of J2EE that the standards based deployment descriptors are often insufficient to actually deploy real world applications and that vendor specific descriptors are commonly required. Thus as well as <tt class="constant">web.xml</tt> descriptor, you will commonly see in <tt class="constant">WEB-INF</tt> descriptors such as <tt class="constant">jboss-web.xml</tt>, <tt class="constant">weblogic.xml</tt>, <tt class="constant">jetty-web.xml</tt>, etc.. These extra descriptors provide vendor/container specific configuration for the web application.</p><p>The extensible deployment mechanism was intended to allow the vendor specific elements to be added to the standard descriptor without validation issues. Thus the configuration for elements such as EJBs would not be spread over multiple files.</p><p>While initially attractive, this proposal was eventually removed for a combination of technical, design and procedural difficulties:</p><div class="itemizedlist"><ul type="disc"><li><p>The aim of the java specification process is to encourage multiple implementations and to allow portability of compliant applications between those implementations. A single extensible deployment descriptor is counter to the aims of portability. While a single descriptor could include extensions from multiple vendors, it is doubtful if tools support for this could be provided simply or rapidly. Thus, apart from the visual confusion of multiple configurations within one descriptor, this feature invited the possibility of one vendor's tools removing or damaging the configurations of the others.</p></li><li><p>It can be argued that the non-servlet deployment elements should never have been included in the standard deployment descriptor. It would have been possible for EJB, Resources and JSPs to be configured from their own descriptors within the <tt class="constant">WEB-INF</tt> directory. Such an approach avoids unnecessary technical coupling and would also lessen the jurisdiction disputes like those caused by the inclusion of J2EE schema's in the descriptor.</p></li><li><p>For this feature to be acceptable, it had to be adopted for all J2EE component specifications. Indeed, other J2EE technologies such as CMP and EJBs suffer much greater issues of multiple descriptors and duplicate structure. However, there is no formal JCP process for getting such coordinated agreement from all JSRs involved and to impose a solution from management would diminish the value of community consultation.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e533"></a>3.3. NIO Support</h3></div></div><div></div></div><p>A much requested feature for the servlets API is support for the <tt class="constant">java.nio</tt> library. This is desirable to allow usage of the more efficient direct buffering mechanism as well as potentially using non blocking IO to free threads from the many idle persistent connections that HTTP/1.1 servers maintain.</p><p>Unfortunately there is not simple way that NIO can be retrofitted to the servlet API. There is enough chaos and confusion caused by readers/writers vs streams API duality, so adding NIO Channels into that mix is not going to be easy without a major overhaul of the API. It is also not workable to slip non-blocking semantics under the existing API. Most servlets are written expecting blocking IO and will either turn into busy loops or fail if zero bytes because a legal return for a read or a write.</p><p>An argument can also be made that moving the Servlets API towards NIO is going in the wrong direction as it will encourage the servlet writer to become more involved with the buffering and scheduling performed by the container. It may be better to increase the level of abstraction provided by the servlet API, so that they can be used more as application components and less as protocol handlers. A higher level of abstraction could allow a container more scope to use efficient mechanisms such as NIO to deal with the low level protocols, which may not be HTTP. For example, the container is already responsible for reading and parsing <tt class="constant">application/x-www-form-urlencoded</tt> content, which it could currently do with NIO behind the scenes. It may be better to extend this approach to allow the container have more responsibility for content reading/writing and let the Servlets focus more on content handling/generation.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e548"></a>3.4. SingleThreadModel Deprecated</h3></div></div><div></div></div><p>While not missing, the SingleThreadModel interface has been deprecated and will go missing in a future release. It was generally agreed that SingleThreadModel was a false friend that allowed a servlet developer to believe that they did not need to be concerned about synchronization and threading. Unfortunately this mechanism only makes this true for instance variables of the servlet itself and does not offer any protection for access to sessions, datasources or any other shared resources. As passing parameters between methods via instance variables is hardly best OO practise, there is no real benefit from this interface. However it does result in some significant additional implementation complications for containers.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e553"></a>4. Updates & Clarifications</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e556"></a>4.1. Java & HTTP Versions</h3></div></div><div></div></div><p>The versions of java required by the servlet specification have been updated to J2SE 1.3. Containers may still be developed to work with older versions of java, but a servlet can now be written to use 1.3 APIs and still be considered portable. Considering the length of time that 1.3 has been released and that 1.4 is now the norm, this is a more than reasonable change.</p><p>The specification also now requires that a servlet container supports HTTP/1.0 and HTTP/1.1 (as per RFC2616). This is actually a requirement of the Web Server associated with the servlet container and so could not strictly be policed from a compliance point of view. However the expectation is that filters and servlets may be written to read and generate the HTTP headers supported by these protocols and that whatever actual transport is used by the Servlet Container will respect the semantics of these. For example it is expected that HTTP/1.1 cache control headers will be transported to the client and any proxies even if the AJP13 protocol and apache mod_jk are the actual transport protocol used by the Servlet Container</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e563"></a>4.2. Path Mappings & Path Parameters</h3></div></div><div></div></div><p>It is a little known and little used feature of URIs that each path element may be given parameters such as:</p><pre class="programlisting">/foo;a=1;b=2/bar;c=3</pre><p>The only common use made of such parameters is by the Servlet specification itself for tracking HttpSession with URL rewriting, e.g.:</p><pre class="programlisting">/foo/bar;jsessionid=a5d5f25s727a01</pre><p>The servlet specification currently has no other support for path parameters and has always excluded them from the request parameter API:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.4.1 “<span class="quote">Path parameters that are part of a GET request (as defined by HTTP 1.1) are not exposed by these APIs. They must be parsed from the String values returned by the getRequestURI method or the getPathInfo method.</span>”</p></blockquote></div><p>The 2.4 servlet goes further in clarifying that path parameter are not considered when mapping URIs to servlets:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.11.1 “<span class="quote">The path used for mapping to a servlet is the request URL from the request object minus the context path and the path parameters.</span>”</p></blockquote></div><p>In practise, most containers will continue to only correctly handle trailing path parameters until later versions of the specification give a more detailed treatment of path parameters.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e590"></a>4.3. Error pages</h3></div></div><div></div></div><p>The 2.4 specification now better defines the mechanism that a container may use to implement the error pages. Previously the dispatch to use was undefined, so that it was not clear how filters should be applied or what values the path methods should return.</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.9.9.1 “<span class="quote">The request path and attributes are set as if a RequestDispatcher.forward to the error resource had been performed.</span>”</p></blockquote></div><p>The enhancement to filters already discussed have also made it clear when filters are applied to error pages.</p><p>The triggering of the error page mechanism has been explicitly restricted to use of the sendError method and for exceptions thrown back to the container from an original request. Use of the setStatus method and exceptions thrown by RequestDisptachers or calls to doFilter will not invoke the error page mechanism. Finally, it has been made explicit exactly when setStatus and sendError will be used:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.9.9.2 “<span class="quote">The default servlet and container will use the sendError method to send 4xx and 5xx status responses, so that the error mechanism may be invoked. The default servlet and container will use the setStatus method for 2xx and 3xx responses and will not invoke the error page mechanism.</span>”</p></blockquote></div><p>Thus it is now clear for example, that setting an error page mapping for the 200 status will not result in the error page being invoked for normal responses.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e611"></a>4.4. Welcome Files</h3></div></div><div></div></div><p>The dispatch mechanism for welcome files has also been somewhat addressed:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.9.10 “<span class="quote">The container may send the request to the welcome resource with a forward, a redirect, or a container specific mechanism that is indistinguishable from a direct request.</span>”</p></blockquote></div><p>In Australia this would be called a Claytons clarification, after a famous advertising campaign for a non alcoholic drink that used the tag line "the drink I have when I'm not having a drink". The 2.4 specification only clarifies that there is no clarity as to what dispatch mechanism should be used for welcome files. Thus it is unclear what filters will apply and what the request path methods should return and as a result many containers offer an option of several different welcome dispatch mechanisms .</p><p>The use of HTTP redirection for welcome files is common, as in 2.3 it was the only way to allow Filters to be applied to welcome files with the same semantics as normal requests. The down side if this is that another round trip to the client is required and that the full welcome file URL is exposed to the user.</p><p>The improved filter mechanism makes the HTTP forward mechanism a viable and well defined alternative for welcome file dispatch. Hopefully it will be this that future specifications recommend.</p><p>Other "clarifications" to the welcome file mechanism are discussed later in New and Unresolved Problems.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e629"></a>4.5. Life Cycles & Events</h3></div></div><div></div></div><p>The life cycle of a web application and the events associated with it have been clarified with several changes throughout the specification and javadoc, plus the addition of section SRV.9.12 on web application deployment.</p><p>It has now been made explicit that the <tt class="constant">ServletContextListener.contextInitialized</tt> method is called before any filters or servlets are initialized. It thus joins <tt class="constant">HttpSessionListener.sessionDestroyed</tt> as an event whose name has the incorrect tense and thus can be misleading. Hopefully future versions of the specification will deprecate these methods and rename them <tt class="constant">contentInitialize</tt> and <tt class="constant">destroySession.</tt></p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e647"></a>5. New and Unresolved Problems</h2></div></div><div></div></div><p>Despite the numerous clarifications (and in some cases because of them), there are still some significant problems and ambiguities in the 2.4 specification.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e652"></a>5.1. Welcome Files</h3></div></div><div></div></div><p>In addition to the non-clarification of welcome file dispatch mechanisms, the 2.4 servlet specification contains a new feature that allows servlets to be welcome "files" even if no real file exists:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.9.10 “<span class="quote">The Web server must append each welcome file in the order specified in the deployment descriptor to the partial request and check whether a static resource or servlet in the WAR is mapped to that request URI.</span>”</p></blockquote></div><p>The intent of this change is to allow the welcome file mechanism to invoke template mechanisms such as TEA and Velocity that often store their templates outside of the normal web application resource hierarchy. Thus if a request is received for <tt class="constant">/foo/</tt>, the welcome mechanism can now dispatch this <tt class="constant">to /foo/index.tea</tt> even if the file <tt class="constant">index.tea</tt> does not exist in the <tt class="constant">foo</tt> directory.</p><p>Other than stretching the meaning of the word "file", this change initially looks appealing. Unfortunately it represents a significant change in the semantics of the welcome file mechanism and could break many web applications if implemented as specified.</p><p>Consider the following section of a deployment descriptor:</p><pre class="programlisting"><welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
</welcome-file-list></pre><p>which is applied to a web application with the following file hierarchy:</p><pre class="programlisting">webapp
|-- WEB-INF
| `-- web.xml
|-- dirA
| `-- index.jsp
`-- dirB
`-- index.html</pre><p>A request to <tt class="constant">/dirA/</tt> will be handled as expected, as a file <tt class="constant">index.jsp</tt> exists and the request will be dispatched or redirected to <tt class="constant">/dirA/index.jsp</tt>. On many containers, this will match a JSPServlet mapped to *.jsp and execute normally.</p><p>Unfortunately, a request to <tt class="constant">/dirB/</tt> will not serve <tt class="constant">/dirB/index.html</tt> as would be the case with the current 2.3 specification. Instead the first welcome file mapping of /dirB/index.jsp will be tried and will result in a match of the JSPServlet mapped to *.jsp. Thus a 2.4 compliant container will dispatch or redirect this request to the non-existent dirB/index.jsp resource. At best this will result in a 404 error, or possibly a 500 error complete with a nasty exception.</p><p>The situation is further muddied by the specification, as it's own examples have not been updated to reflect the inclusion of servlet mappings to the welcome file mechanism. It shows requests being passed to the default servlet, when a mapping to a JSPServlet is the more likely result.</p><p>The great pity of this flawed solution is that the problem really just reflects the deficiancy of the servlet URL paterns supported by the specification. If the URL patterns were able to support even simple wildcard pattern matching, it would not be difficult to map a servlet to every URL ending in /. Even without such a change to the specification, the desired functionality of a servlet welcome resource can easily be provided with the following simple Filter:</p><pre class="programlisting">public class WelcomeFilter implements Filter
{
private String welcome;
public void init(FilterConfig filterConfig)
{
welcome=filterConfig.getInitParameter("welcome");
}
public void doFilter(ServletRequest request,ServletResponse response,FilterChain chain)
throws IOException, ServletException
{
String path=((HttpServletRequest)request).getServletPath();
if (welcome!=null && path.endsWith("/"))
request.getRequestDispatcher(path+welcome).forward(request,response);
else
chain.doFilter(request, response);
}
public void destroy() {}
}</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e711"></a>5.2. RequestDispatchers vs Wrappers</h3></div></div><div></div></div><p>The request wrapping features introduced in 2.3 are well defined within the section of the specification that discusses filters, where it is made clear that specific types of wrapped requests and responses may be passed along a filter chain and over RequestDispatchers:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.6.2.2 “<span class="quote">... When a filter invokes the doFilter method on the containers filter chain implementation, the container must ensure that the request and response object that it passes to the next entity in the filter chain, or to the target web resource if the filter was the last in the chain, is the same object that was passed into the doFilter method by the calling filter. </span>”</p><p>“<span class="quote">The same requirement of wrapper object identity applies to the calls from a servlet or a filter to RequestDispatcher.forward or RequestDispatcher.include, when the caller wraps the request or response objects. In this case, the request and response objects seen by the called servlet must be the same wrapper objects that were passed in by the calling servlet or filter..</span>”</p></blockquote></div><p>While this direct passing of wrapped objects is straight forward for filters, unfortunately this requirement proves ambiguous and undesirable when applied to RequestDispatchers. Fundamentally the container cannot guarantee that request and responses will be passed unwrapped through a RequestDispatcher as the enhanced Filter mechanism now allows filters and thus wrappers to applied to dispatching.</p><p>Furthermore, the specification of the RequestDispatch mechanism is very explicit about the treatment of path methods in a passed request:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.8.4 “<span class="quote">The path elements of the request object exposed to the target servlet must reflect the path used to obtain the RequestDispatcher. The only exception to this is if the RequestDispatcher was obtained via the getNamedDispatcher method.</span>”</p></blockquote></div><p>Thus, as a user supplied wrapper is free to change the values return from the path methods, SRV.8.4 indicates that the container must override any such user supplied wrappers and force the values to be those specified by the RequestDispatcher.</p><p>Containers commonly implement the RequestDispatcher requirements by applying their own request wrapper during dispatch. Containers that respect SRV.6.2.2 “<span class="quote">wrap under</span>” user supplied wrappers, while those that respect SRV.8.4 “<span class="quote">wrap over</span>” user supplied wrappers. These two approaches can both be justified by refering to the specification, but result if very different behaviours.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e743"></a>5.2.1. “<span class="quote">Wrap Over</span>” vs “<span class="quote">Wrap Under</span>”</h4></div></div><div></div></div><p>Consider the following HttpServletRequestWrapper. It has been written to assist converting a webapplication from a case insensitive environment to a case sensitive one, so it converts all path methods to return lowercase values so that mixed case bookmarks and static content continue to work. The filter has been written to cache the results of toLowercase to avoid multiple conversions:</p><pre class="programlisting">public LCRequestWrapper extends HttpServletRequestWrapper
{
LCRequestWrapper(HttpServletRequest r) {super(r);}
public String getServletPath()
{
if (servletPath==null)
servletPath=super.getServletPath().toLowercase();
return servletPath;
}
public String getPathInfo()
{
if (pathInfo==null)
{
pathInfo=super.pathInfo();
if (pathInfo!=null)
pathInfo=pathInfo.toLowercase();
}
return servletPath;
}
private String servletPath;
private String pathInfo;
}</pre><p>This wrapper looks straight forward, but can have very unexpected behaviour if used in a “<span class="quote">wrap under</span>” container. When a dispatch is done, the container will insert a request wrapper underneath this user supplied wrapper, so that the target resource will call the user wrapper directly. The user wrapper may call super methods which may return different values for the duration of the dispatch.</p><p>If the dispatching resource calls a path method before the request is forwarded to the target resource, then the target resource will see the cached value calculated before the dispatch, which will not be the correct value for the target.</p><p>If a path method is first called by the target resource, then the cached value will be set from dispatched values of the path. This value will be incorrectly returned to any call made by the dispatching servlet after the dispatch.</p><p>If “<span class="quote">wrap over</span>” semantics are applied to this example, then the behaviour is well defined as the wrapped path methos are not visible during dispatch as they are hidden by the SRV.8.4 compliant wrapper.</p><p>While this example is somewhat contrived and can simply be fixed by removing the value cache, it does indicate that “<span class="quote">wrap under</span>” semantics can be more complex than first appearances. To avoid such indeterminate behaviour, a wrapper must avoid having any fields that are derived from methods that may be changed during a request dispatch.</p><p>Unfortunately some values, such as streams and writers must be cached by a wrapper as they cannot be reproduced on each call. The following filter follows a similar pattern to most filters that wrap the responses stream or writer with a specialized version for compression or encryption etc.</p><pre class="programlisting">public MyResponseWrapper extends HttpServletResponseWrapper
{
MyResposneWrapper(HttpServletResponse r) {super(r);}
public ServletOutputStream getOutputStream() throws IOException
{
if (_writer!=null)
throw new IllegalStateException("getWriter called");
if (_out==null)
_out=new MyOutputStream(super.getOutputStream());
return _out;
}
public PrintWriter getWriter() throws IOException
{
if (_out!=null)
throw new IllegalStateException("getOutputStream called");
if (_writer==null)
_writer=new MyWriter(super.getWriter());
return _writer;
}
ServletOutputStream _out;
PrintWriter _writer;
}</pre><p>This wrapper contains the state of which type of output stream has been requested. Consider if this wrapper is passed to a servlet that calls getOutputStream before including of a resource that is generated using getWriter.</p><p>The call to getOutputStream will initialize the specialized MyOuputStream. If wrap under semantics are used during the include, then this wrapper will also be passed to the second resource. When getWriter is called an IllegalStateException will result. This implies that the user of RequestDispatch.include must be aware of the implementation details of the requested resource and can only use those with the same flavour of implementation.</p><p>With “<span class="quote">wrap over</span>” semantics, the container is given the opportunity to hide the state of the including resource. The included resource can be passed a response wrapper provided by the container that itself wraps the MyResponseWrapper instance. When getWriter is called, it initially calls the wrapped getWriter which will thow an IllegalStateException. The container supplied wrapper can catch this exception and then call the wrapped getOutputStream and wrap the specialized stream returned in an OutputStreamWriter.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e786"></a>5.2.2. Resolution of RequestDispatchers vs Wrappers</h4></div></div><div></div></div><p>The next version of the specification must address this conflict if portable filters and servlets are to be written using request and response wrapping. To resolve which part of the specification should prevail we need to examine the motivation for the requirement for direct passing of objects:</p><div class="blockquote"><blockquote class="blockquote"><p>SRV.6.2.2 “<span class="quote">... In this model, the developer not only has the ability to override existing methods on the request and response objects, but to provide new API suited to a particular filtering task to a filter or target web resource down the chain.</span>”</p></blockquote></div><p>This close coupling of components is not best practise in an environment where the development of utility filters and wrappers is encouraged to intercept arbitrary requests. For example if a web application was written to assume the direct passing of a wrapper type from a dispatching servlet to a resource producing HTML, then the application of the common compression filter to all HTML resources would break this assumption and cause a class cast exception.</p><p>There exist several other mechanism to allow required coupling between web application components that are more flexible and not vulnerable to the extended filter mechanism. Static methods, request attributes, session attributes, ThreadLocals and unwinding of wrappers can all be used to achieve the aim of providing new API for a web application.</p><p>It is the author's hope that the next revision of the servlet specification will relax the object passing requirements of SRV.6.2.2 and discourage the associated closely couple programming model. The “<span class="quote">wrap over</span>” semantics should be specifically required for RequestDispatching.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e805"></a>5.3. Distributable Web Applications</h3></div></div><div></div></div><p>The specification of distributed HttpSessions remains very poor in the 2.4 specification with no clarifications made to any of the significant omissions in the specification:</p><div class="itemizedlist"><ul type="disc"><li><p>Should the HttpSession.setAttribute method be considered pass-by-value or pass-by-reference? i.e. at what time should the session values be distributed. Non distributed sessions allow the value to be changed at any time by any thread or mechanism and the next call to getAttribute will return the updated value. However, unlike EJB's there is no uniform access path to session values nor transactional model, so such changes cannot simply be distributed. Many distribution implementation avoid this issue by changing the semantics for distributed sessions to be pass-by-value and only distributing session values when setAttribute is called.</p></li><li><p>How are bind and unbind events handled in a distributed session? Is bind called in every JVM that value is distributed to? Or is it only called in the JVM where the value was originally added and then distributed to other JVMs without further events.</p></li><li><p>How is non-gentle migration handled? If a node fails and no session passivation event was handled, should a session activation event be issued on the new node?</p></li></ul></div><p>Until these issues are clarified, distribution wil remain a very container specific mechanism.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e822"></a>6. Conclusion</h2></div></div><div></div></div><p>The 2.4 servlet specification is definitely a much better specification than it's forerunners, with the main achievement being the extension of Filters to be an integral part of all request dispatching within a container. There have also been numerous small but valuable clarifications that have not been covered by this article but are listed in SRV.S.16.</p><p>Unfortunately significant problems remain in the specification, some new ones have been added and some much requested features have been deferred. Other changes are at best of dubious added value and the benefits or otherwise of the structural and procedural changes represented by the J2EE based schema's have yet to play out.</p><p>Hopefully, most of these issues will be below the radar of your average servlet user as IDE's, tools and web frameworks are already doing much of the work to deal directly with the servlet API. Developers should be encorouged to start evaluations of containers supporting this revision.</p></div><div class="appendix" lang="en"><h2 class="title" style="clear: both"><a name="d0e831"></a>A. References</h2><div class="variablelist"><dl><dt><span class="term">Servlet Home page:</span></dt><dd><p><a href="http://java.sun.com/products/servlet" target="_top">http://java.sun.com/products/servlet</a></p></dd><dt><span class="term">JSR-154 Servlet 2.4 Specification working group:</span></dt><dd><p><a href="http://www.jcp.org/en/jsr/detail?id=154" target="_top">http://www.jcp.org/en/jsr/detail?id=154</a></p></dd><dt><span class="term">Java Community Process:</span></dt><dd><p><a href="http://www.jcp.org" target="_top">http://www.jcp.org</a></p></dd><dt><span class="term">Jetty servlet container:</span></dt><dd><p><a href="http://jetty.mortbay.org" target="_top">http://jetty.mortbay.org</a></p></dd><dt><span class="term">Jakarta Tomcat servlet container:</span></dt><dd><p><a href="http://jakarta.apache.org/tomcat" target="_top">http://jakarta.apache.org/tomcat</a></p></dd></dl></div></div></div></body></html>
