Servlet 6.1 offers several new features to enhance development experience and debug enterprise application. It also provides some clarifications for the existing API behaviors

New Servlet Response sendRedirect

Servlet response has three new APIs that allow a send redirect to include an optional response data and/or set any compliant status code, instead of the default 302.

(1) sendRedirect(String location, boolean clearBuffer)
(2) sendRedirect(String location, int statusCode)
(3) sendRedirect(String location, int statusCode, boolean clearBuffer)

Default values:

boolean clearBuffer = true
int statusCode = 302

All sendRedirect methods eventually calls to (3) with the default values of clearBuffer and statusCode if not specified

clearBuffer = true will reset/clear the current response buffer if response has not committed.

If the response’s buffer is clear, the default globalization HTML message will be used:

<html><body><p>Redirecting to <a href=\"{0}\"></a></p></body></html>

The message is encoded, with {0} being the provided location.

Note: statusCode can now be set to any integer status code without verification; however, setting it to an arbitrary number may cause a client (i.e browser) to not follow up with a redirect request.

New Servlet Request attributes

Two new request's attributes are introduced to assist with the application's error handling process.

jakarta.servlet.error.method – the initial request HTTP method
jakarta.servlet.error.query_string – the initial request query string

All error dispatches are now performed as HTTP GET instead of the initial request’s method. The dispatchers can retrieve the original request's method via jakarta.servlet.error.method

When requested with HTTPS, application can check the secure protocol for its request using a new request attribute

jakarta.servlet.request.secure_protocol

New APIs to read and write with java.io.ByteBuffer

The jakarta.servlet.ServletInputStream can read input data using a ByteBuffer

int read(ByteBuffer)

The jakarta.servlet.ServletOutputStream can write out using a ByteBuffer

void write(ByteBuffer)

New character encoding using java.nio.charset.Charset

Several new APIs to support the setting of request and response character encoding using a Charset instead of a String

jakarta.servlet.ServletContext:
    void setRequestCharacterEncoding(Charset)
    void setResponseCharacterEncoding(Charset)

jakarta.servlet.ServletRequest:
    void setCharacterEncoding(Charset)
    
jakarta.servlet.ServletResponse:
    void setCharacterEncoding(Charset)

New HttpSession APIs

To interact with a jakarta.servlet.http.HttpSession outside the scope of a HTTP request, new APIs are added to the HttpSession

public static interface Accessor {
    void access(Consumer<HttpSession> sessionConsumer)
}

default HttpSession.Accessor getAccessor(){
    return null;
}

The session's _lastAccessedTime field from the HttpSession.getLastAccessedTime() is updated automatically whenever the Accessor.access() is called.

Clarification: 1. Canonicalization applies to all ServletContext methods that accept a path parameter.

All String path parameters must be validated against the Servlet 3.5.2. URI Path Canonicalization before being processed.

jakarta.servlet.ServletContext:
    getRealPath(String)
    getRequestDispatcher(String)
    getResource(String)getResourceAsStream(String)
    getResourcePaths(String)

jakarta.servlet.ServletRequest:
    getRequestDispatcher(String)

Returns null if the String path fails the URI Path Canonicalization verification.

Previously - these methods had been returned null when paths could not be resolved. This clarification adds an early path verification and returns null sooner if the path is not compliant with the rules.

Clarification: 2. ServletRequest.getParameter() and its family methods can throw a Runtime Exception.

ServletRequest.getParameter() and the other parameter methods are now documented to throw a java.lang.IllegalStateException if the call triggers the parsing of the parameters resulted in an error.

jakarta.servlet.ServletRequest:
    String getParameter(String name)
    Map<String,String[]> getParameterMap()
    Enumeration<String> getParameterNames()
    String[] getParameterValues(String name)

Since Servlet 6.1 – throw java.lang.IllegalStateException

Previously - throw java.lang.IllegalArgumentException

Clarification: 3. HttpServletResponse.addDateHeader(String, long) can have multiple values for a header.

HttpServletResponse.addDataHeader() can add same header name with multiple different value. The response will contain several same name headers.

Example:

    final long DATE_2022 = 1672427151000L; //Fri, 30 Dec 2022 19:05:51 GMT
    final long DATE_2023 = 1703963151000L; //Sat, 30 Dec 2023 19:05:51 GMT

    HttpServletResponse.addDateHeader("TEST-ADD-DATE-HEADER", DATE_2022);
    HttpServletResponse.addDateHeader("TEST-ADD-DATE-HEADER", DATE_2023);

Response contains multiple headers with the same name but different values:

    TEST-ADD-DATE-HEADER: Fri, 30 Dec 2022 19:05:51 GMT
    TEST-ADD-DATE-HEADER: Sat, 30 Dec 2023 19:05:51 GMT

Previously – only the last addDateHeader() was returned : TEST-ADD-DATE-HEADER: Sat, 30 Dec 2023 19:05:51 GMT

Clarification: 4. HttpServletMapping.getMatchValue() for mappingMatch “PATH” must exclude the leading "/"

Consider web.xml :

    <servlet>
        <servlet-name>MyServlet</servlet-name>
        <servlet-class>MyServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>MyServlet</servlet-name>
        <url-pattern>/MyServlet</url-pattern>
        <url-pattern>/path/*</url-pattern>
    </servlet-mapping>

Request URI: /MyServlet/path/foo/bar

Result since 6.1:

    getMappingMatch()   -> [PATH] 
    getMatchValue()     -> [foo/bar] 
    getPattern()        -> [/path/*] 
    getServletName()    -> [MyServlet]

Previouly: getMatchValue() -> [bar] - though the leading "/" was excluded, the matched value was parsed incorrectly.

Clarification: 5. Default TRACE request does not contain certain response headers.

A response to TRACE requests does not contain the following headers, if handled by the default jakarta.servlet.http.HttpSerlvet.doTrace():

Authorization, Cookie, X-Forwarded-For, Forwarded, Proxy-Authorization

Clarification: 6. Change to the HttpServletRequest.getMethod() during the error-page dispatcher.

HttpServletRequest method during the error-page dispatch is always set to GET.

Previously – it was as same as the initial request’s method.

Example:
Since Servlet 6.1:

    Initial request getMethod [POST]
        --sendError() --> error dispatcher(s) request getMethod [GET]
    returns-from-error --> request getMethod [POST]

Previously:

    Initial request getMethod [POST]
        --sendError() --> error dispatcher request getMethod [POST]
    returns-from-error --> request getMethod [POST]

Behavior Change - 1. Servlet Response addHeader() or setHeader() does not generate additional headers for Set-Cookie

When a response addHeader() or setHeader() is used to add Set-Cookie header with a random attribute, only one Set-Cookie header is generated.

Previously, a new Set-Cookie header was generated for the randome attribute

Example:

response.setHeader("Set-Cookie", "Cookie_viaSetHeader=CookieValue_viaSetHeader; Secure; SameSite=None; randomAttributeA=myAttValueA");

response.addHeader("Set-Cookie", "Cookie_viaAddHeader=CookieValue_viaAddHeader; Secure; SameSite=None; randomAttributeB=myAttValueB");

do not generate separate Set-Cookie headers for just an arbitrary attribute:

Set-Cookie: randomAttributeA=myAttValueA
Set-Cookie: randomAttributeB=myAttValueB

Behavior Change - 2. WebContainer custom property "allowAbsoluteFileNameForPartWrite" changes default to true

When a filename with an absolute path is used on the Part write(), the server will write the file to the specified location.

Previously - the filename was written to the server's temporary location.

Reference: PH62271

Document: Jakarta EE 11: Support Jakarta Servlet 6.1 #7959

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions