Jakarta Servlet Specification

By using and/or copying this document, or the Eclipse Foundation document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the Eclipse Foundation document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

Inclusion of the full text of this NOTICE must be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of Eclipse Foundation documents is granted pursuant to this license, except anyone may prepare and distribute derivative works and portions of this document in software that implements the specification, in supporting materials accompanying such software, and in documentation of such software, PROVIDED that all such works include the notice below. HOWEVER, the publication of derivative works of this document for use as a technical specification is expressly prohibited.

The notice is:

"Copyright © 2018, 2020 Eclipse Foundation. This software or document includes material copied from or derived from Jakarta ® Servlet https://jakarta.ee/specifications/servlet/5.0/"

This document is the Jakarta Servlet Specification, version 5.0. The standard for the Jakarta Servlet API is described herein.

The specification is intended to be a complete and clear explanation of the Jakarta Servlet API, but if questions remain, the following sources may be consulted:

Comments and feedback are welcome, and will be used to improve future versions.

The intended audience for this specification includes the following groups:

We emphasize that this specification is not a user’s guide for servlet developers and is not intended to be used as such.

The full specifications of classes, interfaces, and method signatures that define the Jakarta Servlet API, as well as their accompanying Javadoc™ documentation, is available online at https://jakarta.ee/specifications/servlet.

The following Jakarta API specifications are referenced throughout this specification:

These specifications may be found at the Jakarta EE Platform, web site: https://jakarta.ee/specifications/.

The following Internet specifications provide information relevant to the development and implementation of the Jakarta Servlet API and standard servlet engines:

Online versions of these RFCs are at http://www.ietf.org/rfc/.

