Servlet 3.1 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 you use the Servlet 3.1 feature.
You 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 you must use the Servlet 3.1 feature. If an existing application would be 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. It is not possible to use both the Servlet 3.0 and Servlet 3.1 features in the same server. It is an error to configure both features. If you configure both features, neither servlet feature is loaded.
- Changes that are required by clarifications in the Servlet 3.1 specification.
- Changes that are required for the Servlet 3.1 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 was not.
URL pattern clashes
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()
You can 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 that is 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()
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.
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 that is 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
, andibm-web-ext.xml
files.- Rule 1:
web.xml
andweb-fragment.xml
files.When a default error page is specified in the
web.xml
file, it overrides (masks) any default error page that is specified in aweb-fragment.xml
file. Also, there is no error if, in addition, multipleweb-fragment.xml
files specify default error pages. - Rule 2:
web-fragment.xml
andweb-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 moreweb-fragment.xml
files. - Rule 3:
ibm-web-ext.xml
andweb.xml
orweb-fragment.xml
files.The rule of precedence between the
ibm-web-ext.xml
file and either theweb.xml
orweb-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 anibm-web-ext.xml
file has precedence over a default error page that is defined inweb.xml
orweb-fragment.xml
files.Note: When the web container uses feature level 3.0, you 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 that is specified by
web.xml
orweb-fragment.xml
file has precedence over a default error page that is specified in theibm-web-ext.xml
file. - Rule 1:
- Schema rules
-
Two rules apply for whether default error pages are processed in
web.xml
orweb-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 WebSphere Application Server traditional V8.0, did not support default error pages in the V8.0 general availability release. Support for default error pages was added to WebSphere Application Server traditional, in a service pack, by APAR PM94199. Support for default error pages was added to 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
orweb-fragment.xml
files that use a Servlet 3.0 schema, the default error pages are processed only ifcom.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 theibm-web-ext.xml
file is used. - Case 2: Default error pages by using web container feature version 3.1.
When the web container feature version is 3.1 or higher, a default error page that is specified in the
web.xml
file or theweb-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.
- Rule 1: Default error pages using Servlet 3.0 schema and using web container feature version
3.0.
web-fragment.xml
file has no schema from Servlet 2.5.- Error page and default error page examples
- A default error page that is 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>
- 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">