New functions for the Servlet 3.1 feature

The Servlet 3.1 feature provides full support for the Servlet 3.1 specification.

Descriptions of the new Servlet 3.1 functions are provided in the Servlet 3.1 specification and are not described here. However, additional considerations for the Servlet 3.1 feature :

Asynchronous I/O

A new feature of the Servlet 3.1 feature specifies that when the non-blocking read is started, any resource during the remaining request lifetime cannot call APIs, which can result in a blocking read. For example, for a POST request after the read listener is set by the resource, any subsequent call to getParameter() and getPart() API results in an IllegalStateException.

We must consider setting timeout with the AsyncContext.setTimeout API when you work with async servlets, otherwise the container default value (for example, 30 seconds) is used. The timeout resets each time async starts using the ServletRequest. StartAsync API is called and expires when the AsyncContext.complete API is not called within the timeout period that follows the last time async started. When we use the async I/O support provided by the Servlet-3.1 feature, set the timeout value with the AsyncContext.setTimeout API to also allow for async I/O to complete. Completion depends on other external factors, such as environment or network speed.

Upgrade handling

Non-blocking read and write (introduced with the Servlet 3.1 feature for upgrade), has no limits on how much time the server waits when the read or write operations are async. We can set the timeouts with the web container custom properties in server.xml, such as upgradereadtimeout and upgradewritetimeout. For example, set a timeout of 5 seconds, as follows:

<webContainer upgradeReadTimeout="5000" />
<webContainer upgradeWriteTimeout="5000" />

The request must not be upgraded using the upgrade feature for Servlet 3.1 when the request is being handled by async servlet.

The application that supports the Servlet 3.1 feature for upgrade requires that the connection on the upgraded request remains open between the client and the application that hosts the upgrade. If the application does not initiate the WebConnection close() when the upgrade processing is complete from its handler or any other resources, such as ReadListener or WriteListener, then the TCP connection remains open until the server recycles.

When we use an UpgradeHandler and a ReadListener from the Servlet 3.1 feature, the ReadListener.onAllDataRead method is invoked only when the client closes the connection to the server that hosts the upgraded application. The Javadoc for onReadListener.onAllDataRead states that "Invoked when all data for the current request is read.". In the Upgrade case, the server does not know the end of the data because upgraded data is not delimited the way that HTTP request body data is. Aside from when the client connection closes, there is no determination for the end of the data.

Form based authentication

After successful authentication, a client is redirected to the resource of the original request. The Servlet 3.1 specification specifies: "To improve the predictability of the HTTP method of the redirected request, containers should redirect using the 303 (SC_SEE_OTHER) status code, except where interoperability with HTTP 1.0 user agents is required; in which cases the 302 status code should be used." The Servlet-3.1 feature maintains interoperability with HTTP 1.0 user agents and always uses the 302 status code. For more information on configuring Servlet 3.1 for security, read the Configuring the Liberty profile for Servlet 3.1 topic.

Large post data

The addition of the ServletRequest.getContentLengthLong() API requires support for receiving post data of a length greater than Integer.MAX_VALUE and cannot be fully accommodated in a single-byte array or string.

This addition has implications when you obtain post data content that use APIs that return content in a string or byte[]. For example, the javax.servlet.ServletRequest methods for accessing parameters:

String    getParamter(String name)
String[]  getParameterValues()
Map<String,String> getParameterMap()

It is possible to send post data containing multiple parameters, which when combined, have a length of greater than Integer.MAX_VALUE. However, each individual parameter name and parameter value must be less than Integer.MAX_VALUE in length.

Sending a large amount of post data include these additional considerations:

• We must send post data in chunks of less than Integer.MAX-VALUE in length.

• Post data that is processed by the web container, such as parameters or parts, must be fully read before processing starts. The post data might impose significant memory requirements for large post data because it might require as much memory as double the size of the post data in order for web container processing to be successful.

Parent topic: Administer web applications

Tasks:

Configure Java Servlet 3.1 support for security