The World Wide Web Consortium (http://www.w3.org/) is a definitive source of HTTP related information affecting this specification and its implementations.

The eXtensible Markup Language (XML) is used for the specification of the Deployment Descriptors described in Chapter 13 of this specification.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

We welcome any and all feedback about this specification. Please e-mail your comments to servlet-dev@eclipse.org.

A servlet is a Jakarta technology-based web component, managed by a container, that generates dynamic content. Like other Jakarta technology-based components, servlets are platform-independent Java classes that are compiled to platform-neutral byte code that can be loaded dynamically into and run by a Jakarta technology-enabled web server. Containers, sometimes called servlet engines, are web server extensions that provide servlet functionality. Servlets interact with web clients via a request/response paradigm implemented by the servlet container.

The servlet container is a part of a web server or application server that provides the network services over which requests and responses are sent, decodes MIME-based requests, and formats MIME-based responses. A servlet container also contains and manages servlets through their lifecycle.

A servlet container can be built into a host web server, or installed as an add-on component to a web server via that server’s native extension API. Servlet containers can also be built into or possibly installed into web-enabled application servers.

All servlet containers must support HTTP as a protocol for requests and responses, but additional request/response-based protocols such as HTTPS (HTTP over SSL) may be supported. The required versions of the HTTP specification that a container must implement are HTTP/1.1 and HTTP/2. When supporting HTTP/2, servlet containers must support the “h2” and “h2c” protocol identifiers (as specified in section 3.1 of the HTTP/2 RFC). This implies all servlet containers must support ALPN. Because the container may have a caching mechanism described in RFC 7234 (HTTP/1.1 Caching), it may modify requests from the clients before delivering them to the servlet, may modify responses produced by servlets before sending them to the clients, or may respond to requests without delivering them to the servlet under the compliance with RFC 7234.

A servlet container may place security restrictions on the environment in which a servlet executes. These restrictions may be placed using the permission architecture defined by the Java platform. For example some application servers may limit the creation of a Thread object to insure that other components of the container are not negatively impacted.

Java SE 8 is the minimum version of the underlying Java platform with which servlet containers must be built.

The following is a typical sequence of events:

In functionality, servlets provide a higher level abstraction than Common Gateway Interface (CGI) programs but a lower level of abstraction than that provided by web frameworks such as Jakarta Server Faces.

Servlets have the following advantages over other server extension mechanisms:

The Jakarta Servlet API v.5.0 is a required API of the Jakarta EE Platform, 9^[2]. Servlet containers and servlets deployed into them must meet additional requirements, described in the Jakarta EE specification, for executing in a Jakarta EE environment.

The basic Servlet interface defines a service method for handling client requests. This method is called for each request that the servlet container routes to an instance of a servlet.

The handling of concurrent requests to a web application generally requires that the web developer design servlets that can deal with multiple threads executing within the service method at a particular time.

Generally the web container handles concurrent requests to the same servlet by concurrent execution of the service method on different threads.

The servlet declaration which is either via the annotation as described in Chapter 8, Annotations and Pluggability or part of the deployment descriptor of the web application containing the servlet, as described in Chapter 14, Deployment Descriptor, controls how the servlet container provides instances of the servlet.

For a servlet not hosted in a distributed environment (the default), the servlet container must use only one instance per servlet declaration. However, for a servlet implementing the SingleThreadModel interface, the servlet container may instantiate multiple instances to handle a heavy request load and serialize requests to a particular instance.

In the case where a servlet was deployed as part of an application marked in the deployment descriptor as distributable, a container may have only one instance per servlet declaration per Java Virtual Machine (JVM™). However, if the servlet in a distributable application implements the SingleThreadModel interface, the container may instantiate multiple instances of that servlet in each JVM of the container.

A servlet is managed through a well defined life cycle that defines how it is loaded and instantiated, is initialized, handles requests from clients, and is taken out of service. This life cycle is expressed in the API by the init, service, and destroy methods of the jakarta.servlet.Servlet interface that all servlets must implement directly or indirectly through the GenericServlet or HttpServlet abstract classes.

Request parameters for the servlet are the strings sent by the client to a servlet container as part of its request. When the request is an HttpServletRequest object, and the conditions set out in Section 3.1.1, “When Parameters Are Available” are met, the container populates the parameters from the URI query string and POST-ed data.

The parameters are stored as a set of name-value pairs. Multiple parameter values can exist for any given parameter name. The following methods of the ServletRequest interface are available to access parameters:

The getParameterValues method returns an array of String objects containing all the parameter values associated with a parameter name. The value returned from the getParameter method must be the first value in the array of String objects returned by getParameterValues. The getParameterMap method returns a java.util.Map of the parameter of the request, which contains names as keys and parameter values as map values.

Data from the query string and the post body are aggregated into the request parameter set. Query string data is presented before post body data. For example, if a request is made with a query string of a=hello and a post body of a=goodbye&a=world, the resulting parameter set would be ordered a=(hello, goodbye, world).

Path parameters that are part of a GET request (as defined by HTTP/1.1) are not exposed by these APIs. They must be parsed from the String values returned by the getRequestURI method or the getPathInfo method.

Servlet container allows files to be uploaded when data is sent as multipart/form-data.

The servlet container provides multipart/form-data processing if any one of the following conditions is met.

How data in a request of type multipart/form-data is made available depends on whether the servlet container provides multipart/form-data processing:

Attributes are objects associated with a request. Attributes may be set by the container to express information that otherwise could not be expressed via the API, or may be set by a servlet to communicate information to another servlet (via the RequestDispatcher). Attributes are accessed with the following methods of the ServletRequest interface:

Only one attribute value may be associated with an attribute name.

Attribute names beginning with the prefix of jakarta. are reserved for definition by this specification. It is suggested that all attributes placed in the attribute set be named in accordance with the reverse domain name convention suggested by the Java Programming Language Specification ^[3] for package naming.

A servlet can access the headers of an HTTP request through the following methods of the HttpServletRequest interface:

The getHeader method returns a header value given the name of the header. There can be multiple headers with the same name, e.g. Cache-Control headers, in an HTTP request. If there are multiple headers with the same name, the getHeader method returns the value of first header in the request. The getHeaders method allows access to all the header values associated with a particular header name, returning an Enumeration of String objects.

Headers may contain String representations of int or Date data. The following convenience methods of the HttpServletRequest interface provide access to header data in a one of these formats:

If the getIntHeader method cannot translate the header value to an int, a NumberFormatException is thrown. If the getDateHeader method cannot translate the header to a Date object, an IllegalArgumentException is thrown.

The request path that leads to a servlet servicing a request is composed of many important sections. The following elements are obtained from the request URI path and exposed via the request object:

The following methods exist in the HttpServletRequest interface to access this information:

It is important to note that, except for URL encoding differences between the request URI and the path parts, the following equation is always true:

To give a few examples to clarify the above points, consider the following:

The following behavior is observed:

There are two convenience methods in the API which allow the Application Developer to obtain the file system path equivalent to a particular path. These methods are:

The getRealPath method takes a String argument and returns a String representation of a file on the local file system to which a path corresponds. The getPathTranslated method computes the real path of the pathInfo of the request.

In situations where the servlet container cannot determine a valid file path for these methods, such as when the web application is executed from an archive, on a remote file system not accessible locally, or in a database, these methods must return null. Resources inside the META-INF/resources directory of JAR file must be considered only if the container has unpacked them from their containing JAR file when a call to getRealPath() is made, and in this case MUST return the unpacked location.

Non-blocking request processing in the web container helps improve the ever increasing demand for improved web container scalability, increase the number of connections that can simultaneously be handled by the web container. Non-blocking IO in the servlet container allows developers to read data as it becomes available or write data when possible to do so. Non-blocking IO only works with async request processing in servlets and filters (as defined in Section 2.3.3.3, “Asynchronous processing”), and upgrade processing (as defined in Section 2.3.3.5, “Upgrade Processing”). Otherwise, an IllegalStateException must be thrown when ServletInputStream.setReadListener or ServletOutputStream.setWriteListener is invoked.

The ReadListener provides the following callback methods for non-blocking IO:

The servlet container must access methods in ReadListener in a thread safe manner.

In addition to the ReadListener defined above, the following methods have been added to ServletInputStream class:

Server push is the most visible of the improvements in HTTP/2 to appear in the servlet API. All of the new features in HTTP/2, including server push, are aimed at improving the perceived performance of the web browsing experience. Server push derives its contribution to improved perceived browser performance from the simple fact that servers are in a much better position than clients to know what additional assets (such as images, stylesheets and scripts) go along with initial requests. For example, it is possible for servers to know that whenever a browser requests index.html, it will shortly thereafter request header.gif, footer.gif and style.css. Since servers know this, they can preemptively start sending the bytes of these assets along side the bytes of the index.html.

To use server push, obtain a reference to a PushBuilder from an HttpServletRequest, mutate the builder as desired, then call push(). Please see the javadoc for method jakarta.servlet.http.HttpServletRequest.newPushBuilder() and class jakarta.servlet.http.PushBuilder for the normative specification. The remainder of this section calls out implementation requirements with respect to the section titled “Server Push” in the HTTP/2 specification version referenced in Other Important References.

Unless explicitly excluded, Servlet 5.0 containers must support server push as specified in the HTTP/2 specification section “Server Push”. Containers must enable server push if the client is capable of speaking HTTP/2, unless the client has explicitly disabled server push by sending a SETTINGS_ENABLE_PUSH setting value of 0 (zero) for the current connection. In that case, for that connection only, server push must not be enabled.

In addition to allowing clients to disable server push with the SETTINGS_ENABLE_PUSH setting, servlet containers must honor a client’s request to not receive a pushed response on a finer grained basis by heeding the CANCEL or REFUSED_STREAM code that references the pushed stream’s stream identifier. One common use of this interaction is when a browser already has the resource in its cache.

The HttpServletRequest interface provides the getCookies method to obtain an array of cookies that are present in the request. These cookies are data sent from the client to the server on every request that the client makes. Typically, the only information that the client sends back as part of a cookie is the cookie name and the cookie value. Other cookie attributes that can be set when the cookie is sent to the browser, such as comments, are not typically returned. The specification also allows for the cookies to be HttpOnly cookies. HttpOnly cookies indicate to the client that they should not be exposed to client-side scripting code (it’s not filtered out unless the client knows to look for this attribute). The use of HttpOnly cookies helps mitigate certain kinds of cross-site scripting attacks.

If a request has been transmitted over a secure protocol, such as HTTPS, this information must be exposed via the isSecure method of the ServletRequest interface. The web container must expose the following attributes to the servlet programmer:

If there is an SSL certificate associated with the request, it must be exposed by the servlet container to the servlet programmer as an array of objects of type java.security.cert.X509Certificate and accessible via a ServletRequest attribute of jakarta.servlet.request.X509Certificate.

The order of this array is defined as being in ascending order of trust. The first certificate in the chain is the one set by the client, the next is the one used to authenticate the first, and so on.

Clients may optionally indicate to a web server what language they would prefer the response be given in. This information can be communicated from the client using the Accept-Language header along with other mechanisms described in the HTTP/1.1 specification. The following methods are provided in the ServletRequest interface to determine the preferred locale of the sender:

The getLocale method will return the preferred locale for which the client wants to accept content. See section 14.4 of RFC 7231 (HTTP/1.1) for more information about how the Accept-Language header must be interpreted to determine the preferred language of the client.

The getLocales method will return an Enumeration of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client.

If no preferred locale is specified by the client, the locale returned by the getLocale method must be the default locale for the servlet container and the getLocales method must contain an enumeration of a single Locale element of the default locale.

Currently, many browsers do not send a char encoding qualifier with the Content-Type header, leaving open the determination of the character encoding for reading HTTP requests. In the absence of a char encoding qualifier, if the Content-Type is application/x-www-form-urlencoded, the default encoding the container uses to create the request reader and parse POST data must be US-ASCII. Any %nn encoded values must be decoded to ISO-8859-1. For any other Content-Type, if none has been specified by the client request, web application or container vendor specific configuration (for all web applications in the container), the default encoding of a request the container uses to create the request reader and parse POST data must be ISO-8859-1. However, in order to indicate to the developer the absence of a char encoding qualifier, the container must return null from the getCharacterEncoding() method.

If the client hasn’t set character encoding and the request data is encoded with a different encoding than the default as described above, breakage can occur. To remedy this situation, setRequestCharacterEncoding(String enc) is available on ServletContext, the <request-character-encoding> element is available in the web.xml and setCharacterEncoding(String enc) is available on the ServletRequest interface. Developers can override the character encoding supplied by the container by calling this method. It must be called prior to parsing any post data or reading any input from the request. Calling this method once data has been read will not affect the encoding.

Each request object is valid only within the scope of a servlet’s service method, or within the scope of a filter’s doFilter method, unless the asynchronous processing is enabled for the component and the startAsync method is invoked on the request object. In the case where asynchronous processing occurs, the request object remains valid until complete is invoked on the AsyncContext. Containers commonly recycle request objects in order to avoid the performance overhead of request object creation. The developer must be aware that maintaining references to request objects for which startAsync has not been called outside the scope described above is not recommended as it may have indeterminate results.

In case of upgrade, the above is still true.

The ServletContext interface defines a servlet’s view of the web application within which the servlet is running. The Container Provider is responsible for providing an implementation of the ServletContext interface in the servlet container. Using the ServletContext object, a servlet can log events, obtain URL references to resources, and set and store attributes that other servlets in the context can access.

A ServletContext is rooted at a known path within a web server. For example, a servlet context could be located at http://example.com/catalog. All requests that begin with the /catalog request path, known as the context path, are routed to the web application associated with the ServletContext.

There is one instance object of the ServletContext interface associated with each web application deployed into a container. In cases where the container is distributed over many virtual machines, a web application will have an instance of the ServletContext for each JVM.

The following methods of the ServletContext interface allow the servlet access to context initialization parameters associated with a web application as specified by the Application Developer in the deployment descriptor:

Initialization parameters are used by an Application Developer to convey setup information. Typical examples are a webmaster’s e-mail address, or the name of a system that holds critical data.

The following methods are provided on the ServletContext interface to enable programmatic definition of servlets, filters and the url pattern(s) that they map to. These methods can only be called during the initialization of the application either from the contexInitialized method of a ServletContextListener implementation or from the onStartup method of a ServletContainerInitializer implementation. In addition to adding servlets and filters, one can also look up an instance of a Registration object corresponding to a servlet or filter or a map of all the Registration objects for the servlets or filters. If a ServletContext is passed to the ServletContextListener’s contextInitialized method where the ServletContextListener was neither declared in web.xml or web-fragment.xml nor annotated with @WebListener then an UnsupportedOperationException MUST be thrown for all the methods defined in ServletContext for programmatic configuration of servlets, filters and listeners.

A servlet can bind an object attribute into the context by name. Any attribute bound into a context is available to any other servlet that is part of the same web application. The following methods of ServletContext interface allow access to this functionality:

The ServletContext interface provides direct access only to the hierarchy of static content documents that are part of the web application, including HTML, GIF, and JPEG files, via the following methods of the ServletContext interface:

The getResource and getResourceAsStream methods take a String with a leading "/" as an argument that gives the path of the resource relative to the root of the context or relative to the META-INF/resources directory of a JAR file inside the web application’s WEB-INF/lib directory. If there is a WEB-INF entry inside the META-INF/resources entry of a JAR file in WEB-INF/lib, then it and all child entries are available only as static resources. No classes or jars will be placed on the context classpath from such a WEB-INF entry, and no servlet specific descriptors will be processed. These methods will first search the root of the web application context for the requested resource before looking at any of the JAR files in the WEB-INF/lib directory. The order in which the JAR files in the WEB-INF/lib directory are scanned is undefined. This hierarchy of documents may exist in the server’s file system, in a web application archive file, on a remote server, or at some other location.

These methods are not used to obtain dynamic content. For example, in a container supporting the Jakarta Server Pages specification ^[4], a method call of the form getResource("/index.jsp") would return the JSP source code and not the processed output. See Chapter 9, Dispatching Requests for more information about accessing dynamic content.

The full listing of the resources in the web application can be accessed using the getResourcePaths(String path) method. The full details on the semantics of this method may be found in the API documentation in this specification.

Web servers may support multiple logical hosts sharing one IP address on a server. This capability is sometimes referred to as "virtual hosting". In this case, each logical host must have its own servlet context or set of servlet contexts. Servlet contexts can not be shared across virtual hosts.

The getVirtualServerName method of ServletContext interface allows access to the configuration name of the logical host on which the ServletContext is deployed. Servlet containers may support multiple logical hosts. This method must return the same name for all the servlet contexts deployed on a logical host, and the name returned by this method must be distinct, stable per logical host, and suitable for use in associating server configuration information with the logical host.

Although a Container Provider implementation of a class reloading scheme for ease of development is not required, any such implementation must ensure that all servlets, and classes that they may use ^[5], are loaded in the scope of a single class loader. This requirement is needed to guarantee that the application will behave as expected by the Application Developer. As a development aid, the full semantics of notification to session binding listeners should be supported by containers for use in the monitoring of session termination upon class reloading.

Previous generations of containers created new class loaders to load a servlet, distinct from class loaders used to load other servlets or classes used in the servlet context. This could cause object references within a servlet context to point at unexpected classes or objects, and cause unexpected behavior. The requirement is needed to prevent problems caused by demand generation of new class loaders.

A servlet container is allowed, but not required, to buffer output going to the client for efficiency purposes. Typically servers that do buffering make it the default, but allow servlets to specify buffering parameters.

The following methods in the ServletResponse interface allow a servlet to access and set buffering information:

These methods are provided on the ServletResponse interface to allow buffering operations to be performed whether the servlet is using a ServletOutputStream or a Writer.

The getBufferSize method returns the size of the underlying buffer being used. If no buffering is being used, this method must return the int value of 0 (zero).

The servlet can request a preferred buffer size by using the setBufferSize method. The buffer assigned is not required to be the size requested by the servlet, but must be at least as large as the size requested. This allows the container to reuse a set of fixed size buffers, providing a larger buffer than requested if appropriate. The method must be called before any content is written using a ServletOutputStream or Writer. If any content has been written or the response object has been committed, this method must throw an IllegalStateException.

The isCommitted method returns a boolean value indicating whether any response bytes have been returned to the client. The flushBuffer method forces content in the buffer to be written to the client.

The reset method clears data in the buffer when the response is not committed. Headers, status codes and the state of calling getWriter or getOutputStream set by the servlet prior to the reset call must be cleared as well. The resetBuffer method clears content in the buffer if the response is not committed without clearing the headers and status code.

If the response is committed and the reset or resetBuffer method is called, an IllegalStateException must be thrown. The response and its associated buffer will be unchanged.

When using a buffer, the container must immediately flush the contents of a filled buffer to the client. If this is the first data that is sent to the client, the response is considered to be committed.

A servlet can set headers of an HTTP response via the following methods of the HttpServletResponse interface:

The setHeader method sets a header with a given name and value. A previous header is replaced by the new header. Where a set of header values exist for the name, the values are cleared and replaced with the new value.

The addHeader method adds a header value to the set with a given name. If there are no headers already associated with the name, a new set is created.

Headers may contain data that represents an int or a Date object. The following convenience methods of the HttpServletResponse interface allow a servlet to set a header using the correct formatting for the appropriate data type:

To be successfully transmitted back to the client, headers (other than those in a trailer) must be set before the response is committed. Headers (other than those in a trailer) set after the response is committed will be ignored by the servlet container. If an HTTP trailer, as specified in RFC 7230, is to be sent in the response, the fields must be provided using the setTrailerFields() method on HttpServletResponse. This method must have been called before the last chunk in the chunked response has been written.

Servlet programmers are responsible for ensuring that the Content-Type header is appropriately set in the response object for the content the servlet is generating. The HTTP/1.1 specification does not require that this header be set in an HTTP response. Servlet containers must not set a default content type when the servlet programmer does not set the type.

It is recommended that containers use the X-Powered-By HTTP header to publish its implementation information. The field value should consist of one or more implementation types, such as Servlet/5.0. Optionally, the supplementary information of the container and the underlying Java platform can be added after the implementation type within parentheses. The container should be configurable to suppress this header.

Here’s the examples of this header.

An HTTP trailer is a collection of HTTP headers that comes after the response body. It is specified in RFC 7230. It is useful in the context of chunked transfer encoding and also in the implementation of additional communication protocols. Servlet containers provide support for trailers.

If trailer headers are ready for reading, isTrailerFieldsReady() will return true. Then a servlet can read trailer headers of the HTTP request via the getTrailerFields() method of the HttpServletRequest interface.

A servlet can write trailer headers to the response by providing a Supplier to the setTrailerFields method of the HttpServletResponse interface. The Supplier of the trailer headers can be obtained by accessing the getTrailerFields() method of the HttpServletResponse interface.

Please see the javadoc for these two methods for the normative specification.

Non-blocking IO only works with async request processing in servlets and filters (as defined in Section 2.3.3.3, “Asynchronous processing”), and upgrade processing (as defined in Section 2.3.3.5, “Upgrade Processing”). Otherwise, an IllegalStateException must be thrown when ServletInputStream.setReadListener or ServletOutputStream.setWriteListener is invoked. To support non-blocking writes in the web container, in addition to the changes made in the ServletRequest as described in Section 3.7, “Non-Blocking IO”, the following changes have been made to handle response related classes / interfaces.

The WriteListener provides the following callback methods which the container invokes appropriately.

Along with the WriteListener, the following methods have been added to ServletOutputStream class to allow the developer to check with the runtime whether or not it is possible to write the data to be sent to the client.

The servlet container must access methods in WriteListener in a thread safe manner.

The following convenience methods exist in the HttpServletResponse interface:

The sendRedirect method will set the appropriate headers and content body to redirect the client to a different URL. It is legal to call this method with a relative URL path, however the underlying container must translate the relative path to a fully qualified URL for transmission back to the client. If a partial URL is given and, for whatever reason, cannot be converted into a valid URL, then this method must throw an IllegalArgumentException.

The sendError method will set the appropriate headers and content body for an error message to return to the client. An optional String argument can be provided to the sendError method which can be used in the content body of the error.

These methods will have the side effect of committing the response, if it has not already been committed, and terminating it. No further output to the client should be made by the servlet after these methods are called. If data is written to the response after these methods are called, the data is ignored.

If data has been written to the response buffer, but not returned to the client (i.e. the response is not committed), the data in the response buffer must be cleared and replaced with the data set by these methods. If the response is committed, these methods must throw an IllegalStateException.

Servlets should set the locale and the character encoding of a response. The locale is set using the ServletResponse.setLocale method. The method can be called repeatedly; but calls made after the response is committed have no effect. If the servlet does not set the locale before the page is committed, the container’s default locale is used to determine the response’s locale, but no specification is made for the communication with a client, such as Content-Language header in the case of HTTP.

The <response-character-encoding> element can be used to explicitly set the default encoding for all responses in a given web application.

If neither element exists or does not provide a mapping, setLocale uses a container dependent mapping. The setCharacterEncoding, setContentType, and setLocale methods can be called repeatedly to change the character encoding. Calls made after the servlet response’s getWriter method has been called or after the response is committed have no effect on the character encoding. Calls to setContentType set the character encoding only if the given content type string provides a value for the charset attribute. Calls to setLocale set the character encoding only if neither setCharacterEncoding nor setContentType has set the character encoding before.

If the servlet does not specify a character encoding before the getWriter method of the ServletResponse interface is called or the response is committed, the default ISO-8859-1 is used.

Containers must communicate the locale and the character encoding used for the servlet response’s writer to the client if the protocol in use provides a way for doing so. In the case of HTTP, the locale is communicated via the Content-Language header, the character encoding as part of the Content-Type header for text media types. Note that the character encoding cannot be communicated via HTTP headers if the servlet does not specify a content type; however, it is still used to encode text written via the servlet response’s writer.

When a response is closed, the container must immediately flush all remaining content in the response buffer to the client. The following events indicate that the servlet has satisfied the request and that the response object is to be closed:

Each response object is valid only within the scope of a servlet’s service method, or within the scope of a filter’s doFilter method, unless the associated request object has asynchronous processing enabled for the component. If asynchronous processing on the associated request is started, then the response object remains valid until complete method on AsyncContext is called. Containers commonly recycle response objects in order to avoid the performance overhead of response object creation. The developer must be aware that maintaining references to response objects for which startAsync on the corresponding request has not been called, outside the scope described above may lead to non-deterministic behavior.

A filter is a reusable piece of code that can transform the content of HTTP requests, responses, and header information. Filters do not generally create a response or respond to a request as servlets do, rather they modify or adapt the requests for a resource, and modify or adapt responses from a resource.

Filters can act on dynamic or static content. For the purposes of this chapter, dynamic and static content are referred to as web resources.

Among the types of functionality available to the developer needing to use filters are the following:

The main concepts of this filtering model are described in this section.

The application developer creates a filter by implementing the jakarta.servlet.Filter interface and providing a public constructor taking no arguments. The class is packaged in the web archive along with the static content and servlets that make up the web application. A filter is declared using the <filter> element in the deployment descriptor. A filter or collection of filters can be configured for invocation by defining <filter-mapping> elements in the deployment descriptor. This is done by mapping filters to a particular servlet by the servlet’s logical name, or mapping to a group of servlets and static content resources by mapping a filter to a URL pattern.

The following sections describe approaches to tracking a user’s sessions

A session is considered “new” when it is only a prospective session and has not been established. Because HTTP is a request-response based protocol, an HTTP session is considered to be new until a client “joins” it. A client joins a session when session tracking information has been returned to the server indicating that a session has been established. Until the client joins a session, it cannot be assumed that the next request from the client will be recognized as part of a session.

The session is considered to be “new” if either of the following is true:

These conditions define the situation where the servlet container has no mechanism by which to associate a request with a previous request.

An Application Developer must design the application to handle a situation where a client has not, can not, or will not join a session.

Associated with each session, there is a string containing a unique identifier, which is referred to as the session id. The value of the session id can be obtained by calling jakarta.servlet.http.HttpSession.getId() and can be changed after creation by invoking jakarta.servlet.http.HttpServletRequest.changeSessionId().

HttpSession objects must be scoped at the application (or servlet context) level. The underlying mechanism, such as the cookie used to establish the session, can be the same for different contexts, but the object referenced, including the attributes in that object, must never be shared between contexts by the container.

To illustrate this requirement with an example: if a servlet uses the RequestDispatcher to call a servlet in another web application, any sessions created for and visible to the servlet being called must be different from those visible to the calling servlet.

Additionally, sessions of a context must be resumable by requests into that context regardless of whether their associated context was being accessed directly or as the target of a request dispatch at the time the sessions were created.

A servlet can bind an object attribute into an HttpSession implementation by name. Any object bound into a session is available to any other servlet that belongs to the same ServletContext and handles a request identified as being a part of the same session.

Some objects may require notification when they are placed into, or removed from, a session. This information can be obtained by having the object implement the HttpSessionBindingListener interface. This interface defines the following methods that will signal an object being bound into, or being unbound from, a session.

The valueBound method must be called before the object is made available via the getAttribute method of the HttpSession interface. The valueUnbound method must be called after the object is no longer available via the getAttribute method of the HttpSession interface.

In the HTTP protocol, there is no explicit termination signal when a client is no longer active. This means that the only mechanism that can be used to indicate when a client is no longer active is a time out period.

The default time out period for sessions is defined by the servlet container and can be obtained via the getSessionTimeout method of the ServletContext interface or the getMaxInactiveInterval method of the HttpSession interface. This time out can be changed by the Application Developer using the setSessionTimeout method of the ServletContext interface or the setMaxInactiveInterval method of the HttpSession interface. The time out periods used by session timeout methods are defined in minutes. The time out periods used by max active interval methods are defined in seconds. See the javadoc for setSessionTimeout for additional normative requirements. By definition, if the time out period for a session is set to 0 or lesser value , the session will never expire. The session invalidation will not take effect until all servlets using that session have exited the service method. Once the session invalidation is initiated, a new request must not be able to see that session.

The getLastAccessedTime method of the HttpSession interface allows a servlet to determine the last time the session was accessed before the current request. The session is considered to be accessed when a request that is part of the session is first handled by the servlet container.

In a web application, classes using annotations will have their annotations processed only if they are located in the WEB-INF/classes directory, or if they are packaged in a jar file located in WEB-INF/lib within the application.

The web application deployment descriptor contains a metadata-complete attribute on the web-app element. This attribute defines whether this deployment descriptor and associated web fragments, if any, are complete, or whether the class files available to this module and packaged with this application should be examined for annotations that specify deployment information. Deployment information, in this sense, refers to any information that could have been specified by the deployment descriptor or fragments, but instead is specified as annotations on classes.

If the value of the metadata-complete attribute is specified as true, the deployment tool must ignore any annotations that specify such deployment information in the class files packaged in the web application. Please see Section 8.2.3, “Assembling the Descriptor from web.xml, web-fragment.xml and Annotations”, Section 8.4, “Processing Annotations and Fragments” and Section 15.5.1, “Handling of metadata-complete” for additional details on the handling of metadata-complete.

If the metadata-complete attribute is not specified, or its value is false, the deployment tool must examine the class files of the application for such annotations. Note that a true value for metadata-complete does not preempt the processing of all annotations, only those listed below.

Annotations that do not have equivalents in the deployment XSD include jakarta.servlet.annotation.HandlesTypes and all of the CDI-related annotations. These annotations must be processed during annotation scanning, regardless of the value of metadata-complete.

When Jakarta Enterprise Beans are packaged in a .war file, and the .war file contains an ejb-jar.xml file, the metadata-complete attribute of the ejb-jar.xml file determines the processing of the annotations for enterprise beans. If there is no ejb-jar.xml file, and the web.xml specifies the metadata-complete attribute as true, these annotations are processed as though there were an ejb-jar.xml file whose metadata-complete attribute was specified as true. See the Jakarta Enterprise Beans specification for requirements pertaining to annotations for Jakarta Enterprise Beans.

The following are the annotations in jakarta.servlet. All of these have corresponding deployment descriptor metadata covered by the web xsd.

From jakarta.servlet.annotation:

The following annotations from related packages are also covered by the web.xml and associated fragments.

From jakarta.annotation:

From jakarta.annotation.security:

From jakarta.annotation.sql:

From jakarta.ejb:

From jakarta.jms:

From jakarta.mail:

From jakarta.persistence:

From jakarta.resource:

All annotations in the following packages:

Following are the annotations that MUST be supported by a servlet compliant web container.

The ServletContainerInitializer and programmatic registration features make it possible to provide a clear separation of responsibilities between the servlet and JSP containers, by making the servlet container responsible for parsing only web.xml and web-fragment.xml resources, and delegating the parsing of Tag Library Descriptor (TLD) resources to the JSP container.

Previously, a web container had to scan TLD resources for any listener declarations. With Servlet 3.0 and later versions, this responsibility may be delegated to the JSP container. A JSP container that is embedded in a servlet container may provide its own ServletContainerInitializer implementation, search the ServletContext passed to its onStartup method for any TLD resources, scan those resources for listener declarations, and register the corresponding listeners with the ServletContext.

In addition, prior to Servlet 3.0, a JSP container used to have to scan an application’s deployment descriptor for any jsp-config related configuration. With Servlet 3.0 and later versions, the servlet container must make available, via the ServletContext.getJspConfigDescriptor method, any jsp-config related configuration from the application’s web.xml and web-fragment.xml deployment descriptors.

Any ServletContextListeners that were discovered in a TLD and registered programmatically are limited in the functionality they provide. Any attempt to call a ServletContext API methods on them that was added since Servlet 3.0 will result in an UnsupportedOperationException.

In addition, a servlet container compliant with Servlet 3.0 or later versions must provide a ServletContext attribute with name jakarta.servlet.context.orderedLibs, whose value (of type java.util.List<java.lang.String>) contains the list of names of JAR files in the WEB-INF/lib directory of the application represented by the ServletContext, ordered by their web fragment names (with possible exclusions if fragment JAR files have been excluded from absolute-ordering), or null if the application does not specify any absolute or relative ordering.

Web applications can include both annotations and the web.xml / web-fragment.xml deployment descriptors. The version of the descriptor MUST not affect which annotations the container scans for in a web application. An implementation of a particular version of the specification MUST scan for all annotations supported in that configuration, unless metadata-complete is specified. If there is no deployment descriptor, or there is one but does not have the metadata-complete set to true, web.xml, web-fragment.xml and annotations, if used, in the application must be processed. The following table describes whether or not to process annotations and web.xml fragments.

An object implementing the RequestDispatcher interface may be obtained from the ServletContext via the following methods:

The getRequestDispatcher method takes a String argument describing a path within the scope of the ServletContext. This path must be relative to the root of the ServletContext and begin with a "/", or be empty. The method uses the path to look up a servlet, using the servlet path matching rules in Chapter 12, Mapping Requests to Servlets, wraps it with a RequestDispatcher object, and returns the resulting object. If no servlet can be resolved based on the given path, a RequestDispatcher is provided that returns the content for that path.

The getNamedDispatcher method takes a String argument indicating the name of a servlet known to the ServletContext. If a servlet is found, it is wrapped with a RequestDispatcher object and the object is returned. If no servlet is associated with the given name, the method must return null.

To allow RequestDispatcher objects to be obtained using relative paths that are relative to the path of the current request (not relative to the root of the ServletContext), the getRequestDispatcher method is provided in the ServletRequest interface.

The behavior of this method is similar to the method of the same name in the ServletContext. The servlet container uses information in the request object to transform the given relative path against the current servlet to a complete path. For example, in a context rooted at "/" and a request to /garden/tools.html, a request dispatcher obtained via ServletRequest.getRequestDispatcher("header.html") will behave exactly like a call to ServletContext.getRequestDispatcher("/garden/header.html").

To use a request dispatcher, a servlet calls either the include method or forward method of the RequestDispatcher interface. The parameters to these methods can be either the request and response arguments that were passed in via the service method of the jakarta.servlet.Servlet interface, or instances of subclasses of the request and response wrapper classes that were introduced for version 2.3 of the specification. In the latter case, the wrapper instances must wrap the request or response objects that the container passed into the service method.

The Container Provider should ensure that the dispatch of the request to a target servlet occurs in the same thread of the same JVM as the original request.

The include method of the RequestDispatcher interface may be called at any time. The target servlet of the include method has access to all aspects of the request object, but its use of the response object is more limited.

It can only write information to the ServletOutputStream or Writer of the response object and commit a response by writing content past the end of the response buffer, or by explicitly calling the flushBuffer method of the ServletResponse interface. It cannot set headers or call any method that affects the headers of the response, with the exception of the HttpServletRequest.getSession() and HttpServletRequest.getSession(boolean) methods. Any attempt to set the headers must be ignored, and any call to HttpServletRequest.getSession() or HttpServletRequest.getSession(boolean) that would require adding a Cookie response header must throw an IllegalStateException if the response has been committed.

If the default servlet is the target of a RequestDispatch.include() and the requested resource does not exist, then the default servlet MUST throw FileNotFoundException. If the exception isn’t caught and handled, and the response hasn’t been committed, the status code MUST be set to 500.

The forward method of the RequestDispatcher interface may be called by the calling servlet only when no output has been committed to the client. If output data exists in the response buffer that has not been committed, the content must be cleared before the target servlet’s service method is called. If the response has been committed, an IllegalStateException must be thrown.

The path elements of the request object exposed to the target servlet must reflect the path used to obtain the RequestDispatcher.

The only exception to this is if the RequestDispatcher was obtained via the getNamedDispatcher method. In this case, the path elements of the request object must reflect those of the original request.

Before the forward method of the RequestDispatcher interface returns without exception, the response content must be sent and committed, and closed by the servlet container, unless the request was put into the asynchronous mode. If an error occurs in the target of the RequestDispatcher.forward() the exception may be propagated back through all the calling filters and servlets and eventually back to the container

If the servlet that is the target of a request dispatcher throws a runtime exception or a checked exception of type ServletException or IOException, it should be propagated to the calling servlet. All other exceptions should be wrapped as ServletExceptions and the root cause of the exception set to the original exception, as it should not be propagated.

An object implementing the AsyncContext interface may be obtained from the ServletRequest via one of startAsync methods. Once you have an AsyncContext, you can use it to either complete the processing of the request via the complete() method or use one of the dispatch methods described below.

The following methods can be used to dispatch requests from the AsyncContext:

One of the dispatch methods of the AsyncContext interface may be called by the application waiting for the asynchronous event to happen. If complete() has been called on the AsyncContext, an IllegalStateException must be thrown. All the variations of the dispatch methods returns immediately and do not commit the response.

The path elements of the request object exposed to the target servlet must reflect the path specified in the AsyncContext.dispatch.

A web application is rooted at a specific path within a web server. For example, a catalog application could be located at http://www.example.com/catalog. All requests that start with this prefix will be routed to the ServletContext which represents the catalog application.

A servlet container can establish rules for automatic generation of web applications. For example a /~user/ mapping could be used to map to a web application based at /home/user/public_html/.

By default, an instance of a web application must run on one JVM at any one time. This behavior can be overridden if the application is marked as “distributable” via its deployment descriptor. An application marked as distributable must obey a more restrictive set of rules than is required of a normal web application. These rules are set out throughout this specification.

The servlet container must enforce a one to one correspondence between a web application and a ServletContext. A ServletContext object provides a servlet with its view of the application.

A web application may consist of the following items:

This specification defines a hierarchical structure used for deployment and packaging purposes that can exist in an open file system, in an archive file, or in some other form. It is recommended, but not required, that servlet containers support this structure as a runtime representation.

A web application exists as a structured hierarchy of directories. The root of this hierarchy serves as the document root for files that are part of the application. For example, for a web application with the context path /catalog in a web container, the index.html file at the base of the web application hierarchy or in a JAR file inside WEB-INF/lib that includes the index.html under META-INF/resources directory can be served to satisfy a request from /catalog/index.html. If an index.html is present both in the root context and in the META-INF/resources directory of a JAR file in the WEB-INF/lib directory of the application, then the file that is available in the root context MUST be used. The rules for matching URLs to context path are laid out in Chapter 12, Mapping Requests to Servlets. Since the context path of an application determines the URL namespace of the contents of the web application, web containers must reject web applications defining a context path that could cause potential conflicts in this URL namespace. This may occur, for example, by attempting to deploy a second web application with the same context path. Since requests are matched to resources in a case-sensitive manner, this determination of potential conflict must be performed in a case-sensitive manner as well.

A special directory exists within the application hierarchy named WEB-INF. This directory contains all things related to the application that aren’t in the document root of the application. Most of the WEB-INF node is not part of the public document tree of the application. Except for static resources and JSPs packaged in the META-INF/resources of a JAR file that resides in the WEB-INF/lib directory, no other files contained in the WEB-INF directory may be served directly to a client by the container. However, the contents of the WEB-INF directory are visible to servlet code using the getResource and getResourceAsStream method calls on the ServletContext, and may be exposed using the RequestDispatcher calls. Hence, if the Application Developer needs access, from servlet code, to application specific configuration information that should not be exposed directly to the web client, it may be placed under this directory. Since requests are matched to resource mappings in a case-sensitive manner, client requests for /WEB-INF/foo, /WEb-iNf/foo, for example, should not result in contents of the web application located under /WEB-INF being returned, nor any form of directory listing thereof.

The contents of the WEB-INF directory are:

The web application class loader must load classes from the WEB-INF/classes directory first, and then from library JARs in the WEB-INF/lib directory. Also, except for the case where static resources are packaged in JAR files, any requests from the client to access the resources in WEB-INF/ directory must be returned with a SC_NOT_FOUND (404) response.

Web applications can be packaged and signed into a Web ARchive format (WAR) file using the standard Java archive tools. For example, an application for issue tracking might be distributed in an archive file called issuetrack.war.

When packaged into such a form, a META-INF directory will be present which contains information useful to Java archive tools. This directory must not be directly served as content by the container in response to a web client’s request, though its contents are visible to servlet code via the getResource and getResourceAsStream calls on the ServletContext. Also, any requests to access the resources in META-INF directory must be returned with a SC_NOT_FOUND (404) response.

The web application deployment descriptor (see Chapter 14, Deployment Descriptor) includes the following types of configuration and deployment information:

A server should be able to replace an application with a new version without restarting the container. When an application is replaced, the container should provide a robust method for preserving session data within that application.

Application Developers can define an ordered list of partial URIs called welcome files in the web application deployment descriptor. The deployment descriptor syntax for the list is described in the web application deployment descriptor schema.

The purpose of this mechanism is to allow the deployer to specify an ordered list of partial URIs for the container to use for appending to URIs when there is a request for a URI that corresponds to a directory entry in the WAR not mapped to a web component. This kind of request is known as a valid partial request.

The use for this facility is made clear by the following common example: A welcome file of index.html can be defined so that a request to a URL like host:port/webapp/directory/, where directory is an entry in the WAR that is not mapped to a servlet or JSP page, is returned to the client as host:port/webapp/directory/index.html.

If a web container receives a valid partial request, the web container must examine the welcome file list defined in the deployment descriptor. The welcome file list is an ordered list of partial URLs with no trailing or leading "/". The web server must append each welcome file in the order specified in the deployment descriptor to the partial request and check whether a static resource in the WAR is mapped to that request URI. If no match is found, the web server MUST again append each welcome file in the order specified in the deployment descriptor to the partial request and check if a servlet is mapped to that request URI. The web container must send the request to the first resource in the WAR that matches. The container may send the request to the welcome resource with a forward, a redirect, or a container specific mechanism that is indistinguishable from a direct request.

If no matching welcome file is found in the manner described, the container may handle the request in a manner it finds suitable. For some configurations this may mean returning a directory listing or for others returning a 404 response.

Consider a web application where:

Servlet containers that are not part of a Jakarta EE technology-compliant implementation are encouraged, but not required, to implement the application environment functionality described in Section 15.2.2, “Web Application Environment” and the Jakarta EE specification. If they do not implement the facilities required to support this environment, upon deploying an application that relies on them, the container should provide a warning.

When a web application is deployed into a container, the following steps must be performed, in this order, before the web application begins processing client requests.

A web application is NOT required to contain a web.xml if it does NOT contain any servlet, filter, or listener components or is using annotations to declare the same. In other words an application containing only static files or JSP pages does not require a web.xml to be present.

The application events facility gives the Application Developer greater control over the lifecycle of the ServletContext and HttpSession and ServletRequest, allows for better code factorization, and increases efficiency in managing the resources that the web application uses.

Application event listeners are classes that implement one or more of the servlet event listener interfaces. They are instantiated and registered in the web container at the time of the deployment of the web application. They are provided by the Application Developer in the WAR.

Servlet event listeners support event notifications for state changes in the ServletContext, HttpSession and ServletRequest objects. Servlet context listeners are used to manage resources or state held at a JVM level for the application. HTTP session listeners are used to manage state or resources associated with a series of requests made into a web application from the same client or user. Servlet request listeners are used to manage state across the lifecycle of servlet requests. Async listeners are used to manage async events such as time outs and completion of async processing.

There may be multiple listener classes listening to each event type, and the Application Developer may specify the order in which the container invokes the listener beans for each event type.

The following example is the deployment grammar for registering two servlet context lifecycle listeners and an HttpSession listener.

Suppose that com.example.MyConnectionManager and com.example.MyLoggingModule both implement jakarta.servlet.ServletContextListener, and that com.example.MyLoggingModule additionally implements jakarta.servlet.http.HttpSessionListener. Also, the Application Developer wants com.example.MyConnectionManager to be notified of servlet context lifecycle events before com.example.MyLoggingModule. Here is the deployment descriptor for this application:

The container is required to complete instantiation of the listener classes in a web application prior to the start of execution of the first request into the application. The container must maintain a reference to each listener instance until the last request is serviced for the web application.

Attribute changes to ServletContext and HttpSession objects may occur concurrently. The container is not required to synchronize the resulting notifications to attribute listener classes. Listener classes that maintain state are responsible for the integrity of the data and should handle this case explicitly.

Application code inside a listener may throw an exception during operation. Some listener notifications occur under the call tree of another component in the application. An example of this is a servlet that sets a session attribute, where the session listener throws an unhandled exception. The container must allow unhandled exceptions to be handled by the error page mechanism described in Section 10.9, “Error Handling”. If there is no error page specified for those exceptions, the container must ensure to send a response back with status 500. In this case no more listeners under that event are called.

Some exceptions do not occur under the call stack of another component in the application. An example of this is a SessionListener that receives a notification that a session has timed out and throws an unhandled exception, or of a ServletContextListener that throws an unhandled exception during a notification of servlet context initialization, or of a ServletRequestListener that throws an unhandled exception during a notification of the initialization or the destruction of the request object. In this case, the Application Developer has no opportunity to handle the exception. The container may respond to all subsequent requests to the web application with an HTTP status code 500 to indicate an application error.

Developers wishing normal processing to occur after a listener generates an exception must handle their own exceptions within the notification methods.

In distributed web containers, HttpSession instances are scoped to the particular JVM servicing session requests, and the ServletContext object is scoped to the web container’s JVM. Distributed containers are not required to propagate either servlet context events or HttpSession events to other JVMs. Listener class instances are scoped to one per deployment descriptor declaration per JVM.

Listener classes provide the Application Developer with a way of tracking sessions within a web application. It is often useful in tracking sessions to know whether a session became invalid because the container timed out the session, or because a web component within the application called the invalidate method. The distinction may be determined indirectly using listeners and the HttpSession API methods.

Upon receipt of a client request, the web container determines the web application to which to forward it. The web application selected must have the longest context path that matches the start of the request URL. The matched part of the URL is the context path when mapping to servlets. The request URL is decoded as a UTF-8 encoded string. Implementations may provide container vendor specific configuration to change this encoding or enable more fine-grained encoding such as using a different encoding for the path and query string portions of the URL. Note that the encoding used to process the remainder of the request, after the URL, can be configured as specified in Section 3.12, “Request Data Encoding”.

The web container next must locate the servlet to process the request using the path mapping procedure described below.

The path used for mapping to a servlet is the request URL from the request object minus the context path and the path parameters. The URL path mapping rules below are used in order. The first successful match is used with no further matches attempted:

The container must use case-sensitive string comparisons for matching.

In the web application deployment descriptor, the following syntax is used to define mappings:

If the effective web.xml (after merging information from fragments and annotations) contains any url-patterns that are mapped to multiple servlets then the deployment must fail.

Every mapping that causes a servlet to be activated, regardless of whether or not servlet filters are involved, is discoverable at runtime via the servlet mapping API.

A web application contains resources that can be accessed by many users. These resources often traverse unprotected, open networks such as the Internet. In such an environment, a substantial number of web applications will have security requirements.

Although the quality assurances and implementation details may vary, servlet containers have mechanisms and infrastructure for meeting these requirements that share some of the following characteristics:

Declarative security refers to the means of expressing an application’s security model or requirements, including roles, access control, and authentication requirements in a form external to the application. The deployment descriptor is the primary vehicle for declarative security in web applications.

The Deployer maps the application’s logical security requirements to a representation of the security policy that is specific to the runtime environment. At runtime, the servlet container uses the security policy representation to enforce authentication and authorization.

The security model applies to the static content part of the web application and to servlets and filters within the application that are requested by the client. The security model does not apply when a servlet uses the RequestDispatcher to invoke a static resource or servlet using a forward or an include.

Programmatic security is used by security aware applications when declarative security alone is not sufficient to express the security model of the application. Programmatic security consists of the following methods of the HttpServletRequest interface:

The login method allows an application to perform username and password collection (as an alternative to Form-Based Login).

The authenticate methods allow an application to instigate authentication of the request caller by the container from within an unconstrained request context.

The logout method is provided to allow an application to reset the caller identity of a request.

The getRemoteUser method returns the name of the remote user (that is, the caller) associated, by the container, with the request.

The isUserInRole method determines if the remote user (that is, the caller) associated with the request is in a specified security role.

The getUserPrincipal method determines the principal name of the remote user (that is, the caller) and returns a java.security.Principal object corresponding to the remote user. Calling the getName method on the Principal returned by getUserPrincipal returns the name of the remote user. These APIs allow servlets to make business logic decisions based on the information obtained.

If no user has been authenticated, the getRemoteUser method returns null, the isUserInRole method always returns false, and the getUserPrincipal method returns null.

The isUserInRole method takes a String argument that references an application role. For each distinct role reference used in a call to isUserInRole, A security-role-ref element with role-name corresponding to the role reference should be declared in the deployment descriptor. Each security-role-ref should contain a role-link sub-element whose value is the name of the application security role to which the application embedded role reference is linked. The container uses the security-role-ref with role-name equal to the role reference to determine which security-role to test the user for membership in.

For example, to map the security role reference "FOO" to the security role with role-name "manager" the syntax would be:

In this case, if a servlet called by a user belonging to the "manager" security role were to call isUserInRole("FOO") the result would be true.

If no matching security-role-ref exists for a role reference used in a call to isUserInRole, the container must default to testing the user for membership in the security-role with role-name equal to the role reference used in the call.

The role name "*" should never be used as an argument in calling isUserInRole. Any call to isUserInRole with "*" must return false. If the role-name of the security-role to be tested is "**", and the application has NOT declared an application security-role with role-name "**", isUserInRole must only return true if the user has been authenticated; that is, only when getRemoteUser and getUserPrincipal would both return a non-null value. Otherwise, the container must check the user for membership in the application role.

The declaration of security-role-ref elements informs the deployer of the role references used by the application and for which mappings must be defined.

This section defines the annotations and APIs provided to configure the security constraints enforced by the servlet container.

A security role is a logical grouping of users defined by the Application Developer or Assembler. When the application is deployed, roles are mapped by a Deployer to principals or groups in the runtime environment.

A servlet container enforces declarative or programmatic security for the principal associated with an incoming request based on the security attributes of the principal. This may happen in either of the following ways:

A web client can authenticate a user to a web server using one of the following mechanisms:

As the underlying security identities (such as users and groups) to which roles are mapped in a runtime environment are environment specific rather than application specific, it is desirable to:

Therefore, a servlet container is required to track authentication information at the container level (rather than at the web application level). This allows users authenticated for one web application to access other resources managed by the container permitted to the same security identity.

Security constraints are a declarative way of defining the protection of web content. A security constraint associates authorization and/or user data constraints with HTTP operations on web resources. A security constraint, represented as a security-constraint in a deployment descriptor, consists of the following elements:

The HTTP operations and web resources to which a security constraint applies (i.e. the constrained requests) are identified by one or more web resource collections. A web resource collection consists of the following elements:

An authorization constraint establishes a requirement for authentication and names the authorization roles permitted to perform the constrained requests. A user must be a member of at least one of the named roles to be permitted to perform the constrained requests. The special role name "*" is a shorthand for all role names defined in the deployment descriptor. The special role name "**" is a shorthand for any authenticated user independent of role. When the special role name "**" appears in an authorization constraint, it indicates that any authenticated user, independent of role, is authorized to perform the constrained requests. An authorization constraint that names no roles indicates that access to the constrained requests must not be permitted under any circumstances. An authorization constraint consists of the following element:

A user data constraint establishes a requirement that the constrained requests be received over a protected transport layer connection. The strength of the required protection is defined by the value of the transport guarantee. A transport guarantee of INTEGRAL is used to establish a requirement for content integrity and a transport guarantee of CONFIDENTIAL is used to establish a requirement for confidentiality. The transport guarantee of NONE indicates that the container must accept the constrained requests when received on any connection including an unprotected one. Containers may impose a confidential transport guarantee in response to the INTEGRAL value. A user data constraint consists of the following element:

If no authorization constraint applies to a request, the container must accept the request without requiring user authentication. If no user data constraint applies to a request, the container must accept the request when received over any connection including an unprotected one.

By default, authentication is not needed to access resources. Authentication is required when the security constraints (if any) that contain the url-pattern that is the best match for the request URI combine to impose an auth-constraint (naming roles) on the HTTP method of the request. Similarly, a protected transport is not required unless the security constraints that apply to the request combine to impose a user-data-constraint (with a protected transport-guarantee) on the HTTP method of the request.

The container establishes the caller identity of a request prior to dispatching the request to the servlet engine. The caller identity remains unchanged throughout the processing of the request or until the application sucessfully calls authenticate, login or logout on the request. For asynchronous requests, the caller identity established at the initial dispatch remains unchanged until the processing of the overall request completes, or the application successfully calls authenticate, login or logout on the request.

Being logged into an application during the processing of a request, corresponds precisely to there being a valid non-null caller identity associated with the request as may be determined by calling getRemoteUser or getUserPrincipal on the request. A null return value from either of these methods indicates that the caller is not logged into the application with respect to the processing of the request.

Containers may create HTTP Session objects to track login state. If a developer creates a session while a user is not authenticated, and the container then authenticates the user, the session visible to developer code after login must be the same session object that was created prior to login occurring so that there is no loss of session information.

The following types of configuration and deployment information are required to be supported in the web application deployment descriptor for all servlet containers:

This section lists some general rules that web containers and developers must note concerning the processing of the deployment descriptor for a web application.