Servlet behavior changes

Servlet behavior changes

The Servlet 3.1 implementation contains behavior changes that might cause an application that was written for Servlet 3.0 to behave differently or fail when using the Servlet 3.1 feature.

We can choose between the Servlet 3.0 and Servlet 3.1 feature implementations for each server instance, with consideration for behavior changes. If the required behavior is contained in the Servlet 3.1 feature only, then use the Servlet 3.1 feature. If an existing application is adversely affected by behavior changes in the Servlet 3.1 feature, then using the Servlet 3.0 feature preserves the existing behavior for that application. We cannot use both the Servlet 3.0 and Servlet 3.1 features in the same server. If we configure both features, neither servlet feature is loaded.

The behavior changes are introduced for the following reasons:

Changes required by clarifications in the Servlet 3.1 specification.
Changes required for the implementation to pass the Servlet 3.1 Technology Compatibility Kit (TCK).
Changes to improve the servlet implementation.

Programmatically added servlets, filters, and listeners

A clarification from the Servlet 3.1 specification now makes it illegal for a ServletContextListener to programmatically configure servlets, filters, or listeners if the ServletContextListener was not declared in the web.xml file or web-fragment.xml file or was not annotated with @WebListener. As a result, any call on the ServletContext to perform such programmatic configuration results in an UnsupportedOperationException.

Forward after asynchronous processing is started

In the Servlet 3.0 implementation, a response is always closed before the forward method of the RequestDispatcher interface returns. However, due to a clarification in the Servlet 3.1 specification, the Servlet 3.1 implementation does not close or flush the response before the forward method of the RequestDispatcher interface returns, if the request is put into the asynchronous mode. This change might affect existing 3.0 applications, which add response output on return from forward because such response data is now sent, whereas in Servlet 3.0, it is not.

URL pattern clashes

In Servlet 3.0, an application starts successfully even when a URL pattern was mapped to multiple servlets. However, due to a clarification in the Servlet 3.1 specification, the application must fail to start. In the Liberty Servlet 3.1 implementation, a message is output and the application fails to start:
SRVE9016E: Unable to insert mapping [{0}] for servlet named [{1}]. The URL pattern is already defined for servlet named [{2}].

Explanation: There is an application error. A servlet mapping URL pattern should not map to multiple servlets.

User action: Change the URL pattern for the servlet mapping.
ServletContext.getMinorVersion()

In the Servlet 3.0 feature implementation, this API returns 0.

In the Servlet 3.1 feature this API now returns 1.

ServletContext.getServerInfo()

In the Servlet 3.0 feature implementation, this API returns SMF WebContainer.

In the Servlet 3.1 feature this API now returns IBM WebSphere Liberty/8.5.5.<x>, where <x> is the WebSphere Application Server fix pack number.

ServletResponse.reset()

Use ServletResponse.reset() to clear any buffered response data, the status code, and response headers when a response is not already committed. If the Servlet 3.1 feature is being used, this method also clears any record of ServletResonse.getWriter() or ServletResponse.getOutputStream() that were previously called.

X-Powered-By header

In the Servlet 3.0 feature implementation, the X-Powered-By header is set to Servlet/3.0. In the Servlet 3.1 feature implementation, the X-Powered-By header is set to Servlet/3.1.

Resource reference injection target merging

In the Servlet 3.0 specification, the <injection-target> elements of a resource reference defined in a web-fragment.xml file are added only to the parent web.xml file if the web.xml resource reference definition with the same name has no <injection-target> elements. In the Servlet 3.1 specification, it is clarified that all <injection-target> elements in web-fragment.xml descriptors are added to the parent web.xml descriptors list of <injection-target> elements for a resource reference of the same name. When the Servlet 3.1 feature is in use, this feature might change existing application function by activating injection targets that were previously excluded from the web.xml file.

Tolerance of duplicate elements in web descriptors

In the Servlet 3.1 specification, it was clarified that a web.xml file cannot contain two <absolute-ordering> elements. Deployment of an application with multiple <absolute-ordering> elements fails. Additionally, web-fragment.xml descriptors cannot contain two <ordering> elements. Deployment of an application with multiple <ordering> elements fails. Previously, the deployment would not fail, but the function of the elements might be indeterminate.

