Servlet 3.1 feature functions

The product supports the Servlet 3.1 specification. View the clarifications and descriptions of the functions available.

Descriptions of the Servlet 3.1 functions are provided in the Java™ Servlet Specification and are not described in the product documentation. However, more considerations for the Servlet 3.1 functions are as follows:

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.

You 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 by 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 you use the async I/O support that is 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 processing

Important: Use the ServletOutputStream class with the WriteListener interface and the ServletInputStream class with the ReadListener interface. Do not use these classes with the ObjectInputStream class or the ObjectOutputStream class. These classes circumvent some of the required checks for the ReadListener and WriteListener interfaces, mainly the isReady checks, and can cause unexpected behavior.
Upgrade processing is a Servlet 3.1 feature that has non-blocking read and write capability. When the read or write operations are async, there are no limits on how much time the server waits for the operation to complete. You can set the timeouts with the web container custom properties in the server.xml file, such as upgradereadtimeout and upgradewritetimeout. See the following example of a timeout of 5 seconds:
<webContainer upgradeReadTimeout="5000" />
<webContainer upgradeWriteTimeout="5000" />

The request must not be upgraded by 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 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, the TCP connection remains open until the server recycles.

When you 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 returns the following message: 
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 must 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 must be used. The feature maintains interoperability with HTTP 1.0 user agents and always uses the 302 status code. For more information on configuringServlet 3.1 for security, read the Configuring Liberty 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 that contains 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:
  • You 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.