Web fragment ordering change in metadata - complete cases

The processing of the <absolute-ordering> element is changed in cases where a web.xml descriptor is marked metadata-complete="true". Previously in metadata-complete="true" cases, all web fragment archives would be used. When the Servlet-3.1 feature is in use, the <absolute-ordering> element in metadata-complete cases is considered to be complete. This change results in fragments that are not listed in the <absolute-ordering> element to be excluded from processing.

AsyncContext.dispatch()

If our request invokes AsyncContext.dispatch() with no parameters, the request is dispatched to the original URL. If we include a query string in the original request, and forward to another resource using a different query string, which invokes AsyncContext.dispatch(), the request parameter values that are returned to the original resource change with the specification level. With Servlet 3.0, the request accesses the parameters passed on the query string of the original request. With Servlet 3.1, it accesses the parameters passed on the query string of the second resource. See the following example:
Request for /FirstResource?param=One
First Resource:
    getParameter("param") returns "One"
           forward request to /SecondResource?param=Two
SecondResource
           getParameter(param) returns "Two"
           ac.start()
           ac.dispacth() dispatches to /FirstResource
First Resource
           Servlet-3.0 feature : getParamter("param") returns "One"
           Servlet-3.1 feature : getParameter("param") returns "Two"

This change was required by the Servlet 3.1 TCK.
Obtain the request or response object after an AsyncContext.dispatch() or AsyncContext.complete() is not permitted and results in the following exception:
java.lang.IllegalStateException: SRVE9015E: Cannot obtain the request or response object after an AsyncContext.dispatch() or AsyncContext.complete().
    at com.ibm.ws.webcontainer31.async.AsyncContext31Impl.getRequest(AsyncContext31Impl.java:72)
    [...]
SessionCookieConfig.setComment()

According to the Java Servlet 3.1 Specification, this API returns an illegalStateException if it is called after the ServletContext completes initialization, and the Servlet 3.1 feature follows this required behavior. However, the Servlet 3.0 feature does not prevent use of this API after the context is initialized and as a result, applications that depend on the Servlet 3.0 feature behavior will not work with the Servlet 3.1 feature.

sendRedirect(java.lang.String location) API

The sendRedirect(java.lang.String location) API accepts relative URLs; however, the servlet container must convert the relative URL to an absolute URL before it can send the response to the client. If the location is relative without a leading '/' (folder/default.jsp), the container interprets it as relative to the current request URI. If the location is relative with a leading '/', the container interprets it as relative to the servlet container root.

For example, if the redirection location provided by application is folder/default.jsp, with no leading '/', and the inbound request URL is http://host:port/context_root/folder or http://host:port/context_root/folder/, the request is redirected to http://host:port/context_root/folder/folder/default.jsp, which is relative to the current request URI.

This behavior is found in the Servlet 3.0 feature when the com.ibm.ws.webcontainer.redirectwithpathinfo property is set to true. This property is ignored in the Servlet 3.1 feature and the behavior defaults, as described.

Default error pages

The IBM extended function is the ability to specify a default error page with a web extension, such as ibm-web-ext.xml.

As a function of Servlet 3.0 and higher, default error pages are a modification of the ability to specify error pages. As with normal (non-default) error pages, default error pages are specified in web module descriptors (web.xml), and in web fragment descriptors (web-fragment.xml).

Normal (non-default) error pages specify either an exception-type or an error-code. A default error page omits both exception-type and error-code. A default error page is used when a servlet throws an exception or sets an error-code result and no configured error page matches the type of the exception or matches the set error code.

The ability to define default error pages is provided by the Servlet 3.0 specification, and is supported by the Servlet 3.0 schemas. Default error pages are error pages that do not contain an exception-type or an error-code element, according to the Servlet 3.1 specification.

Examples of error pages and default error pages follow.

Default error page precedence rules

Three rules apply for determining precedence for default error pages in the web.xml, web-fragment.xml, and ibm-web-ext.xml files.

Rule 1: web.xml and web-fragment.xml files.
When a default error page is specified in the web.xml file, it overrides (masks) any default error page specified in a web-fragment.xml file. Also, there is no error if, in addition, multiple web-fragment.xml files specify default error pages.

Rule 2: web-fragment.xml and web-fragment.xml.
When a default error page is not specified in the web.xml file, an error condition exists if different default error pages are specified by two or more web-fragment.xml files.

Rule 3: ibm-web-ext.xml and web.xml or web-fragment.xml files.
The rule of precedence between the ibm-web-ext.xml file and either the web.xml or web-fragment.xml files depends on the web container feature level.

When the web container feature level is 3.0, a default error page that is defined by an ibm-web-ext.xml file has precedence over a default error page defined in web.xml or web-fragment.xml files.
When the web container uses feature level 3.0, we cannot use Servlet 3.1 schemas. Refer to the rule on using default error pages for servlet 3.0 schemas.
When the web container feature level is 3.1 or higher, a default error page specified by web.xml or web-fragment.xml file has precedence over a default error page specified in the ibm-web-ext.xml file.

Schema rules

Two rules apply for whether default error pages are processed in web.xml or web-fragment.xml files. The rules depend on the web container feature version, which Servlet schema is in use, and the setting of a Java custom property.

These rules arose because IBM WAS traditional V8.0, did not support default error pages in the V8.0 general availability release. Support for default error pages was added to WAS traditional, in a service pack, by APAR PM94199. Support for default error pages was added to WAS Liberty, in a service pack, by APAR PI05845. Because these updates are a change of externally visible function, the new function is disabled by default and must be enabled by a Java system property.

Rule 1: Default error pages using Servlet 3.0 schema and using web container feature version 3.0.
When the web container feature version is 3.0 and a default error page is specified in web.xml or web-fragment.xml files that use a Servlet 3.0 schema, the default error pages are processed only if com.ibm.ws.webcontainer.allowdefaulterrorpage Java system property is set to true. When the Java system property is not set, or is not set to true, the default error page is ignored. A default error page that is specified by the ibm-web-ext.xml file is used.

Case 2: Default error pages using web container feature version 3.1.
When the web container feature version is 3.1 or higher, a default error page specified in the web.xml file or the web-fragment.xml file is always processed, regardless of what servlet schema version is used, and regardless of whether the Java custom property is set.

This case occurs when a descriptor uses a Servlet 3.1 schema, since the processing of a descriptor that uses a Servlet 3.1 schema requires web container feature version 3.1.

Web fragments were not added until Servlet 3.0. The web-fragment.xml file has no schema from Servlet 2.5.
Error page and default error page examples
A default error page defined in an ibm-web-ext.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<web-ext xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
    version="1.0">

	<default-error-page uri="/ExtErrorPage.html"/>
</web-ext>
An error-code error page element, which is defined in either the web.xml file or web-fragment.xml file:
<error-page>
		<error-code>404</error-code>
			<location>/ErrorCodeErrorPage.html</location>
</error-page>
An exception-type error page element, which is defined in either the web.xml file or web-fragment.xml file:
<error-page>
		<exception-type>javax.servlet.ServletException</exception-type>
		<location>/ExceptionTypeErrorPage.html</location>
</error-page>
A default error page element, which is defined in either the web.xml file or web-fragment.xml file:
<error-page>
		<location>/DefaultErrorPage.html</location>
</error-page>
Schema examples
Example header of a web.xml file that uses a Servlet 2.5 schema:
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
      version="2.5">
Example header of a web.xml file that uses a Servlet 3.0 schema:
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">
Example header of a web.xml file that uses a Servlet 3.1 schema:
<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
    version="3.1">
Example header of a web-fragment.xml file that uses a Servlet 3.0 schema:
<?xml version="1.0" encoding="utf-8"?>
<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
      version="3.0">
Example header of a web-fragment.xml file that uses a Servlet 3.1 schema:
<?xml version="1.0" encoding="utf-8"?>
<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns="http://xmlns.jcp.org/xml/ns/javaee"
      xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-fragment_3_1.xsd"
      version="3.1">