:xrefstyle: full
:spec-version: 6.1
:spec-version-underscore: 6_1

:sectnums!:
:figure-caption!:
== Jakarta Servlet Specification, Version {spec-version}

Copyright (c) 2024 Contributors to the Eclipse Foundation.

Eclipse is a registered trademark of the Eclipse Foundation. Jakarta
is a trademark of the Eclipse Foundation. Oracle and Java are
registered trademarks of Oracle and/or its affiliates. Other names
may be trademarks of their respective owners.

The Jakarta Servlet Team

Comments to: servlet-dev@eclipse.org

=== Preface

This document is the Jakarta Servlet
Specification, version {spec-version}. The standard for the Jakarta Servlet API is
described herein.

=== Additional Sources

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:

* A compatible implementation (CI) has been made
available which provides a behavioral benchmark for this specification.
Where the specification leaves implementation of a particular feature
open to interpretation, implementors may use the reference
implementation as a model of how to carry out the intention of the
specification.

* The Jakarta EE Platform TCK has been
provided for assessing whether implementations meet the compatibility
requirements of the Jakarta Servlet API standard. The test results have
normative value for resolving questions about whether an implementation
is standard.

* If further clarification is required, the
working group for the Jakarta Servlet API under the Jakarta EE Working Group
should be consulted, and is the final arbiter of such issues.

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

=== Who Should Read This Specification

The intended audience for this specification
includes the following groups:

* Web server and application server vendors that
want to provide servlet engines that conform to this standard.

* Authoring tool developers that want to support
web applications that conform to this specification.

* Experienced servlet authors who want to
understand the underlying mechanisms of servlet technology.

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

=== API Reference

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`.

=== Other Jakarta Platform Specifications

The following Jakarta API specifications are
referenced throughout this specification:

* Jakarta EE Platform, version 11

* Jakarta Server Pages™ (JSP), version 4.0

* Java Naming and Directory Interface™ (JNDI).

* Jakarta Context and Dependency Injection for the Jakarta EE Platform

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

References to other specifications that are part of the Jakarta EE platform exclude the versions of
those specifications that target Jakarta EE 8 due to the different name-space used.

=== Other Important References

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

* RFC 1630 Uniform Resource Identifiers (URI)

* RFC 1738 Uniform Resource Locators (URL)

* RFC 3986 Uniform Resource Identifiers (URI):
Generic Syntax

* RFC 1945 Hypertext Transfer Protocol (HTTP/1.0)

* RFC 2045 MIME Part One: Format of Internet Message Bodies

* RFC 2046 MIME Part Two: Media Types

* RFC 2047 MIME Part Three: Message Header Extensions for non-ASCII text

* RFC 2048 MIME Part Four: Registration Procedures

* RFC 2049 MIME Part Five: Conformance Criteria and Examples

* RFC 6265 HTTP State Management Mechanism

* RFC 7258 Pervasive Monitoring Is an Attack

* RFC 7541 HPACK: Header Compression for HTTP/2 (HPACK)

* RFC 7301 Transport Layer Security (TLS)
Application-Layer Protocol Negotiation Extension (ALPN)

* RFC 7168 The Hyper Text Coffee Pot
Control Protocol for Tea Ef (HTCPCP-TEA)footnote:[This reference is mostly
tongue-in-cheek although most of the concepts described in the HTCPCP
-TEA RFC are relevant to all well-designed web servers.]

* RFC 2119 Key words for use in RFCs to Indicate
Requirement Levels

* RFC 7616 HTTP Digest Access Authentication

* RFC 7617 The 'Basic' HTTP Authentication Scheme

* RFC 8297 An HTTP Status Code for Indicating Hints

* RFC 9110 HTTP Semantics

* RFC 9111 HTTP Caching

* RFC 9112 HTTP/1.1

* RFC 9113 HTTP/2

* RFC 9114 HTTP/3

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.

=== Providing Feedback

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

:sectnums:
== Overview

=== What is a Servlet?

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.

=== What is a 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 and HTTPS as protocols for requests
and responses, but additional request/response-based protocols 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 9111 (HTTP 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 9111.

A servlet container may place security restrictions on the environment in which
a servlet executes.

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

=== An Example

The following is a typical sequence of events:

. A client (e.g., a web browser) accesses a web
server and makes an HTTP request.

. The request is received by the web server and
handed off to the servlet container. The servlet container can be
running in the same process as the host web server, in a different
process on the same host, or on a different host from the web server for
which it processes requests.

. The servlet container determines which servlet
to invoke based on the configuration of its servlets, and calls it with
objects representing the request and response.

. The servlet uses the request object to find
out who the remote user is, what HTTP `POST` parameters may have been
sent as part of this request, and other relevant data. The servlet
performs whatever logic it was programmed with, and generates data to
send back to the client. It sends this data back to the client via the
response object.

. Once the servlet has finished processing the
request, the servlet container ensures that the response is properly
flushed, and returns control back to the host web server.

=== Comparing Servlets with Other Technologies

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:

* They are generally much faster than CGI
scripts because a different process model is used.

* They use a standard API that is supported by
many web servers.

* They have all the advantages of the Java
programming language, including ease of development and platform
independence.

* They can access the large set of APIs
available for the Java platform.

== The Servlet Interface


The `Servlet` interface is the central
abstraction of the Jakarta Servlet API. All servlets implement this
interface either directly, or more commonly, by extending a class that
implements the interface. The two classes in the Jakarta Servlet API that
implement the `Servlet` interface are `GenericServlet` and `HttpServlet`.
For most purposes, Developers will extend `HttpServlet` to implement
their servlets.

=== Request Handling Methods

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 requires that the web developer design servlets
that can deal with multiple threads executing within the `service`
method at a particular time.

==== HTTP Specific Request Handling Methods

The `HttpServlet` abstract subclass adds
additional methods beyond the basic `Servlet` interface that are
automatically called by the `service` method in the `HttpServlet` class
to aid in processing HTTP-based requests. These methods are:

* `doGet` for handling HTTP `GET` requests

* `doPost` for handling HTTP `POST` requests

* `doPut` for handling HTTP `PUT` requests

* `doDelete` for handling HTTP `DELETE` requests

* `doHead` for handling HTTP `HEAD` requests

* `doOptions` for handling HTTP `OPTIONS` requests

* `doTrace` for handling HTTP `TRACE` requests

Typically when developing HTTP-based servlets,
an Application Developer is concerned with the `doGet` and
`doPost` methods. The other methods are considered to be methods for use
by programmers very familiar with HTTP programming.

==== HEAD Method
The `doHead` method in `HttpServlet`, by default, directly calls the `doGet` method and relies on the container to implement HEAD behaviour of the HTTP protocol.
However, if the "jakarta.servlet.http.legacyDoHead" `ServletConfig` init parameter is set to "TRUE" then the `doGet` method is called with the `ServletResponse` wrapped to provide  only the headers produced by the `doGet` method.
The legacy mode is deprecated as it may not be accurate in producing the same heads as `GET` method would have returned and may be removed in a future release.

==== Additional Methods

The `doPut` and `doDelete` methods allow
Servlet Developers to support HTTP/1.1 clients that employ these
features.  The `doOptions` method responds with which HTTP methods are
supported by the servlet. The `doTrace` method generates a response
containing all instances of the headers sent in the `TRACE` request.

The `CONNECT` method applies to proxies whereas the Jakarta Servlet API is
targeted at endpoints so, by default, Containers must reject such requests with
an `SC_NOT_IMPLEMENTED` (501) response and not pass the request to a Filter or
Servlet. Containers may provide container specific functionality to handle
`CONNECT` requests. If that functionality includes passing `CONNECT` requests to
a Filter or Servlet, then the container should define the expected behaviour of
the Servlet API for such requests in that container.

==== Sensitive headers

The `HttpServlet` class defines the `isSensitiveHeader` method which identifies
headers that will be excluded from a response generated by the default `doTrace`
implementation as recommended by RFC 9110. The default implementation identifies
the following headers as sensitive:
- `Authorization`
- `Cookie`
- `X-Forwarded`
- `Forwarded`
- `Proxy-Authorization`
The handling of sensitive headers may be customized by over-riding the
`isSensitiveHeader` and/or `doTrace` methods.

==== Conditional GET Support

The `HttpServlet` class defines the
`getLastModified` method to support conditional `GET` operations. A
conditional `GET` operation requests a resource be sent only if it has
been modified since a specified time. In appropriate situations,
implementation of this method may aid efficient utilization of network
resources.

=== Number of Instances

The servlet declaration which is either via
the annotation as described in <<Annotations and Pluggability>> or
part of the deployment descriptor of
the web application containing the servlet, as described in
<<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.

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™).

=== Servlet Life Cycle

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.

==== Loading and Instantiation

The servlet container is responsible for
loading and instantiating servlets. The loading and instantiation can
occur when the container is started, or delayed until the container
determines the servlet is needed to service a request.

When the servlet engine is started, needed
servlet classes must be located by the servlet container. The servlet
container loads the servlet class using normal Java class loading
facilities. The loading may be from a local file system, a remote file
system, or other network services.

After loading the `Servlet` class, the
container instantiates it for use.

==== Initialization

After the servlet object is instantiated, the
container must initialize the servlet before it can handle requests from
clients. Initialization is provided so that a servlet can read
persistent configuration data, initialize costly resources (such as
JDBC™ API-based connections), and perform other one-time activities. The
container initializes the servlet instance by calling the `init` method
of the `Servlet` interface with a unique (per servlet declaration)
object implementing the `ServletConfig` interface. This configuration
object allows the servlet to access name-value initialization parameters
from the web application’s configuration information. The configuration
object also gives the servlet access to an object (implementing the
`ServletContext` interface) that describes the servlet’s runtime
environment. See <<Servlet Context>>
for more information about the `ServletContext` interface.

===== Error Conditions on Initialization

During initialization, the servlet instance
can throw an `UnavailableException` or a `ServletException`. In this
case, the servlet must not be placed into active service and must be
released by the servlet container. The `destroy` method is not called as
it is considered unsuccessful initialization.

A new instance may be instantiated and
initialized by the container after a failed initialization. The
exception to this rule is when an `UnavailableException` indicates a
minimum time of unavailability, and the container must wait for the
period to pass before creating and initializing a new servlet instance.

===== Tool Considerations

The triggering of static initialization
methods when a tool loads and introspects a web application is to be
distinguished from the calling of the `init` method. Developers should
not assume a servlet is in an active container runtime until the `init`
method of the `Servlet` interface is called. For example, a servlet
should not try to establish connections to databases or Jakarta Enterprise
Beans containers when only static (class) initialization methods
have been invoked.

==== Request Handling

After a servlet is properly initialized, the
servlet container may use it to handle client requests. Requests are
represented by request objects of type `ServletRequest`. The servlet
fills out responses to requests by calling methods of a provided object
of type `ServletResponse`. These objects are passed as parameters to
the `service` method of the `Servlet` interface.

In the case of an HTTP request, the objects
provided by the container are of types `HttpServletRequest` and
`HttpServletResponse`.

Note that a servlet instance placed into
service by a servlet container may handle no requests during its
lifetime.

===== Multithreading Issues

A servlet container may send concurrent
requests through the `service` method of the servlet. To handle the
requests, the Application Developer must make adequate provisions for
concurrent processing with multiple threads in the `service` method.

It is strongly recommended that Developers not synchronize the `service` method
(or methods dispatched to it) because of the detrimental effects on performance.

===== Exceptions During Request Handling

A servlet may throw either a
`ServletException` or an `UnavailableException` during the service of a
request. A `ServletException` signals that some error occurred during
the processing of the request and that the container should take
appropriate measures to clean up the request.

An `UnavailableException` signals that the
servlet is unable to handle requests either temporarily or permanently.

If a permanent unavailability is indicated by
the `UnavailableException`, the servlet container must remove the
servlet from service, call its `destroy` method, and release the servlet
instance. Any requests refused by the container by that cause must be
returned with a `SC_NOT_FOUND` (404) response.

If temporary unavailability is indicated by
the `UnavailableException`, the container may choose to not route any
requests through the servlet during the time period of the temporary
unavailability. Any requests refused by the container during this period
must be returned with a `SC_SERVICE_UNAVAILABLE` (503) response status
along with a `Retry-After` header indicating when the unavailability
will terminate.

The container may choose to ignore the
distinction between a permanent and temporary unavailability and treat
all `UnavailableExceptions` as permanent, thereby removing a servlet
that throws any `UnavailableException` from service.

===== Asynchronous processing

Sometimes a filter and/or servlet is unable
to complete the processing of a request without waiting for a resource
or event before generating a response. For example, a servlet may need
to wait for an available JDBC connection, for a response from a remote
web service, for a JMS message, or for an application event, before
proceeding to generate a response. Waiting within the servlet is an
inefficient operation as it is a blocking operation that consumes a
thread and other limited resources. Frequently a slow resource such as a
database may have many threads blocked waiting for access and can cause
thread starvation and poor quality of service for an entire web
container.

The asynchronous processing of requests is
introduced to allow the thread to return to the container and perform
other tasks. When asynchronous processing begins on the request, another
thread or callback may either generate the response and call `complete`
or dispatch the request so that it may run in the context of the
container using the `AsyncContext.dispatch` method. A typical sequence
of events for asynchronous processing is:

. The request is received and passed via normal
filters for authentication etc. to the servlet.

. The servlet processes the request parameters
and/or content to determine the nature of the request.

. The servlet issues requests for resources or
data, for example, sends a remote web service request or joins a queue
waiting for a JDBC connection.

. The servlet returns without generating a response.

. After some time, the requested resource
becomes available, the thread handling that event continues processing
either in the same thread or by dispatching to a resource in the
container using the `AsyncContext`.

Jakarta EE features such as <<_Web_Application_Environment>> and
<<Propagation of Security Identity in Jakarta Enterprise Bean Calls>>
are available only to threads executing the initial request or when
the request is dispatched to the container via the
`AsyncContext.dispatch` method. Jakarta EE features may be available
to other threads operating directly on the response object via the
`AsyncContext.start(Runnable)` method.

The `@WebServlet` and `@WebFilter`
annotations described in Chapter 8 have an attribute `asyncSupported`
that is a `boolean` with a default value of `false`. When
`asyncSupported` is set to true the application can start asynchronous
processing in a separate thread by calling `startAsync` (see below),
passing it a reference to the request and response objects, and then
exit from the container on the original thread. This means that the
response will traverse (in reverse order) the same filters (or filter
chain) that were traversed on the way in. The response isn't committed
till `complete` (see below) is called on the `AsyncContext`. The
application is responsible for handling concurrent access to the request
and response objects if the async task is executing before the
container-initiated dispatch that called `startAsync` has returned to
the container.

Dispatching from a servlet that has
`asyncSupported=true` to one where `asyncSupported` is set to `false` is
allowed. In this case, the response will be committed when the service
method of the servlet that does not support async is exited, and it is
the container's responsibility to call `complete` on the `AsyncContext`
so that any interested `AsyncListener` instances will be notified. The
`AsyncListener.onComplete` notification should also be used by filters
as a mechanism to clear up resources that they have been holding on to for
the async task to complete.

Dispatching from a synchronous servlet to an
asynchronous servlet would be illegal. However the decision of throwing
an `IllegalStateException` is deferred to the point when the application
calls `startAsync`. This would allow a servlet to either function as a
synchronous or an asynchronous servlet.

The async task that the application is
waiting for could write directly to the response, on a different thread
than the one that was used for the initial request. This thread knows
nothing about any filters. If a filter wanted to manipulate the response
in the new thread, it would have to wrap the response when it was
processing the initial request "on the way in", and passed the wrapped
response to the next filter in the chain, and eventually to the servlet.
So if the response was wrapped (possibly multiple times, once per
filter), and the application processes the request and writes directly
to the response, it is really writing to the response wrapper(s), i.e.,
any output added to the response will still be processed by the response
wrapper(s). When an application reads from a request in a separate
thread, and adds output to the response, it really reads from the
request wrapper(s), and writes to the response wrapper(s), so any input
and/or output manipulation intended by the wrapper(s) will continue to
occur.

Alternately if the application chooses to do
so it can use the `AsyncContext` to `dispatch` the request from the new
thread to a resource in the container. This would enable using content
generation technologies like Jakarta Server Pages within the scope of
the container.

In addition to the annotation attributes, the following methods / classes
are provided:

.ServletRequest

`public AsyncContext startAsync(ServletRequest req, ServletResponse res)`::
This method puts
the request into asynchronous mode and initializes its `AsyncContext`
with the given request and response objects and the time out returned by
`getAsyncTimeout`. The `ServletRequest` and `ServletResponse`
parameters MUST be either the same objects as were passed to the calling
servlet’s `service`, or the filter’s `doFilter` method, or be
subclasses of `ServletRequestWrapper` or `ServletResponseWrapper`
classes that wrap them. A call to this method ensures that the response
isn't committed when the application exits out of the `service` method.
It is committed when `AsyncContext.complete` is called on the returned
`AsyncContext` or the `AsyncContext` times out and there are no
listeners associated to handle the time out. The timer for async time
outs will not start until the request and its associated response have
returned from the container. The `AsyncContext` could be used to write
to the response from the async thread. It can also be used to just
notify that the response is not closed and committed.
+
It is illegal to call `startAsync` if the
request is within the scope of a servlet or filter that does not support
asynchronous operations, or if the response has been committed and
closed, or is called again during the same `dispatch`. The
`AsyncContext` returned from a call to `startAsync` can then be used for
further asynchronous processing. Calling the
`AsyncContext.hasOriginalRequestResponse()` on the returned
`AsyncContext` will return `false`, unless the passed `ServletRequest`
and `ServletResponse` arguments are the original ones and do not carry
application provided wrappers. Any filters invoked in the outbound
direction after this request was put into asynchronous mode MAY use this
as an indication that some of the request and / or response wrappers
that they added during their inbound invocation MAY need to stay in
place for the duration of the asynchronous operation, and their
associated resources MAY not be released. A `ServletRequestWrapper`
applied during the inbound invocation of a filter MAY be released by the
outbound invocation of the filter only if the given `ServletRequest`
which is used to initialize the `AsyncContext` and will be returned by a
call to `AsyncContext.getRequest()`, does not contain the said
`ServletRequestWrapper`. The same holds true for
`ServletResponseWrapper` instances.

`public AsyncContext startAsync()`::
This method is
provided as a convenience that uses the original request and response
objects for the async processing. Please note users of this method
SHOULD flush the response if they are wrapped before calling this method
if you wish, to ensure that any data written to the wrapped response
isn’t lost.

`public AsyncContext getAsyncContext()`::
Returns the `AsyncContext` that was created or re initialized by the
invocation of `startAsync`. It is illegal to call `getAsyncContext` if
the request has not been put in asynchronous mode.

`public boolean isAsyncSupported()`::
Returns `true` if the request supports async processing, and `false`
otherwise. Async support will be disabled as soon as the request has
passed a filter or servlet that does not support async processing
(either via the designated annotation or declaratively).

 `public boolean isAsyncStarted()`::
Returns `true` if async processing has started on this request, and `false`
otherwise. If this request has been dispatched using one of the
`AsyncContext.dispatch` methods since it was put in asynchronous mode,
or a call to `AsynContext.complete` is made, this method returns `false`.

`public DispatcherType getDispatcherType()`::
Returns the dispatcher type of a request. The dispatcher type of a
request is used by the container to select the filters that need to be
applied to the request. Only filters with the matching dispatcher type
and url patterns will be applied. Allowing a filter that has been
configured for multiple dispatcher types to query a request for its
dispatcher type allows the filter to process the request differently
depending on its dispatcher type. The initial dispatcher type of a
request is defined as `DispatcherType.REQUEST`. The dispatcher type of
a request dispatched via `RequestDispatcher.forward(ServletRequest,
ServletResponse)` or `RequestDispatcher.include(ServletRequest,
ServletResponse)` is given as `DispatcherType.FORWARD` or
`DispatcherType.INCLUDE` respectively, while a dispatcher type of an
asynchronous request dispatched via one of the `AsyncContext.dispatch`
methods is given as `DispatcherType.ASYNC`. Finally the dispatcher type
of a request dispatched to an error page by the container’s error
handling mechanism is given as `DispatcherType.ERROR`.

.AsyncContext

This class represents the execution context
for the asynchronous operation that was started on the `ServletRequest`.
An `AsyncContext` is created and initialized by a call to
`ServletRequest.startAsync` as described above. The following methods
are in the `AsyncContext`:

`public ServletRequest getRequest()`::
Returns the request that was used to initialize the `AsyncContext` by
calling one of the `startAsync` methods. Calling `getRequest` when
complete or any of the dispatch methods has been previously called in
the asynchronous cycle will result in an `IllegalStateException`.

`public ServletResponse getResponse()`::
Returns the response that was used to initialize the `AsyncContext` by
calling one of the `startAsync` methods. Calling `getResponse` when
complete or any of the dispatch methods has been previously called in
the asynchronous cycle will result in an `IllegalStateException`.

`public void setTimeout(long timeoutMilliseconds)`::
Sets the time out for the asynchronous
processing in milliseconds. A call to this method overrides the
time out set by the container. If the time out is not specified via the
call to `setTimeout`, 30000 is used as the default. A value of 0 or
less indicates that the asynchronous operation will never time out. The
time out applies to the `AsyncContext` once the container-initiated
dispatch, during which one of the `ServletRequest.startAsync` methods was
called, has returned to the container. It is illegal to call
this method after the container-initiated dispatch on which
the asynchronous cycle was started has returned to the container and
will result in an `IllegalStateException`.

`public long getTimeout()`::
Gets the time
out, in milliseconds, associated with the `AsyncContext`. This method
returns the container’s default time out, or the time out value set via
the most recent invocation of `setTimeout` method.

`public void addListener(AsyncListener listener, ServletRequest req, ServletResponse res)`::
Registers the
given listener for notifications of `onTimeout`, `onError`, `onComplete` or
`onStartAsync`. The first three are associated with the most recent
asynchronous cycle started by calling one of the
`ServletRequest.startAsync` methods. The `onStartAsync` is associated to
a new asynchronous cycle via one of the `ServletRequest.startAsync`
methods. Async listeners will be notified in the order in which they
were added to the request. The request and response objects passed in to
the method are the exact same ones that are available from the
`AsyncEvent.getSuppliedRequest()` and `AsyncEvent.getSuppliedResponse()`
when the `AsyncListener` is notified. These objects should not be read
from or written to, because additional wrapping may have occurred since
the given `AsyncListener` was registered, but may be used in order to
release any resources associated with them. It is illegal to call this
method after the container-initiated dispatch on which the asynchronous
cycle was started has returned to the container and before a new
asynchronous cycle was started and will result in an
`IllegalStateException`.

`public <T extends AsyncListener> createListener(Class<T> clazz)`::
Instantiates the given `AsyncListener`
class. The returned `AsyncListener` instance may be further customized
before it is registered with the `AsyncContext` via a call to one of the
`addListener` methods specified below. The given `AsyncListener` class
MUST define a zero argument constructor, which is used to instantiate
it. This method supports any annotations applicable to the
`AsyncListener`.

`public void addListener(AsyncListener)`::
Registers the given listener for notifications of `onTimeout`, `onError`,
`onComplete` or `onStartAsync`. The first three are associated with the
most recent asynchronous cycle started by calling one of the
`ServletRequest.startAsync` methods. The `onStartAsync` is associated to
a new asynchronous cycle via one of the `ServletRequest.startAsync`
methods. If `startAsync(req, res)` or `startAsync()` is called on the
request, the exact same request and response objects are available from
the `AsyncEvent` when the `AsyncListener` is notified. The request and
response may or may not be wrapped. Async listeners will be notified in
the order in which they were added to the request. It is illegal to call
this method after the container-initiated dispatch on which the
asynchronous cycle was started has returned to the container and before
a new asynchronous cycle was started and will result in an
`IllegalStateException`.

`public void dispatch(String path)`::
Dispatches the request and response that were used to initialize the
`AsyncContext` to the resource with the given path. The given path is
interpreted as relative to the `ServletContext` that initialized the
`AsyncContext`. All path related query methods of the request MUST
reflect the dispatch target, while the original request URI, context
path, path info and query string may be obtained from the request
attributes as defined in <<Dispatched Request Parameters>>.
These attributes MUST always reflect the original
path elements, even after multiple dispatches.

`public void dispatch()`::
Provided as a
convenience to dispatch the request and response used to initialize the
`AsyncContext` as follows. If the `AsyncContext` was initialized via the
`startAsync(ServletRequest, ServletResponse)` and the request passed is
an instance of `HttpServletRequest`, then the dispatch is to the URI
returned by `HttpServletRequest.getRequestURI()`. Otherwise the
dispatch is to the URI of the request when it was last dispatched by the
container. The examples <<CODE_EXAMPLE_2_1>>, <<CODE_EXAMPLE_2_2>> and
<<CODE_EXAMPLE_2_3>> shown below demonstrate what the
target URI of dispatch would be in the different cases.

[[CODE_EXAMPLE_2_1]]
.CODE EXAMPLE 2-1
[source,java]
----
// REQUEST to /url/A
AsyncContext ac = request.startAsync();
...
ac.dispatch(); // ASYNC dispatch to /url/A
----

[[CODE_EXAMPLE_2_2]]
.CODE EXAMPLE 2-2
[source,java]
----
// REQUEST to /url/A

// FORWARD to /url/B

request.getRequestDispatcher("/url/B").forward(request, response);

// Start async operation from within the target of the FORWARD

AsyncContext ac = request.startAsync();

ac.dispatch(); // ASYNC dispatch to /url/A
----

[[CODE_EXAMPLE_2_3]]
.CODE EXAMPLE 2-3
[source,java]
----
// REQUEST to /url/A

// FORWARD to /url/B

request.getRequestDispatcher("/url/B").forward(request, response);

// Start async operation from within the target of the FORWARD

AsyncContext ac = request.startAsync(request, response);

ac.dispatch(); // ASYNC dispatch to /url/B
----

`public void dispatch(ServletContext context, String path)`::
Dispatches the request and response used to
initialize the `AsyncContext` to the resource with the given path in the
given `ServletContext`.
+
For all the 3 variations of the `dispatch`
methods defined above, calls to the methods returns immediately after
passing the request and response objects to a container managed thread,
on which the dispatch operation will be performed. The dispatcher type
of the request is set to `ASYNC`. Unlike
`RequestDispatcher.forward(ServletRequest, ServletResponse)` dispatches,
the response buffer and headers will not be reset, and it is legal to
dispatch even if the response has already been committed. Control over
the request and response is delegated to the dispatch target, and the
response will be closed when the dispatch target has completed
execution, unless `ServletRequest.startAsync()` or
`ServletRequest.startAsync(ServletRequest, ServletResponse)` is called.
If any of the dispatch methods are called before the container-initiated
dispatch that called `startAsync` has returned to the container, the
following conditions must hold during that time between the invocation
of `dispatch` and the return of control to the container:
+
--
[lowerroman]
. any `dispatch` invocations invoked during
that time will not take effect until after the container-initiated
dispatch has returned to the container.

. any `AsyncListener.onComplete(AsyncEvent)`,
`AsyncListener.onTimeout(AsyncEvent)` and
`AsyncListener.onError(AsyncEvent)` invocations will also be delayed
until after the container-initiated dispatch has returned to the
container.

. any calls to `request.isAsyncStarted()` must
return `true` until after the container-initiated dispatch has returned
to the container.
--
+
There can be at most one asynchronous
dispatch operation per asynchronous cycle, which is started by a call to
one of the `ServletRequest.startAsync` methods. Any attempt to perform
additional asynchronous dispatch operations within the same asynchronous
cycle is illegal and will result in an `IllegalStateException`. If
`startAsync` is subsequently called on the dispatched request, then any
of the `dispatch` methods may be called with the same restriction as
above.
+
[[Dispatch_Errors,dispatch error handling]]
Any errors or exceptions
that may occur during the execution of the `dispatch` methods MUST be
caught and handled by the container as follows:
+
--
[lowerroman]
. invoke the
`AsyncListener.onError(AsyncEvent)` method for all instances of the
`AsyncListener` registered with the `ServletRequest` for which the
`AsyncContext` was created and make the `Throwable` available via the
`AsyncEvent.getThrowable()`.

. If none of the listeners called
`AsyncContext.complete` or any of the `AsyncContext.dispatch` methods,
then perform an error dispatch with a status code equal to
`HttpServletResponse.SC_INTERNAL_SERVER_ERROR` and make the `Throwable`
available as the value of the `RequestDispatcher.ERROR_EXCEPTION`
request attribute.

. If no matching error page is found, or the
error page does not call `AsyncContext.complete()` or any of the
`AsyncContext.dispatch` methods, then the container MUST call
`AsyncContext.complete`.
--

`public boolean hasOriginalRequestAndResponse()`::
This method checks if the
`AsyncContext` was initialized with the original request and response
objects by calling `ServletRequest.startAsync()` or if it was
initialized by calling `ServletRequest.startAsync(ServletRequest,
ServletResponse)` and neither the `ServletRequest` nor the
`ServletResponse` argument carried any application provided wrappers, in
which case it returns `true`. If the `AsyncContext` was initialized
with wrapped request and/or response objects using
`ServletRequest.startAsync(ServletRequest, ServletResponse)`, it
returns `false`. This information may be used by filters invoked in the
outbound direction, after a request was put into asynchronous mode, to
determine whether any request and/or response wrappers that they added
during their inbound invocation need to be preserved for the duration of
the asynchronous operation or may be released.

`public void start(Runnable r)`::
This method causes the container to dispatch a thread, possibly from a
managed thread pool, to run the specified `Runnable`. The container may
propagate appropriate contextual information to the `Runnable`.

 `public void complete()`::
 If `request.startAsync` is called then this method MUST be called to
complete the async processing and commit and close the response. The
`complete` method can be invoked by the container if the request is
dispatched to a servlet that does not support async processing, or the
target servlet called by `AsyncContext.dispatch` does not do a
subsequent call to `startAsync`. In this case, it is the container's
responsibility to call `complete()` as soon as that servlet's `service`
method is exited. An `IllegalStateException` MUST be thrown if
`startAsync` was not called. It is legal to call this method anytime
after a call to `ServletRequest.startAsync()` or
`ServletRequest.startAsync(ServletRequest, ServletResponse)` and before
a call to one of the dispatch methods. If this method is called before
the container-initiated dispatch that called `startAsync` has returned
to the container, the following conditions must hold during that time
between the invocation of `complete` and the return of control to the
container:
+
[lowerroman]
. the behavior specified for `complete` will
not take effect until after the container-initiated dispatch has
returned to the container.

. any `AsyncListener.onComplete(AsyncEvent)`
invocations will also be delayed until after the container-initiated
dispatch has returned to the container.

. any calls to `request.isAsyncStarted()` must
return `true` until after the container-initiated dispatch has returned
to the container.

.ServletRequestWrapper

`public boolean isWrapperFor(ServletRequest req)`::
Checks recursively if this wrapper wraps the given
`ServletRequest` and returns `true` if it does, else it returns `false`.

.ServletResponseWrapper

`public boolean isWrapperFor(ServletResponse res)`::
Checks recursively if this wrapper wraps the given
`ServletResponse` and returns `true` if it does, else it returns `false`.

.AsyncListener

 `public void onComplete(AsyncEvent event)`::
Is used to notify the listener of completion of the asynchronous
operation started on the `ServletRequest`.

 `public void onTimeout(AsyncEvent event)`::
Is used to notify the listener of a time out of the asynchronous
operation started on the `ServletRequest`.

 `public void onError(AsyncEvent event)`::
Is used to notify the listener that the asynchronous operation has failed
to complete.

 `public void onStartAsync(AsyncEvent event)`::
Is used to notify the listener that a new asynchronous cycle is being
initiated via a call to one of the `ServletRequest.startAsync` methods.
The `AsyncContext` corresponding to the asynchronous operation that is
being reinitialized may be obtained by calling
`AsyncEvent.getAsyncContext` on the given event.

In the event that an
asynchronous operation times out, the container must run through the
following steps:

* Invoke the `AsyncListener.onTimeout` method
on all the `AsyncListener` instances registered with the
`ServletRequest` on which the asynchronous operation was initiated.

* If none of the listeners called
`AsyncContext.complete()` or any of the `AsyncContext.dispatch` methods,
perform an error dispatch with a status code equal to
`HttpServletResponse.SC_INTERNAL_SERVER_ERROR`.

* If no matching error page was found, or the
error page did not call `AsyncContext.complete()` or any of the
`AsyncContext.dispatch` methods, the container MUST call
`AsyncContext.complete()`.

* If an exception is thrown while invoking
methods in an `AsyncListener`, it is logged and will not affect the
invocation of any other `AsyncListeners`.

* Async processing in JSP would not be
supported by default as it is used for content generation and async
processing would have to be done before the content generation. It is up
to the container how to handle this case. Once all the async activities
are done, a dispatch to the JSP page using the `AsyncContext.dispatch`
can be used for generating content.

* Figure 2-1 shown below is a diagram depicting
the state transitions for various asynchronous operations.

.*Figure 2-1* State transition diagram for asynchronous operations
image::state-transition.png[image]

===== Thread Safety

Other than the `startAsync` and `complete`
methods, implementations of the request and response objects are not
guaranteed to be thread safe. This means that they should either only be
used within the scope of the request handling thread or the application
must ensure that access to the request and response objects are thread
safe.

If a thread created by the application uses
the container-managed objects, such as the request or response object,
those objects must be accessed only within the object’s life cycle as
defined in sections <<Lifetime of the Request Object>> and
<<Lifetime of the Response Object>> respectively.
Be aware that other than the `startAsync`, and `complete` methods,
the request and response objects are not thread safe.
If those objects were accessed in the multiple threads, the
access should be synchronized or be done through a wrapper to add the
thread safety, for instance, synchronizing the call of the methods to
access the request attribute, or using a local output stream for the
response object within a thread.

===== Upgrade Processing

In HTTP/1.1, the Upgrade header
allows the client to specify the additional communication protocols that
it supports and would like to use. If the server finds it appropriate to
switch protocols, then new protocols will be used in subsequent
communication.

The servlet container provides an HTTP
upgrade mechanism. However the servlet container itself does not have
knowledge about the upgraded protocol. The protocol processing is
encapsulated in the `HttpUpgradeHandler`. Data reading or writing
between the servlet container and the `HttpUpgradeHandler` is in byte
streams.

When an upgrade request is received, the
servlet can invoke the `HttpServletRequest.upgrade` method, which starts
the upgrade process. This method instantiates the given
`HttpUpgradeHandler` class. The returned `HttpUpgradeHandler` instance
may be further customized. The application prepares and sends an
appropriate response to the client. After exiting the `service` method
of the servlet, the servlet container completes the processing of all
filters and marks the connection to be handled by the
`HttpUpgradeHandler`. It then calls the ``HttpUpgradeHandler``'s `init`
method, passing a `WebConnection` to allow the protocol handler access
to the data streams.

The servlet filters only process the initial
HTTP request and response. They are not involved in subsequent
communications. In other words, they are not invoked once the request
has been upgraded.

The `HttpUpgradeHandler` may use non-blocking
IO to consume and produce messages.

The Application Developer has the responsibility for
thread safe access to the `ServletInputStream` and `ServletOutputStream`
while processing HTTP upgrade.

When the upgrade processing is done,
`HttpUpgradeHandler.destroy` will be invoked.

==== End of Service

The servlet container is not required to keep
a servlet loaded for any particular period of time. A servlet instance
may be kept active in a servlet container for a period of milliseconds,
for the lifetime of the servlet container (which could be a number of
days, months, or years), or any amount of time in between.

When the servlet container determines that a
servlet should be removed from service, it calls the `destroy` method of
the `Servlet` interface to allow the servlet to release any resources it
is using and save any persistent state. For example, the container may
do this when it wants to conserve memory resources, or when it is being
shut down.

Before the servlet container calls the
`destroy` method, it must allow any threads that are currently running
in the `service` method of the servlet to complete execution, or exceed
a server-defined time limit.

Once the `destroy` method is called on a
servlet instance, the container may not route other requests to that
instance of the servlet. If the container needs to enable the servlet
again, it must do so with a new instance of the servlet’s class.

After the `destroy` method completes, the
servlet container must release the servlet instance so that it is
eligible for garbage collection.


== The Request


The request object encapsulates all
information from the client request. In the HTTP protocol, this
information is transmitted from the client to the server in the HTTP
headers and the message body of the request.

=== HTTP Protocol Parameters

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 <<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:

* `getParameter`

* `getParameterNames`

* `getParameterValues`

* `getParameterMap`

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.

==== When Parameters Are Available

The following are the conditions that must be
met before form data will be populated to the parameter set:

. The request is an HTTP or HTTPS request.

. The HTTP method is POST.

. The content type is `application/x-www-form-urlencoded`.

. The servlet has made an initial call of any of
the `getParameter` family of methods on the request object.

If the conditions are not met and the
form data is not included in the parameter set, the form data must still
be available to the servlet via the request object’s input stream. If
the conditions are met, form data will no longer be available for
reading directly from the request object’s input stream.

=== File Upload

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.

* The servlet handling the request is annotated
with the `@MultipartConfig` as defined in
<<_MultipartConfig>>.

* Deployment descriptors contain a
`multipart-config` element for the servlet handling the request.

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

* If the servlet container provides
`multipart/form-data` processing, the data is made available through the
following methods in `HttpServletRequest`:
+
--

** `public Collection<Part> getParts()`

** `public Part getPart(String name)`

Each part provides access to the headers,
content type related with it and the content via the
`Part.getInputStream` method.

For parts with `form-data` as the
`Content-Disposition`, but without a filename, the string value of the
part will also be available through the `getParameter` and
`getParameterValues` methods on `HttpServletRequest`, using the name of
the part.

--

* If the servlet container does not provide the
`multi-part/form-data` processing, the data will be available through
`HttpServletRequest.getInputStream`.

=== Attributes

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:

* `getAttribute`

* `getAttributeNames`

* `setAttribute`

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 footnote:[The Java Programming
Language Specification is available at
`http://docs.oracle.com/javase/specs/`] for package naming.

=== Headers

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

* `getHeader`

* `getHeaders`

* `getHeaderNames`

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:

* `getIntHeader`

* `getDateHeader`

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.

=== Request URI Path Processing
The path portion of the URI of an HTTP identifies the resource to be processed. As URI paths may have various non-canonical forms, it is important that all containers process URI paths in the same way so that matching to security constraints and resources is identical.

The process described here adapts and extends the URI canonicalization process described in [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) to create a standard Servlet URI path canonicalization process that ensures that URIs can be mapped to Servlets, Filters and security constraints in an unambiguous manner. It is also intended to provide information to reverse proxy implementations so they are aware of how requests they pass to servlet containers will be processed.

==== Obtaining the URI Path
HTTP/1.0:: The URI path is extracted from the `Request-URI` in the `Request-Line` as defined by [RFC 1945](https://datatracker.ietf.org/doc/html/rfc1945#section-5.1). URIs in `abs_path` form are the URI path. URIs in `absoluteURI` have the protocol and authority removed to convert them to `origin-form` and thus obtain the URI path.

HTTP/1.1:: The URI path is extracted from the `request-target` as defined by [RFC 9112](https://www.rfc-editor.org/rfc/rfc9112.html#name-request-target). URIs in `origin-form` are the URI path. URIs in `absolute-form` have the protocol and authority removed to convert them to `origin-form` and thus obtain the URI path. URIs in `authority-form` or `asterisk-form` are outside of the scope of this specification.

HTTP/2:: The URI path is the `:path` pseudo header as defined by [RFC 9113](https://www.rfc-editor.org/rfc/rfc9113.html#name-request-pseudo-header-field) and is passed unchanged to stage 2.

HTTP/3:: The URI path is the `:path` pseudo header as currently defined by the [RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html#name-request-pseudo-header-field).

Other protocols:: Containers may support other protocols. Containers should extract an appropriate URI path for the request from the protocol and pass it to stage 2.

==== URI Path Canonicalization

Servlet containers may implement the standard Servlet URI path canonicalization in any manner they see fit as long as the end result is identical to the end result of the process described here. Servlet containers may provide container specific configuration options to vary the standard canonicalization process. Any such variations may have security implications and both Servlet container implementors and users are advised to be sure that they understand the implications of any such container specific canonicalization options.

. **Discard fragment.**
+
The path is split by the first occurrence of any `"\#"` character. The `"#"` and following fragment are discarded and the path is replaced with the character sequence preceding the `"#"` character.

. **Separation of path and query.**
+
The URI is split by the first occurrence of any `"?"` character to path and query.  The query is preserved for later handling and the following steps applied to the path.

. **Split path into segments.**
+
The path is split into segments using the `"/"` character as a prefix to each segment. The separating `"/"` does not form part of the resulting segments.   For example, the path `"/foo/bar/"` is split into 3 segments: `"foo"`, `"bar"` and `""`. The prefix `"/"` for the fist segment is optional, but URIs without a leading `"/"` should be rejected below.

. **Remove path parameters.**
+
Any segment containing the `";"` character is split at the first occurrence of `";"`. The segment is replaced by the character sequence preceding the `";"`. The characters following the `";"` are considered path parameters and may be preserved by the container for later decoding and/or processing (eg `jsessionid`).

. **Decode.**
+
Octets that are encoded in `%nn` form are decoded in each segment. The resulting octet sequence is treated as UTF-8 and converted to a character sequence that replaces the segment.

. **Remove Empty Segments.**
+
Empty segments, other than the last segment, are removed.  Containers may be configured to retain all empty segments.

. **Remove dot-segments.**
+
All segments that are exactly `"."` are removed from the segment series. Segments that are exactly `".."` and that are preceded by a non `".."` segment are removed together with the preceding segment. This normalization differs from RFC3986 in that segments with parameters may be treated as dot segments.

. **Concatenate segments.**
+
The segments are concatenated into a single path string with each segment preceded by the `"/"` character. If there are no segments remaining, the resulting path is `"/"`. If a segment contains the "/" or "%" characters, and the container is configured to not reject the request for containing an encoded `"/"`, then the container should re-encode those characters to the %nn form. If any characters are re-encoded, then the `"%"` must also be re-encoded.

. **Mapping URI to context and resource.**
+
The decoded path is used to map the request to a context and resource within the context. This form of the URI path is used for all subsequent mapping (web applications, servlet, filters and security constraints).

. **Rejecting Suspicious Sequences.**
+
If suspicious sequences are discovered during the prior processing steps, the request must be rejected with a 400 bad request rather than dispatched to the target servlet. If a context is matched then the error handling of the context may be used to generate the 400 response. By default, the set of suspicious sequences is defined below, but may be configured differently by a container:

  * The presence of a fragment in the URI
  * Any path not starting with the `"/"` character (e.g. `path/info`)
  * Any path starting with an initial segment of `".."` (e.g. `/../path/info`)
  * The encoded `"/"` character (e.g. `/path%2Finfo`)
  * Any `"."` or `".."` segment that had a path parameter (e.g. `/path/..;/info`)
  * Any `"."` or `".."` segment with any encoded characters (e.g. `/path/%2e%2e/info`)
  * If empty segments are not removed, then `".."` segment preceded by an empty segment (e.g. `/path//../info`)
  * Any empty segment other than the last segment, with parameters (e.g. `/path/;param/info` )
  * The `"\"` character encoded or not. (e.g. `/path\info`)
  * Any control characters either encoded or not.  (e.g. `/path%00/info`)
  * Any illegal hex sequences following a % character
  * Any illegal UTF-8 code sequences.

==== Example URIs
|===
| Encoded URI path  | Decoded Path | Rejected

| `foo/bar` | `/foo/bar` | 400 must start with /
| `/foo/bar` | `/foo/bar` | 
| `/foo/bar;jsessionid=1234` | `/foo/bar` | 
| `/foo/bar/` | `/foo/bar/` | 
| `/foo/bar/;jsessionid=1234` | `/foo/bar/` | 
| `/foo;/bar;` | `/foo/bar` | 
| `/foo;/bar;/;` | `/foo/bar/` | 
| `/foo%00/bar/` | `/foo[NUL]/bar/` | 400 control character
| `/foo%7Fbar` | `/foo[DEL]bar` | 400 control character
| `/foo%2Fbar` | `/foo%2Fbar` | 400 encoded /
| `/foo%2Fb%25r` | `/foo%2Fb%25r` | 400 encoded /
| `/foo/b%25r` | `/foo/b%r` |
| `/foo\bar` | `/foo\bar` | 400 backslash character
| `/foo%5Cbar` | `/foo\bar` | 400 backslash character
| `/foo;%2F/bar` | `/foo/bar` | 400 encoded /
| `/foo/./bar` | `/foo/bar` | 
| `/foo/././bar` | `/foo/bar` | 
| `/./foo/bar` | `/foo/bar` | 
| `/foo/%2e/bar` | `/foo/bar` | 400 encoded dot segment
| `/foo/.;/bar` | `/foo/bar` | 400 dot segment with parameter
| `/foo/%2e;/bar` | `/foo/bar` | 400 encoded dot segment
| `/foo/.%2Fbar` | `/foo/.%2Fbar` | 400 encoded /
| `/foo/.%5Cbar` | `/foo/.\bar` | 400 backslash character
| `/foo/bar/.` | `/foo/bar` | 
| `/foo/bar/./` | `/foo/bar/` | 
| `/foo/bar/.;` | `/foo/bar` | 400 dot segment with parameter
| `/foo/bar/./;` | `/foo/bar/` | 
| `/foo/.bar` | `/foo/.bar` | 
| `/foo/../bar` | `/bar` | 
| `/foo/../../bar` | `/../bar` | 400 leading dot-dot-segment
| `/../foo/bar` | `/../foo/bar` | 400 leading dot-dot-segment
| `/foo/%2e%2E/bar` | `/bar` | 400 encoded dot segment
| `/foo/%2e%2e/%2E%2E/bar` | `/../bar` | 400 leading dot-dot-segment & encoded dot segment
| `/foo/./../bar` | `/bar` | 
| `/foo/..;/bar` | `/bar` | 400 dot segment with parameter
| `/foo/%2e%2E;/bar` | `/bar` | 400 encoded dot segment
| `/foo/..%2Fbar` | `/foo/..%2Fbar` | 400 encoded /
| `/foo/..%5Cbar` | `/foo/..\bar` | 400 backslash character
| `/foo/bar/..` | `/foo` | 
| `/foo/bar/../` | `/foo/` | 
| `/foo/bar/..;` | `/foo` | 400 dot segment with parameter
| `/foo/bar/../;` | `/foo/` | 
| `/foo/..bar` | `/foo/..bar` | 
| `/foo/pass:[...]/bar` | `/foo/pass:[...]/bar` |
| `/foo//bar` | `/foo/bar` | 
| `//foo//bar//` | `/foo/bar/` | 
| `/;/foo;/;/bar/;/;` | `/foo/bar/` | 400 empty segment with parameters
| `/foo//../bar` | `/bar` | 
| `/foo/;/../bar` | `/bar` | 400 empty segment with parameters
| `/foo%E2%82%ACbar` | `/foo€bar` | 
| `/foo%20bar` | `/foo bar` | 
| `/foo%E2%82` | `/foo%E2%82` | 400 decode error
| `/foo%E2%82bar` | `/foo%E2%82bar` | 400 decode error
| `/foo%-1/bar` | `/foo%-1/bar` | 400 decode error
| `/foo%XX/bar` | `/foo%XX/bar` | 400 decode error
| `/foo%/bar` | `/foo%/bar` | 400 decode error
| `/foo/bar%0` | `/foo/bar%0` | 400 decode error
| `/good%20/bad%/%20mix%` | `/good /bad%/%20mix%` | 400 decode error
| `/foo/bar?q` | `/foo/bar` | 
| `/foo/bar#f` | `/foo/bar` | 400 fragment
| `/foo/bar?q#f` | `/foo/bar` | 400 fragment
| `/foo/bar/?q` | `/foo/bar/` | 
| `/foo/bar/#f` | `/foo/bar/` | 400 fragment
| `/foo/bar/?q#f` | `/foo/bar/` | 400 fragment
| `/foo/bar;?q` | `/foo/bar` | 
| `/foo/bar;#f` | `/foo/bar` | 400 fragment
| `/foo/bar;?q#f` | `/foo/bar` | 400 fragment
| `/` | `/` | 
| `//` | `/` | 
| `/;/` | `/` | 400 empty segment with parameters
| `/.` | `/` | 
| `/..` | `/..` | 400 leading dot-dot-segment
| `/./` | `/` | 
| `/../` | `/../` | 400 leading dot-dot-segment
| `foo/bar/` | `/foo/bar/` | 400 must start with /
| `./foo/bar/` | `/foo/bar/` | 400 must start with /
| `%2e/foo/bar/` | `/foo/bar/` | 400 must start with / & encoded dot segment
| `../foo/bar/` | `/../foo/bar/` | 400 must start with / & leading dot-dot-segment
| `.%2e/foo/bar/` | `/../foo/bar/` | 400 must start with / & leading dot-dot-segment & encoded dot segment
| `;/foo/bar/` | `/foo/bar/` | 400 must start with / & empty segment with parameters
| `/#f` | `/` | 400 fragment
| `#f` | `/` | 400 fragment & must start with /
| `/?q` | `/` | 
| `?q` | `/` | 400 must start with /

|===


=== Request Path Elements

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:

* *Context Path:* The path prefix associated
with the `ServletContext` that this servlet is a part of. If this
context is the “default” context rooted at the base of the web server’s
URL name space, this path will be an empty string. Otherwise, if the
context is not rooted at the root of the server’s name space, the path
starts with a `"/"` character but does not end with a `"/"` character.

* *Servlet Path:* The path section that
directly corresponds to the mapping which activated this request. This
path starts with a `"/"` character except in the case where the
request is matched with the `"/*"` or `""` pattern, in which case it is
an empty string.

* *PathInfo:* The part of the request path that
is not part of the Context Path or the Servlet Path. It is either null
if there is no extra path, or is a string with a leading `"/"`.

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

* `getContextPath`

* `getServletPath`

* `getPathInfo`

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:

 requestURI = contextPath + servletPath + pathInfo

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

.Example Context Configuration
[caption="Table 3-1 ", cols="2"]
[%breakable]
|===
| Context Path
| `/catalog`

| Servlet Mapping
| Pattern: `/lawn/*` +
Servlet: `LawnServlet`

| Servlet Mapping
| Pattern: `/garden/*` +
Servlet: `GardenServlet`

| Servlet Mapping
| Pattern: `*.jsp` +
Servlet: `JSPServlet`
|===


The following behavior is observed:

.Observed Path Element Behavior
[caption="Table 3-2  ", cols="2", options="header"]
[%breakable]
|===
|Request Path
|Path Elements

|`/catalog/lawn/index.html`
|ContextPath: `/catalog` +
ServletPath: `/lawn` +
PathInfo: `/index.html`

|`/catalog/garden/implements/`
|ContextPath: `/catalog` +
ServletPath: `/garden` +
PathInfo: `/implements/`

|`/catalog/help/feedback.jsp`
|ContextPath: `/catalog` +
ServletPath: `/help/feedback.jsp` +
PathInfo: `null`
|===

=== Path Translation Methods

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:

* `ServletContext.getRealPath`

* `HttpServletRequest.getPathTranslated`

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 IO

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
<<Asynchronous processing>>), and
upgrade processing (as defined in <<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:

.ReadListener
`onDataAvailable()`::
The `onDataAvailable`
method is invoked on the `ReadListener` when data is available to read
from the incoming request stream. The container will invoke the method
the first time when data is available to read. The container will
subsequently invoke the `onDataAvailable` method if and only if the
`isReady` method on `ServletInputStream`, described below, has been
called and returned a value of `false` and data has subsequently become
available to read.

`onAllDataRead()`::
The `onAllDataRead`
method is invoked when all the data for the `ServletRequest` for which the
listener was registered has been read.

`onError(Throwable t)`::
The `onError`
method is invoked if there is any error or exception that occurs while
processing the request.

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:

.ServletInputStream
`boolean isFinished()`::
The `isFinished`
method returns `true` when all the data for the request associated with
the `ServletInputStream` has been read. Otherwise it returns `false`.

`boolean isReady()`::
The `isReady` method
returns `true` if data can be read without blocking. If no data can be
read without blocking it returns `false`. If `isReady` returns `false` it
is illegal to call the read method and an `IllegalStateException` MUST
be thrown.

`void setReadListener(ReadListener listener)`::
Sets the `ReadListener` defined above to be invoked to
read data in a non-blocking fashion. Once a listener is associated with
the `ServletInputStream`, the container invokes the methods on
the `ReadListener` when data is available to read, all the data has been
read or if there was an error processing the request. Registering a
`ReadListener` will start non-blocking IO. It is illegal to switch to
the traditional blocking IO at that point and an `IllegalStateException`
MUST be thrown. A subsequent call to `setReadListener` in the scope of
the current request is illegal and an `IllegalStateException` MUST be
thrown.

=== HTTP/2 Server Push

Server push was intended to improve the perceived performance of the web
browsing experience. The basis for this was the idea 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 require `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`.

Server push has not been widely adopted and the leading browsers have removed
support for server push. This is because the server does not have visibility
into either the client cache or any intermediate caches that may be present and,
as such, is unable to identify which resources need to be pushed and which the
client already has. Server push has essentially been replaced by RFC 8297 (Early
Hints).

Server push support was added in version 4 of this specification. As of version
6.1 of this specification, containers are not required to support server push
and may always return `null` from
`jakarta.servlet.http.HttpServletRequest.newPushBuilder()`

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>>.

Servlet {spec-version} containers may support server push as specified in the
HTTP/2 specification section “Server Push”. Containers may 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.

=== Cookies

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. The only information that
the client sends back as part of a cookie is the cookie name and the cookie
value. 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.

=== SSL Attributes

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:

.Protocol Attributes
[caption="Table 3-3  "]
[%breakable]
[cols="30,50,20", options="header"]
|===
|Attribute
|Attribute Name
|Java Type

|protocol e.g. TLSv1.3
|`jakarta.servlet.request.secure_protocol`
|`String`

|cipher suite
|`jakarta.servlet.request.cipher_suite`
|`String`

|bit size of the algorithm
|`jakarta.servlet.request.key_size`
|`Integer`

|SSL session id
|`jakarta.servlet.request.ssl_session_id`
|`String`
|===

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.

=== Internationalization

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:

* `getLocale`

* `getLocales`

The `getLocale` method will return the
preferred locale for which the client wants to accept content. See
section 12.5.4 of RFC 9110 (HTTP Semantics) 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.

=== Request Data Encoding

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.

=== Lifetime of the Request Object

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.


== Servlet Context

=== Introduction to the ServletContext Interface

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`.

=== Scope of a ServletContext Interface

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.

=== Initialization Parameters

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:

* `getInitParameter`

* `getInitParameterNames`

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.

=== Configuration Methods

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.

==== Programmatically Adding and Configuring Servlets

The ability to programmatically add a servlet
to a context is useful for framework developers. For example a framework
could declare a controller servlet using this method. The return value
of this method is a `ServletRegistration` or a
`ServletRegistration.Dynamic` object which further allows the setup
of the other parameters of the servlet like `init-param`, `url-mappings`
etc. There are three overloaded versions of the method as described
below.

===== addServlet(String servletName, String className)

This method allows the application to declare
a servlet programmatically. It adds a servlet with the given name, and
class name to the servlet context.

===== addServlet(String servletName, Servlet servlet)

This method allows the application to declare
a servlet programmatically. It adds a servlet with the given name, and
servlet instance to the servlet context.

===== addServlet(String servletName, Class <? extends Servlet> servletClass)

This method allows the application to declare
a servlet programmatically. It adds a servlet with the given name, and
an instance of the servlet class to the servlet context.

===== addJspFile(String servletName, String jspfile)

This method allows the application to declare
a jsp programmatically. It adds the jsp with the given name, and an
instance of the servlet class corresponding to the jsp file to the
servlet context.

===== <T extends Servlet> T createServlet(Class<T> clazz)

This method instantiates the given `Servlet`
class. The method must support all the annotations applicable to
servlets except `@WebServlet`. The returned `Servlet` instance may be
further customized before it is registered with the `ServletContext` via
a call to `addServlet(String, Servlet)` as defined above. The given
`Servlet` class must define a zero argument constructor, which is used
to instantiate it.

===== ServletRegistration getServletRegistration(String servletName)

This method returns the `ServletRegistration`
corresponding to the servlet with the given `name`, or `null` if no
`ServletRegistration` exists under that `name`. An
`UnsupportedOperationException` is thrown if the `ServletContext` was
passed to the `contextInitialized` method of a `ServletContextListener`
that was neither declared in the `web.xml` or `web-fragment.xml`, nor
annotated with `jakarta.servlet.annotation.WebListener`.

===== Map<String, ? extends ServletRegistration> getServletRegistrations()

This method returns a map of
`ServletRegistration` objects, keyed by name corresponding to all servlets
registered with the `ServletContext`. If there are no servlets registered
with the `ServletContext` an empty map is returned. The returned `Map`
includes the `ServletRegistration` objects corresponding to all declared
and annotated servlets, as well as the `ServletRegistration` objects
corresponding to all servlets that have been added via one of the
`addServlet` and `addJspFile` methods. Any changes to the returned `Map`
MUST not affect the `ServletContext`. An
`UnsupportedOperationException` is thrown if the `ServletContext` was
passed to the `contextInitialized` method of a `ServletContextListener`
that was neither declared in the `web.xml` or `web-fragment.xml`, nor
annotated with `jakarta.servlet.annotation.WebListener`.

==== Programmatically Adding and Configuring Filters

===== addFilter(String filterName, String className)

This method allows the application to declare
a filter programmatically. It adds a filter with the given name, and
class name to the web application.

===== addFilter(String filterName, Filter filter)

This method allows the application to declare
a filter programmatically. It adds a filter with the given name, and
filter instance to the web application.

===== addFilter(String filterName, Class <? extends Filter> filterClass)

This method allows the application to declare
a filter programmatically. It adds a filter with the given name, and
an instance of the filter class to the web application.

===== <T extends Filter> T createFilter(Class<T> clazz)

This method instantiates the given `Filter`
class. The method must support all the annotations applicable to
filters. The returned `Filter` instance may be further customized before
it is registered with the `ServletContext` via a call to
`addFilter(String, Filter)` as defined above. The given `Filter` class
must define a zero argument constructor, which is used to instantiate
it.

===== FilterRegistration getFilterRegistration(String filterName)

This method returns the `FilterRegistration`
corresponding to the filter with the given `name`, or `null` if no
`FilterRegistration` exists under that `name`. An
`UnsupportedOperationException` is thrown if the `ServletContext` was
passed to the `contextInitialized` method of a `ServletContextListener`
that was neither declared in the `web.xml` or `web-fragment.xml`, nor
annotated with `jakarta.servlet.annotation.WebListener`.

===== Map<String, ? extends FilterRegistration> getFilterRegistrations()

This method returns a map of
`FilterRegistration` objects, keyed by name corresponding to all filters
registered with the `ServletContext`. If there are no filters
registered with the `ServletContext` an empty `Map` is returned. The
returned `Map` includes the `FilterRegistration` objects corresponding
to all declared and annotated filters, as well as the
`FilterRegistration` objects corresponding to all filters that have been
added via one of the `addFilter` methods. Any changes to the returned
`Map` MUST not affect the `ServletContext`. An
`UnsupportedOperationException` is thrown if the `ServletContext` was
passed to the `contextInitialized` method of a `ServletContextListener`
that was neither declared in the `web.xml` or `web-fragment.xml`, nor
annotated with `jakarta.servlet.annotation.WebListener`.

==== Programmatically Adding and Configuring Listeners

===== void addListener(String className)

Add the listener with the given class name to
the `ServletContext`. The class with the given name will be loaded
using the classloader associated with the application represented by the
`ServletContext`, and MUST implement one or more of the following
interfaces:


* `jakarta.servlet.ServletContextAttributeListener`

* `jakarta.servlet.ServletRequestListener`

* `jakarta.servlet.ServletRequestAttributeListener`

* `jakarta.servlet.http.HttpSessionListener`

* `jakarta.servlet.http.HttpSessionAttributeListener`

* `jakarta.servlet.http.HttpSessionIdListener`

If the `ServletContext` was passed to the
`ServletContainerInitializer`’s `onStartup` method, then the class with
the given name MAY also implement `jakarta.servlet.ServletContextListener`
in addition to the interfaces listed above. As part of this method call,
the container MUST load the class with the specified class name to
ensure that it implements one of the required interfaces. If the class
with the given name implements a listener interface whose invocation
order corresponds to the declaration order, that is, if it implements
`jakarta.servlet.ServletRequestListener`,
`jakarta.servlet.ServletContextListener` or
`jakarta.servlet.http.HttpSessionListener` then the new listener will be
added to the end of the ordered list of listeners of that interface.

===== <T extends EventListener> void addListener(T t)

Add the given listener to the
`ServletContext`. The given listener MUST be an instance of one or more
of the following interfaces:

* `jakarta.servlet.ServletContextAttributeListener`

* `jakarta.servlet.ServletRequestListener`

* `jakarta.servlet.ServletRequestAttributeListener`

* `jakarta.servlet.http.HttpSessionListener`

* `jakarta.servlet.http.HttpSessionAttributeListener`

* `jakarta.servlet.http.HttpSessionIdListener`

If the `ServletContext` was passed to the
`ServletContainerInitializer`’s `onStartup` method, then the given
listener MAY also be an instance of
`jakarta.servlet.ServletContextListener` in addition to the interfaces
listed above. If the given listener is an instance of a listener
interface whose invocation order corresponds to the declaration order,
that is, if it implements `jakarta.servlet.ServletRequestListener`,
`jakarta.servlet.ServletContextListener` or
`jakarta.servlet.http.HttpSessionListener`, then the new listener will be
added to the end of the ordered list of listeners of that interface.

===== void addListener(Class <? extends EventListener> listenerClass)

Add the listener of the given class type to
the `ServletContext`. The given listener class MUST implement one or
more of the following interfaces:

* `jakarta.servlet.ServletContextAttributeListener`

* `jakarta.servlet.ServletRequestListener`

* `jakarta.servlet.ServletRequestAttributeListener`

* `jakarta.servlet.http.HttpSessionListener`

* `jakarta.servlet.http.HttpSessionAttributeListener`

* `jakarta.servlet.http.HttpSessionIdListener`

If the `ServletContext` was passed to the
`ServletContainerInitializer`’s `onStartup` method, then the given
listener class MAY also implement `jakarta.servlet.ServletContextListener`
in addition to the interfaces listed above. If the given listener class
implements a listener interface whose invocation order corresponds to
the declaration order, that is, if it implements
`jakarta.servlet.ServletRequestListener`,
`jakarta.servlet.ServletContextListener` or
`jakarta.servlet.http.HttpSessionListener,` then the new listener will be
added to the end of the ordered list of listeners of that interface.

===== <T extends EventListener> void createListener(Class<T> clazz)

This method instantiates the given
EventListener class. The specified EventListener class MUST implement at
least one of the following interfaces:

* `jakarta.servlet.ServletContextAttributeListener`

* `jakarta.servlet.ServletRequestListener`

* `jakarta.servlet.ServletRequestAttributeListener`

* `jakarta.servlet.http.HttpSessionListener`

* `jakarta.servlet.http.HttpSessionAttributeListener`

* `jakarta.servlet.http.HttpSessionIdListener`

This method MUST support all annotations
applicable to the above listener interfaces as defined by this
specification. The returned EventListener instance may be further
customized before it is registered with the ServletContext via a call to
addListener(T t). The given EventListener class MUST define a zero
argument constructor, which is used to instantiate it.

===== Annotation processing requirements for programmatically added Servlets, Filters and Listeners

When using the programmatic API to add a
servlet or create a servlet, apart from the addServlet that takes an
instance, the following annotations must be introspected in the class in
question and the metadata defined in it MUST be used unless it is
overridden by calls to the API in the `ServletRegistration.Dynamic` /
`ServletRegistration`.

`@ServletSecurity`, `@RunAs`, `@DeclareRoles`, `@MultipartConfig`.

For filters and listeners no annotations need
to be introspected.

Resource injection on all components
(servlets, filters and listeners) added programmatically or created
programmatically, other than the ones added via the methods that takes
an instance, will only be supported when the component is a CDI Managed
Bean. For details please refer to
<<Contexts and Dependency Injection for Jakarta EE Platform Requirements>>.

==== Programmatically Configuring Session Time Out

The following methods of the `ServletContext`
interface allow the web application to access and configure the default
session timeout interval for all sessions created in the given web
application. The specified timeout in `setSessionTimeout` is in minutes.
If the timeout is 0 or less the container ensures the default behavior
of sessions is never to time out.

* `getSessionTimeout()`

* `setSessionTimeout(int timeout)`

==== Programmatically Configuring Character Encoding

The following methods of the `ServletContext`
interface allow the web application to access and configure request and
response character encoding.

* `getRequestCharacterEncoding()`

* `setRequestCharacterEncoding(String encoding)`

* `getResponseCharacterEncoding()`

* `setResponseCharacterEncoding(String encoding)`

If no request character encoding is specified
in deployment descriptor or container specific configuration (for all
web applications in the container), `getRequestCharacterEncoding()`
returns null. If no response character encoding is specified in
deployment descriptor or container specific configuration (for all web
applications in the container), `getResponseCharacterEncoding()` returns
null.

=== Context Attributes

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:

* `setAttribute`

* `getAttribute`

* `getAttributeNames`

* `removeAttribute`

==== Context Attributes in a Distributed Container

Context attributes are local to the JVM in
which they were created. This prevents `ServletContext` attributes from
being a shared memory store in a distributed container. When information
needs to be shared between servlets running in a distributed
environment, the information should be placed into a session (See
<<Sessions>>), stored in a database,
or set in an Jakarta Enterprise Beans component.

=== Resources

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:

* `getResource`

* `getResourceAsStream`

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 footnote:[The Jakarta Server Pages
specification can be found at `https://jakarta.ee/specifications/pages`],
a method call of the form
`getResource("/index.jsp")` would return the JSP source code and not the
processed output. See <<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.

=== Multiple Hosts and Servlet Contexts

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.

=== Reloading Considerations

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 footnote:[An exception is system classes that the servlet may use
in a different class loader.], 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.

==== Temporary Working Directories

A temporary storage directory is required for
each servlet context. Servlet containers must provide a private
temporary directory for each servlet context, and make it available via
the `jakarta.servlet.context.tempdir` context attribute. The objects
associated with the attribute must be of type `java.io.File`.

The requirement recognizes a common
convenience provided in many servlet engine implementations. The
container is not required to maintain the contents of the temporary
directory when the servlet container restarts, but is required to ensure
that the contents of the temporary directory of one servlet context is
not visible to the servlet contexts of other web applications running on
the servlet container.


== The Response


The response object encapsulates all
information to be returned from the server to the client. In the HTTP
protocol, this information is transmitted from the server to the client
either by HTTP headers or the message body of the response.

=== Buffering

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:

* `getBufferSize`

* `setBufferSize`

* `isCommitted`

* `reset`

* `resetBuffer`

* `flushBuffer`

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.

=== Headers

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

* `setHeader`

* `addHeader`

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:

* `setIntHeader`

* `setDateHeader`

* `addIntHeader`

* `addDateHeader`

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 9110, 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.

=== HTTP Trailers

An HTTP trailer is a collection of HTTP headers that comes after the
response body. It is specified
in RFC 9110. 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

Non-blocking IO only works with async request
processing in servlets and filters (as defined in
<<Asynchronous processing>>), and
upgrade processing (as defined in <<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
<<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.

.WriteListener

 `void onWritePossible()`:: When a
`WriteListener` is registered with the `ServletOutputStream`, this
method will be invoked by the container the first time when it is
possible to write data. The container will subsequently invoke the
`onWritePossible` method if and only if the `isReady` method on
`ServletOutputStream`, described below, returns a value of `false` and
a write operation has subsequently become possible.

 `void onError(Throwable t)`:: Invoked when an
error occurs processing the response.

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.

.ServletOutputStream

`boolean isReady()`::
This method returns
`true` if a write to the `ServletOutputStream` will succeed, otherwise
it will return `false`. If this method returns `true`, a write
operation can be performed on the `ServletOutputStream`. If no further
data can be written to the `ServletOutputStream` then this method will
return `false` till the underlying data is flushed at which point the
container will invoke the `onWritePossible` method of the
`WriteListener.` A subsequent call to this method will return `true`.

`void setWriteListener(WriteListener listener)`::
Associates the `WriteListener` with this
`ServletOutputStream` for the container to invoke the callback methods
on the `WriteListener` when it is possible to write data. Registering a
`WriteListener` will start non-blocking IO. It is illegal to switch to
the traditional blocking IO at that point. The use of IO related method
calls after this illegal switch to traditional blocking IO produces
unspecified behavior.

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

=== Convenience Methods

The following convenience methods exist in the
`HttpServletResponse` interface:

* `sendRedirect`

* `sendError`

The `sendRedirect` methods will set the appropriate headers and content body to
redirect the client to a different URL.
It is legal to call these methods with a relative URL path.
The underlying container may provide an option to use the relative URL path as
provided but if no such option is provided it 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 these methods 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`.

=== Internationalization

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.


[source,xml]
----
<locale-encoding-mapping-list>
  <locale-encoding-mapping>
    <locale>ja</locale>
    <encoding>Shift_JIS</encoding>
  </locale-encoding-mapping>
</locale-encoding-mapping-list>
----

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

[source,xml]
----
<response-character-encoding>UTF-8</response-character-encoding>
----

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.

=== Closure of the Response Object

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:

* The termination of the `service` method of the
servlet.

* The amount of content specified in the
`setContentLength` or `setContentLengthLong` method of the response has
been greater than zero and has been written to the response.

* The `sendError` method is called.

* The `sendRedirect` method is called.

* The `complete` method on `AsyncContext` is
called.

=== Lifetime of the Response Object

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.


== Filtering


Filters are Java components that allow on the
fly transformations of payload and header information in both the
request into a resource and the response from a resource.

The Jakarta Servlet API provides a lightweight framework for filtering
active and static content.
It describes how filters are configured in a web application, and
conventions and semantics for their implementation.

API documentation for servlet filters is
provided online. The configuration syntax for filters is given by the
deployment descriptor schema described in <<Deployment Descriptor>>.
The reader should use these sources as
references when reading this chapter.

=== What is a Filter?

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 accessing of a resource before a request
to it is invoked.

* The processing of the request for a resource
before it is invoked.

* The modification of request headers and data
by wrapping the request in customized versions of the request object.

* The modification of response headers and
response data by providing customized versions of the response object.

* The interception of an invocation of a
resource after its call.

* Actions on a servlet, on groups of servlets,
or static content by zero, one, or more filters in a specifiable order.

==== Examples of Filtering Components

* Authentication filters

* Logging and auditing filters

* Image conversion filters

* Data compression filters

* Encryption filters

* Tokenizing filters

* Filters that trigger resource access events

* XSL/T filters that transform XML content

* MIME-type chain filters

* Caching filters

=== Main Concepts

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.

==== Filter Lifecycle

After deployment of the web application, and
before a request causes the container to access a web resource, the
container must locate the list of filters that must be applied to the
web resource as described below. The container must ensure that it has
instantiated a filter of the appropriate class for each filter in the
list, and called its `init(FilterConfig config)` method. The filter may
throw an exception to indicate that it cannot function properly. If the
exception is of type `UnavailableException`, the container may examine
the isPermanent attribute of the exception and may choose to retry the
filter at some later time.

Only one instance per `<filter>` declaration
in the deployment descriptor is instantiated per JVM of the container.
The container provides the filter `config` as declared in the filter’s
deployment descriptor, the reference to the `ServletContext` for the web
application, and the set of initialization parameters.

When the container receives an incoming
request, it takes the first filter instance in the list and calls its
`doFilter` method, passing in the `ServletRequest` and `ServletResponse`
, and a reference to the `FilterChain` object it will use.

The `doFilter` method of a filter will
typically be implemented following this or some subset of the following
pattern:

. The method examines the request’s headers.

. The method may wrap the request object with a
customized implementation of `ServletRequest` or `HttpServletRequest` in
order to modify request headers or data.

. The method may wrap the response object passed
in to its `doFilter` method with a customized implementation of
`ServletResponse` or `HttpServletResponse` to modify response headers or
data.

. The filter may invoke the next entity in the
filter chain. The next entity may be another filter, or if the filter
making the invocation is the last filter configured in the deployment
descriptor for this chain, the next entity is the target web resource.
The invocation of the next entity is effected by calling the `doFilter`
method on the `FilterChain` object, and passing in the request and
response with which it was called or passing in wrapped versions it may
have created.
+
The filter chain’s implementation of the
`doFilter` method, provided by the container, must locate the next
entity in the filter chain and invoke its `doFilter` method, passing in
the appropriate request and response objects.
+
Alternatively, the filter chain can block the
request by not making the call to invoke the next entity, leaving the
filter responsible for filling out the response object.
+
The `service` method is required to run in
the same thread as all filters that apply to the servlet.

. After invocation of the next filter in the
chain, the filter may examine response headers.

. Alternatively, the filter may have thrown an
exception to indicate an error in processing. If the filter throws an
`UnavailableException` during its `doFilter` processing, the container
must not attempt continued processing down the filter chain. It may
choose to retry the whole chain at a later time if the exception is not
marked permanent.

. When the last filter in the chain has been
invoked, the next entity accessed is the target servlet or resource at
the end of the chain.

. Before a filter instance can be removed from
service by the container, the container must first call the `destroy`
method on the filter to enable the filter to release any resources and
perform other cleanup operations.

==== Wrapping Requests and Responses

Central to the notion of filtering is the
concept of wrapping a request or response in order that it can override
behavior to perform a filtering task. In this model, the developer not
only has the ability to override existing methods on the request and
response objects, but to provide new API suited to a particular
filtering task to a filter or target web resource down the chain. For
example, the developer may wish to extend the response object with
higher level output objects than the output stream or the writer, such
as API that allows DOM objects to be written back to the client.

In order to support this style of filter the container must support
the following requirements:

 * When a filter invokes the `doFilter` method on the container’s
filter chain implementation, the container must ensure that
the request and response objects that it
passes to the next entity in the filter chain, or to the target web
resource if the filter was the last in the chain, is the same object
that was passed into the `doFilter` method by the calling filter.
 * When a filter or servlet calls `RequestDispatcher.forward` or
`RequestDispatcher.include`, then the request and response objects
seen by the called filter(s) and/or servlet must either:
be the same wrapper objects that were passed; or wrappers of the
objects that were passed.
 * When `startAsync(ServletRequest, ServletResponse)`
is used to commence an asynchronous cycle then the request and response objects
seen by any filter(s) and/or servlet subsequent to an `AsyncContext.dispatch()`
(or overloaded variant) must either:
be the same wrapper objects that were passed; or wrappers of the
objects that were passed.

==== Filter Environment

A set of initialization parameters can be
associated with a filter using the `<init-param>` element in the
deployment descriptor. The names and values of these parameters are
available to the filter at runtime via the `getInitParameter` and
`getInitParameterNames` methods on the filter’s `FilterConfig` object.
Additionally, the `FilterConfig` affords access to the `ServletContext`
of the web application for the loading of resources, for logging
functionality, and for storage of state in the `ServletContext`’s
attribute list. A filter and the target servlet or resource at the end
of the filter chain must execute in the same invocation thread.

==== Configuration of Filters in a Web Application

A filter is defined either via the
`@WebFilter` annotation as defined in
<<_WebFilter>> of the specification or
in the deployment descriptor using the `<filter>` element. In this
element, the programmer declares the following:

* `filter-name`: used to map the filter to a servlet or URL

* `filter-class`: used by the container to identify the filter type

* `init-param`: initialization parameters for a filter

Optionally, the programmer can specify icons,
a textual description, and a display name for tool manipulation. The
container must instantiate exactly one instance of the Java class
defining the filter per filter declaration in the deployment descriptor.
Hence, two instances of the same filter class will be instantiated by
the container if the developer makes two filter declarations for the
same filter class.

Here is an example of a filter declaration:

[source,xml]
----
<filter>
  <filter-name>Image Filter</filter-name>
  <filter-class>com.example.ImageServlet</filter-class>
</filter>
----

Once a filter has been declared in the
deployment descriptor, the assembler uses the `<filter-mapping>` element
to define servlets and static resources in the web application to which
the filter is to be applied. Filters can be associated with a servlet
using the `<servlet-name>` element. For example, the following code
example maps the `Image Filter` filter to the `ImageServlet` servlet:


[source,xml]
----
<filter-mapping>
  <filter-name>Image Filter</filter-name>
  <servlet-name>ImageServlet</servlet-name>
</filter-mapping>
----

Filters can be associated with groups of
servlets and static content using the `<url-pattern>` style of filter
mapping:

[source,xml]
----
<filter-mapping>
  <filter-name>Logging Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
----

Here the `Logging Filter` is applied to all the
servlets and static content pages in the web application, because every
request URI matches the `/*` URL pattern.

When processing a `<filter-mapping>` element
using the `<url-pattern>` style, the container must determine whether
the `<url-pattern>` matches the request URI using the path mapping rules
defined in <<Mapping Requests to Servlets>>.

The order the container uses in building the
chain of filters to be applied for a particular request URI is as
follows:

. First, the `<url-pattern>` matching filter
mappings in the same order that these elements appear in the deployment
descriptor.

. Next, the `<servlet-name>` matching filter
mappings in the same order that these elements appear in the deployment
descriptor.

If a filter mapping contains both
<servlet-name> and <url-pattern>, the container must expand the filter
mapping into multiple filter mappings (one for each <servlet-name> and
<url-pattern>), preserving the order of the <servlet-name> and
<url-pattern> elements. For example, the following filter mapping:

[source,xml]
----
<filter-mapping>
  <filter-name>Multiple Mappings Filter</filter-name>
  <url-pattern>/foo/*</url-pattern>
  <servlet-name>Servlet1</servlet-name>
  <servlet-name>Servlet2</servlet-name>
  <url-pattern>/bar/*</url-pattern>
</filter-mapping>
----

is equivalent to:

[source,xml]
----
<filter-mapping>
  <filter-name>Multipe Mappings Filter</filter-name>
  <url-pattern>/foo/*</url-pattern>
</filter-mapping>

<filter-mapping>
  <filter-name>Multipe Mappings Filter</filter-name>
  <servlet-name>Servlet1</servlet-name>
</filter-mapping>

<filter-mapping>
  <filter-name>Multipe Mappings Filter</filter-name>
  <servlet-name>Servlet2</servlet-name>
</filter-mapping>

<filter-mapping>
  <filter-name>Multipe Mappings Filter</filter-name>
  <url-pattern>/bar/*</url-pattern>
</filter-mapping>
----

The requirement about the order of the filter
chain means that the container, when receiving an incoming request,
processes the request as follows:

* Identifies the target web resource according
to the rules of <<Specification of Mappings>>.

* If there are filters matched by servlet name
and the web resource has a `<servlet-name>`, the container builds the
chain of filters matching in the order declared in the deployment
descriptor. The last filter in this chain corresponds to the last
`<servlet-name>` matching filter and is the filter that invokes the
target web resource.

* If there are filters using `<url-pattern>`
matching and the `<url-pattern>` matches the request URI according to
the rules of <<Specification of Mappings>>,
the container builds the chain of `<url-pattern>` matched
filters in the same order as declared in the deployment descriptor. The
last filter in this chain is the last `<url-pattern>` matching filter in
the deployment descriptor for this request URI. The last filter in this
chain is the filter that invokes the first filter in the
`<servlet-name>` matching chain, or invokes the target web resource if
there are none.

It is expected that high performance web
containers will cache filter chains so that they do not need to compute
them on a per-request basis.

==== Filters and the RequestDispatcher

The servlet specification provides the ability to configure filters to be
invoked under request dispatcher `forward()` and `include()` calls.

By using the `<dispatcher>` element in the
deployment descriptor, the developer can indicate for a filter-mapping
whether the filter should be applied to requests when:

. The request comes directly from the client.
+
This is indicated by a `<dispatcher>` element
with value `REQUEST`, or by the absence of any `<dispatcher>` elements.

. The request is being processed under a request
dispatcher representing the web component matching the `<url-pattern>`
or `<servlet-name>` using a `forward()` call.
+
This is indicated by a `<dispatcher>` element
with value `FORWARD`.

. The request is being processed under a request
dispatcher representing the web component matching the `<url-pattern>`
or `<servlet-name>` using an `include()` call.
+
This is indicated by a `<dispatcher>` element
with value `INCLUDE`.

. The request is being processed with the error
page mechanism specified in <<Error Handling>> to an error
resource matching the `<url-pattern>`.
+
This is indicated by a `<dispatcher>` element
with the value `ERROR`.

. The request is being processed with the async
context dispatch mechanism specified in
<<Asynchronous processing>> to a web
component using a `dispatch` call.
+
This is indicated by a `<dispatcher>` element
with the value `ASYNC`.

. Or any combination of 1, 2, 3, 4 or 5 above.

For example:

[source,xml]
----
<filter-mapping>
  <filter-name>Logging Filter</filter-name>
  <url-pattern>/products/*</url-pattern>
</filter-mapping>
----

would result in the `Logging Filter` being
invoked by client requests starting `/products/...` but not underneath a
request dispatcher call where the request dispatcher has path commencing
`/products/...`. The following code:

[source,xml]
----
<filter-mapping>
  <filter-name>Logging Filter</filter-name>
  <servlet-name>ProductServlet</servlet-name>
  <dispatcher>INCLUDE</dispatcher>
</filter-mapping>
----

would result in the `Logging Filter` not being
invoked by client requests to the `ProductServlet`, nor underneath a
request dispatcher `forward()` call to the `ProductServlet`, but would
be invoked underneath a request dispatcher `include()` call where the
request dispatcher has a name commencing `ProductServlet`. The
following code:

[source,xml]
----
<filter-mapping>
  <filter-name>Logging Filter</filter-name>
  <url-pattern>/products/*</url-pattern>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>
----

would result in the `Logging Filter` being
invoked by client requests starting `/products/...` and underneath a
request dispatcher `forward()` call where the request dispatcher has
path commencing `/products/...`.

Finally, the following code uses the special servlet name `*`:

[source,xml]
----
<filter-mapping>
  <filter-name>All Dispatch Filter</filter-name>
  <servlet-name>*</servlet-name>
  <dispatcher>FORWARD</dispatcher>
</filter-mapping>
----

This code would result in the `All Dispatch Filter` being invoked on
request dispatcher forward() calls for all
request dispatchers obtained by name or by path.


== Sessions


The Hypertext Transfer Protocol (HTTP) is by
design a stateless protocol. To build effective web applications, it is
imperative that requests from a particular client be associated with
each other. Many strategies for session tracking have evolved over time,
but all are difficult or troublesome for the programmer to use directly.

This specification defines a simple
`HttpSession` interface that allows a servlet container to use any of
several approaches to track a user’s session without involving the
Application Developer in the nuances of any one approach.

=== Session Tracking Mechanisms

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

==== Cookies

Session tracking through HTTP cookies is the
most used session tracking mechanism and is required to be supported by
all servlet containers.

The container sends a cookie to the client.
The client will then return the cookie on each subsequent request to the
server, unambiguously associating the request with a session. The
standard name of the session tracking cookie must be `JSESSIONID`.
Containers may allow the name of the session tracking cookie to be
customized through container specific configuration.

All servlet containers MUST provide an
ability to configure whether or not the container marks the session
tracking cookie as `HttpOnly`. The established configuration must apply
to all contexts for which a context specific configuration has not been
established (see `SessionCookieConfig` javadoc for more details).

If a web application configures a custom name
for its session tracking cookies, the same custom name will also be used
as the name of the URI parameter if the session id is encoded in the URL
(provided that URL rewriting has been enabled).

==== SSL Sessions

Secure Sockets Layer, the encryption
technology used in the HTTPS protocol, has a built-in mechanism allowing
multiple requests from a client to be unambiguously identified as being
part of a session. A servlet container can easily use this data to
define a session.

==== URL Rewriting

URL rewriting is the lowest common denominator
of session tracking. When a client will not accept a cookie, URL
rewriting may be used by the server as the basis for session tracking.
URL rewriting involves adding data, a session ID, to the URL path that
is interpreted by the container to associate the request with a session.

The session ID must be encoded as a path
parameter in the URL string. The name of the parameter must be
`jsessionid`. Here is an example of a URL containing encoded path
information:

 http://www.example.com/catalog/index.html;jsessionid=1234

URL rewriting exposes session identifiers in
logs, bookmarks, referer headers, cached HTML, and the URL bar. URL
rewriting should not be used as a session tracking mechanism where
cookies or SSL sessions are supported and suitable.

==== Session Integrity

Web containers must be able to support the
HTTP session while servicing HTTP requests from clients that do not
support the use of cookies. To fulfill this requirement, web containers
commonly support the URL rewriting mechanism.

=== Creating a Session

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:

* The client does not yet know about the session

* The client chooses not to join a session.

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()`.

=== Session Scope

`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.

`HttpSession` objects obtained from `HttpServletRequest` must not be used
outside the scope of the request from which there are obtained. If it is
necessary to access the `HttpSession` outside of this scope, the
`HttpSession.getAccessor()` method must be used.

=== Binding Attributes into a Session

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.

* `valueBound`

* `valueUnbound`

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.

=== Session Timeouts

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.

=== Last Accessed Times

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.

=== Important Session Semantics

==== Threading Issues

Multiple servlets executing request threads
may have active access to the same session object at the same time. The
container must ensure that manipulation of internal data structures
representing the session attributes is performed in a thread safe
manner. The Application Developer has the responsibility for thread safe access to
the attribute objects themselves. This will protect the attribute
collection inside the `HttpSession` object from concurrent access,
eliminating the opportunity for an application to cause that collection
to become corrupted. Unless explicitly stated elsewhere in the
specification, objects vended from the request or
response must be assumed to be non thread safe. This includes, but is
not limited to the `PrintWriter` returned from
`ServletResponse.getWriter()` and the `OutputStream` returned from
`ServletResponse.getOutputStream()`.

==== Distributed Environments

Within an application marked as distributable,
all requests that are part of a session must be handled by one JVM at a
time. The container must be able to handle all objects placed into
instances of the `HttpSession` class using the `setAttribute` or
`putValue` methods appropriately. The following restrictions are imposed
to meet these conditions:

* The container must accept objects that
implement the `Serializable` interface.

* The container may choose to support storage of
other designated objects in the `HttpSession`, such as references to
Jakarta Enterprise Beans components and transactions.

* Migration of sessions will be handled by
container-specific facilities.

The distributed servlet container must throw
an `IllegalArgumentException` for objects where the container cannot
support the mechanism necessary for migration of the session storing
them.

The distributed servlet container must support
the mechanism necessary for migrating objects that implement
`Serializable`.

These restrictions mean that the Application Developer is
ensured that there are no additional concurrency issues beyond those
encountered in a non-distributed container.

The Container Provider can ensure scalability
and quality of service features like load-balancing and failover by
having the ability to move a session object, and its contents, from any
active node of the distributed system to a different node of the system.

If distributed containers persist or migrate
sessions to provide quality of service features, they are not restricted
to using the native JVM Serialization mechanism for serializing
`HttpSessions` and their attributes. Developers are not guaranteed that
containers will call `readObject` and `writeObject` methods on session
attributes if they implement them, but are guaranteed that the
`Serializable` closure of their attributes will be preserved.

Containers must notify any session attributes
implementing the `HttpSessionActivationListener` during migration of a
session. They must notify listeners of passivation prior to
serialization of a session, and of activation after deserialization of a
session.

Application Developers writing distributed
applications should be aware that since the container may run in more
than one Java virtual machine, the developer cannot depend on static
variables for storing an application state. They should store such
states using an enterprise bean or a database.

==== Client Semantics

Due to the fact that cookies or SSL
certificates are typically controlled by the web browser process and are
not associated with any particular window of the browser, requests from
all windows of a client application to a servlet container might be part
of the same session. For maximum portability, the Application Developer should
always assume that all windows of a client are participating in the same
session.


== Annotations and Pluggability

This chapter describes the use of annotations
and other enhancements to enable pluggability of frameworks and
libraries for use within a web application.

[[_Annotations_and_pluggability]]
=== Annotations and Pluggability

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
<<Assembling_the_descriptor>>, <<Processing Annotations and Fragments>> and
<<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`:

* `HttpConstraint`

* `HttpMethodConstraint`

* `MultipartConfig`

* `ServletSecurity`

* `WebFilter`

* `WebInitParam`

* `WebListener`

* `WebServlet`

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

From `jakarta.annotation`:

* `PostConstruct`

* `PreDestroy`

* `Resource`

* `Resources`

From `jakarta.annotation.security`:

* `DeclareRoles`

* `RunAs`

From `jakarta.annotation.sql`:

* `DataSourceDefinition`

* `DataSourceDefinitions`

From `jakarta.ejb`:

* `EJB`

* `EJBs`

From `jakarta.jms`:

* `JMSConnectionFactoryDefinition`

* `JMSConnectionFactoryDefinitions`

* `JMSDestinationDefinition`

* `JMSDestinationDefinitions`

From `jakarta.mail`:

* `MailSessionDefinition`

* `MailSessionDefinitions`

From `jakarta.persistence`:

* `PersistenceContext`

* `PersistenceContexts`

* `PersistenceUnit`

* `PersistenceUnits`

From `jakarta.resource`:

* `AdministeredObjectDefinition`

* `AdministeredObjectDefinitions`

* `ConnectionFactoryDefinition`

* `ConnectionFactoryDefinitions`

All annotations in the following packages:

* `jakarta.jws`

* `jakarta.jws.soap`

* `jakarta.xml.ws`

* `jakarta.xml.ws.soap`

* `jakarta.xml.ws.spi`

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

==== @WebServlet

This annotation is used to define a `Servlet`
component in a web application. This annotation is specified on a class
and contains metadata about the `Servlet` being declared. The
`urlPatterns` or the `value` attribute on the annotation MUST be
present. All other attributes are optional with default settings (see
javadocs for more details). It is recommended to use `value` when the
only attribute on the annotation is the url pattern and to use the
`urlPatterns` attribute when the other attributes are also used. It is
illegal to have both `value` and `urlPatterns` attribute used together
on the same annotation. The default name of the `Servlet` if not
specified is the fully qualified class name. The annotated servlet MUST
specify at least one url pattern to be deployed. If the same servlet
class is declared in the deployment descriptor under a different name, a
new instance of the servlet MUST be instantiated. If the same servlet
class is added with a different name to the `ServletContext` via the
programmatic API defined in <<Programmatically Adding and Configuring Servlets>>,
the attribute values
declared via the `@WebServlet` annotation MUST be ignored and a new
instance of the servlet with the name specified MUST be created.

Classes annotated with `@WebServlet` class
MUST extend the `jakarta.servlet.http.HttpServlet` class.

Following is an example of how this
annotation would be used.

.@WebServlet Annotation Example
[source,java]
----
@WebServlet("/foo")
public class CalculatorServlet extends HttpServlet{
    ...
}
----

Following is an example of how this
annotation would be used with some more of the attributes specified.


.@WebServlet annotation example using other annotation attributes specified
[source,java]
----
@WebServlet(name="MyServlet", urlPatterns={"/foo", "/bar"})
public class SampleUsingAnnotationAttributes extends HttpServlet{

    public void doGet(HttpServletRequest req, HttpServletResponse res) {
        ...
    }
}
----

[[_WebFilter]]
==== @WebFilter

This annotation is used to define a `Filter`
in a web application. This annotation is specified on a class and
contains metadata about the filter being declared. The default name of
the `Filter` if not specified is the fully qualified class name. The
`urlPatterns` attribute, `servletNames` attribute or the `value`
attribute of the annotation MUST be specified. All other attributes are
optional with default settings (see javadocs for more details). It is
recommended to use `value` when the only attribute on the annotation is
the url pattern and to use the `urlPatterns` attribute when the other
attributes are also used. It is illegal to have both `value` and
`urlPatterns` attribute used together on the same annotation.

Classes annotated with `@WebFilter` MUST
implement `jakarta.servlet.Filter`.

Following is an example of how this
annotation would be used.

.@WebFilter annotation example
[source,java]
----
@WebFilter("/foo")
public class MyFilter implements Filter {

    public void doFilter(HttpServletRequest req, HttpServletResponse res) {
        ...
    }
}
----

==== @WebInitParam

This annotation is used to specify any init
parameters that must be passed to the `Servlet` or the `Filter`. It is
an attribute of the `WebServlet` and `WebFilter` annotation.

==== @WebListener

The `WebListener` annotation is used to
annotate a listener to get events for various operations on the
particular web application context. Classes annotated with
`@WebListener` MUST implement one of the following interfaces:

* `jakarta.servlet.ServletContextListener`

* `jakarta.servlet.ServletContextAttributeListener`

* `jakarta.servlet.ServletRequestListener`

* `jakarta.servlet.ServletRequestAttributeListener`

* `jakarta.servlet.http.HttpSessionListener`

* `jakarta.servlet.http.HttpSessionAttributeListener`

* `jakarta.servlet.http.HttpSessionIdListener`

An example:

[source,java]
----
@WebListener
public class MyListener implements ServletContextListener{

    public void contextInitialized(ServletContextEvent sce) {
        ServletContext sc = sce.getServletContext();
        sc.addServlet("myServlet", "Sample servlet", "foo.bar.MyServlet", null, -1);
        sc.addServletMapping("myServlet", new String[] { "/urlpattern/*" });
    }
}
----

[[_MultipartConfig]]
==== @MultipartConfig

This annotation, when specified on a
`Servlet`, indicates that the request it expects is of type
`multipart/form-data`. The `HttpServletRequest` object of the
corresponding servlet MUST make available the mime attachments via the
`getParts` and `getPart` methods to iterate over the various mime
attachments. The `location` attribute of the
`jakarta.servlet.annotation.MultipartConfig` and the `<location>` element
of the `<multipart-config>` is interpreted as an absolute path and
defaults to the value of the `jakarta.servlet.context.tempdir`. If a
relative path is specified, it will be relative to the `tempdir`
location. The test for absolute path vs relative path MUST be done via
`java.io.File.isAbsolute`.

==== Other Annotations / Conventions

In addition to these annotations all the
annotations defined in <<Annotations and Resource Injection>> will continue
to work in the context of these new annotations.

By default all applications will have
`index.htm[l]` and `index.jsp` in the `welcome-file-list`. The
descriptor may to be used to override these default settings.

The order in which the listeners, servlets
are loaded from the various framework jars / classes in the
`WEB-INF/classes` or `WEB-INF/lib` is unspecified when using
annotations. If ordering is important then look at the section for
modularity of web.xml and ordering of `web.xml` and `web-fragment.xml`
below. The order can be specified in the deployment descriptor only.

=== Pluggability

==== Modularity of web.xml

Using the annotations defined above makes
the use of web.xml optional. However for overriding either the default
values or the values set via annotations, the deployment descriptor is
used. As before, if the `metadata-complete` element is set to `true` in
the `web.xml` descriptor, annotations that specify deployment
information present in the class files and web-fragments bundled in jars
will not be processed. It implies that all the metadata for the
application is specified via the `web.xml` descriptor.

For better pluggability and less
configuration for developers, we introduce the notion of web module
deployment descriptor fragments (web fragment). A web fragment is a part
or all of the `web.xml` that can be specified and included in a library
or framework jar's `META-INF` directory. A plain old jar file in the
WEB-INF/lib directory with no web-fragment.xml is also considered a
fragment. Any annotations specified in it will be processed according to
the rules defined in 8.2.3. The container will pick up and use the
configuration as per the rules defined below.

A web fragment is a logical partitioning of
the web application in such a way that the frameworks being used within
the web application can define all the artifacts without asking
developers to edit or add information in the web.xml. It can include
almost all the same elements that the web.xml descriptor uses. However
the top level element for the descriptor MUST be web-fragment and the
corresponding descriptor file MUST be called web-fragment.xml. The
ordering related elements also differ between the web-fragment.xml and
web.xml See the corresponding schema for web-fragments in the deployment
descriptor section in Chapter 14.

If a framework is packaged as a jar file and
has metadata information in the form of deployment descriptor then the
`web-fragment.xml` descriptor must be in the `META-INF/` directory of
the jar file.

If a framework wants its
`META-INF/web-fragment.xml` honored in such a way that it augments a web
application's `web.xml`, the framework must be bundled within the web
application's `WEB-INF/lib` directory. In order for any other types of
resources (e.g., class files) of the framework to be made available to a
web application, it is sufficient for the framework to be present
anywhere in the classloader delegation chain of the web application. In
other words, only JAR files bundled in a web application's `WEB-INF/lib`
directory, but not those higher up in the class loading delegation
chain, need to be scanned for `web-fragment.xml`.

During deployment the container is
responsible for scanning the location specified above and discovering
the `web-fragment.xml` files and processing them. The requirements about name
uniqueness that exist currently for a single web.xml also apply to the
union of a web.xml and all applicable web-fragment.xml files.

An example of what a library or framework can
include is shown below


[source,xml]
----
<web-fragment>

  <servlet>
    <servlet-name>welcome</servlet-name>
    <servlet-class>com.example.WelcomeServlet</servlet-class>
  </servlet>

  <listener>
    <listener-class>com.example.RequestListener</listener-class>
  </listener>

</web-fragment>
----


The above web-fragment.xml would be included
in the META-INF/ directory of the framework’s jar file. The order in
which configuration from web-fragment.xml and annotations should be
applied is undefined. If ordering is an important aspect for a
particular application please see rules defined below on how to achieve
the order desired.

==== Ordering of web.xml and web-fragment.xml

Since the specification allows the
application configuration resources to be composed of multiple
configuration files (`web.xml` and `web-fragment.xml`), discovered and
loaded from several different places in the application, the question of
ordering must be addressed. This section specifies how configuration
resource authors may declare the ordering requirements of their
artifacts.

A `web-fragment.xml` may have a top level
`<name>` element of type `jakartaee:java-identifierType`. There can only
be one `<name>` element in a `web-fragment.xml`. If a `<name>` element
is present, it must be considered for the ordering of artifacts (unless
the duplicate name exception applies, as described below).

Two cases must be considered to allow
application configuration resources to express their ordering
preferences.

. Absolute ordering: an
`<absolute-ordering>` element in the `web.xml`. There can only be one
`<absolute-ordering>` element in a `web.xml`.

.. In this case, ordering preferences that
would have been handled by case 2 below must be ignored.

.. The `web.xml` and WEB-INF/classes MUST be
processed before any of the web-fragments listed in the
`absolute-ordering` element.

.. Any `<name>` element direct children of the
`<absolute-ordering>` MUST be interpreted as indicating the absolute
ordering in which those named web-fragments, which may or may not be
present, must be processed.

.. The `<absolute-ordering>`
element may contain zero or one `<others/>` element. The required action
for this element is described below. If the `<absolute-ordering>`
element does not contain an `<others/>` element, any web-fragment not
specifically mentioned within `<name/>` elements MUST be ignored.
Excluded jars are not scanned for annotated servlets, filters or
listeners. However, if a servlet, filter or listener from an excluded
jar is listed in `web.xml` or a non-excluded `web-fragment.xml`, then
it's annotations will apply unless otherwise excluded by
`metadata-complete`. `ServletContextListeners` discovered in TLD files
of excluded jars are not able to configure filters and servlets using
the programmatic APIs. Any attempt to do so will result in an
`IllegalStateException`. If a discovered `ServletContainerInitializer`
is loaded from an excluded jar, it will be ignored. Irrespective of the
setting of `metadata-complete`, jars excluded by `<absolute-ordering>`
elements are not scanned for classes to be handled by any
`ServletContainerInitializer`.

.. Duplicate name exception: if, when traversing
the children of `<absolute-ordering>`, multiple children with the same
`<name>` element are encountered, only the first such occurrence must be
considered.

. Relative ordering: an `<ordering>` element
within the `web-fragment.xml`. There can only be one `<ordering>`
element in a `web-fragment.xml`.

.. A `web-fragment.xml` may have an `<ordering>`
element. If so, this element must contain zero or one `<before>` element
and zero or one `<after>` element. The meaning of these elements is
explained below.

.. The `web.xml` and WEB-INF/classes MUST be
processed before any of the web-fragments listed in the `ordering`
element.

.. Duplicate name exception: if, when traversing
the web-fragments, multiple members with the same `<name>` element are
encountered, the application must log an informative error message
including information to help fix the problem, and must fail to deploy.
For example, one way to fix this problem is for the user to use absolute
ordering, in which case relative ordering is ignored.

.. Consider this abbreviated but illustrative
example. 3 web-fragments: `MyFragment1`, `MyFragment2` and
`MyFragment3` are part of the application that also includes a `web.xml`
+
--
.web-fragment.xml
[source,xml]
----
<web-fragment>
  <name>MyFragment1</name>
  <ordering>
    <after>
      <name>MyFragment2</name>
    </after>
  </ordering>
  ...
</web-fragment>
----

.web-fragment.xml
[source,xml]
----
<web-fragment>
  <name>MyFragment2</name>
  ...
</web-fragment>
----

.web-fragment.xml
[source,xml]
----
<web-fragment>
  <name>MyFragment3</name>
  <ordering>
    <before>
      <others/>
    </before>
  </ordering>
  ...
</web-fragment>
----

.web.xml
[source,xml]
----
<web-app>
  ...
</web-app>
----

In this example the processing order will be:

. `web.xml`

. `MyFragment3`

. `MyFragment2`

. `MyFragment1`

--

The preceding example illustrates some, but
not all, of the following principles.

* `<before>` means the document must be
ordered before the document with the name matching what is specified
within the nested `<name>` element.

* `<after>` means the document must be ordered
after the document with the name matching what is specified within the
nested `<name>` element.

* There is a special element `<others/>` which
may be included zero or one time within the `<before>` or `<after>`
element, or zero or one time directly within the `<absolute-ordering>`
element. The `<others/>` element must be handled as follows.

** If the `<before>` element contains a nested
`<others/>`, the document will be moved to the beginning of the list of
sorted documents. If there are multiple documents stating
`<before><others/>`, they will all be at the beginning of the list of
sorted documents, but the ordering within the group of such documents is
unspecified.

** If the `<after>` element contains a nested
`<others/>`, the document will be moved to the end of the list of
sorted documents. If there are multiple documents requiring
`<after><others/>`, they will all be at the end of the list of sorted
documents, but the ordering within the group of such documents is
unspecified.

** Within a `<before>` or `<after>` element, if
an `<others/>` element is present, but is not the only `<name>` element
within its parent element, the other elements within that parent must be
considered in the ordering process.

** If the `<others/>` element appears directly
within the `<absolute-ordering>` element, the runtime must ensure that
any web-fragments not explicitly named in the `<absolute-ordering>`
section are included at that point in the processing order.

* If a `web-fragment.xml` file does not have an
`<ordering>` or the `web.xml` does not have an `<absolute-ordering>`
element the artifacts are assumed to not have any ordering dependency.

* If the runtime discovers circular references,
an informative message must be logged, and the application must fail to
deploy. Again, one course of action the user may take is to use absolute
ordering in the `web.xml`.

* The previous example can be extended to
illustrate the case when the `web.xml` contains an ordering section.
+
--

.web.xml
[source,xml]
----
<web-app>
  <absolute-ordering>
    <name>MyFragment3</name>
    <name>MyFragment2</name>
  </absolute-ordering>
  ...
</web-app>
----

In this example, the ordering for the various
elements will be:

. `web.xml`

. `MyFragment3`

. `MyFragment2`

--

Some additional example scenarios are
included below. All of these apply to relative ordering and not absolute
ordering.

.Example 1
--

.Document A:
[source,xml]
----
<after>
  <others/>
  <name>C</name>
</after>
----

.Document B:
[source,xml]
----
<before>
  <others/>
</before>
----

.Document C:
[source,xml]
----
<after>
  <others/>
</after>
----

.Document D:
no ordering

.Document E:
no ordering

.Document F:
[source,xml]
----
<before>
  <others/>
  <name>B</name>
</before>
----

Resulting parse order:

 web.xml, F, B, D, E, C, A.

--


.Example 2
--

.Document <no id>:
[source,xml]
----
<after>
  <others/>
</after>
<before>
  <name>C</name>
</before>
----

.Document B:
[source,xml]
----
<before>
  <others/>
</before>
----

.Document C:
no ordering

.Document D:
[source,xml]
----
<after>
  <others/>
</after>
----

.Document E:
[source,xml]
----
<before>
  <others/>
</before>
----

.Document F:
no ordering

Resulting parse order can be one of the
following:

* B, E, F, <no id>, C, D
* B, E, F, <no id>, D, C
* E, B, F, <no id>, C, D
* E, B, F, <no id>, D, C
* E, B, F, D, <no id>, C
* B, E, F, D, <no id>, C

--

.Example 3
--

.Document A:
[source,xml]
----
<after>
  <name>B</name>
</after>
----

.Document B:
no ordering

.Document C:
[source,xml]
----
<before>
  <others/>
</before>
----

.Document D:
no ordering


Resulting parse order can be one of the
following:

* C, B, D, A
* C, D, B, A
* C, B, A, D

--

[[Assembling_the_descriptor]]
==== Assembling the Descriptor from web.xml, web-fragment.xml and Annotations

If the order in which the listeners,
servlets, filters are invoked is important to an application then a
deployment descriptor must be used. Also, if necessary, the ordering
element defined above can be used. As described above, when using
annotations to define the listeners, servlets and filters, the order in
which they are invoked is unspecified. Below are a set of rules that
apply for assembling the final deployment descriptor for the
application:

. The order for listeners, servlets, filters if
relevant must be specified in either the `web-fragment.xml` or the
`web.xml`.

. The ordering will be based on the order in
which they are defined in the descriptor and on the `absolute-ordering`
element in the `web.xml` or an `ordering` element in the
`web-fragment.xml`, if present.

.. Filters that match a request are chained in
the order in which they are declared in the `web.xml`.

.. Servlets are initialized either lazily at
request processing time or eagerly during deployment. In the latter
case, they are initialized in the order indicated by their
`load-on-startup` elements.

.. The listeners are invoked
in the order in which they are declared in the `web.xml` as specified
below:

... Implementations of
`jakarta.servlet.ServletContextListener` are invoked at their
`contextInitialized` method in the order in which they have been
declared, and at their `contextDestroyed` method in reverse order.

... Implementations of
`jakarta.servlet.ServletRequestListener` are invoked at their
`requestInitialized` method in the order in which they have been
declared, and at their `requestDestroyed` method in reverse order.

... Implementations of
`jakarta.servlet.http.HttpSessionListener` are invoked at their
`sessionCreated` method in the order in which they have been declared,
and at their `sessionDestroyed` method in reverse order.

... The methods of implementation of
`jakarta.servlet.ServletContextAttributeListener`,
`jakarta.servlet.ServletRequestAttributeListener` and
`jakarta.servlet.HttpSessionAttributeListener` are invoked in the order in
which they are declared when corresponding events are fired.

. If a servlet is disabled using the `enabled`
element introduced in the `web.xml` then the servlet will not be
available at the `url-pattern` specified for the servlet.

. The `web.xml` of the web application has the
highest precedence when resolving conflicts between the `web.xml`,
`web-fragment.xml` and annotations.

. If `metadata-complete` is not specified in
the descriptors, or is set to `false` in the deployment descriptor, then
the effective metadata for the application is derived by combining the
metadata present in the annotations and the descriptors. The rules for
merging are specified below:

.. Configuration settings in web fragments are
used to augment those specified in the main web.xml in such a way as if
they had been specified in the same web.xml.

.. The order in which configuration
settings of web fragments are added to those in the main web.xml is as
specified above in <<Ordering of web.xml and web-fragment.xml>>

.. The `metadata-complete` attribute when set to
`true` in the main `web.xml`, is considered complete and scanning of
annotations and fragments will not occur at deployment time. The
`absolute-ordering` and `ordering` elements will be ignored if present.
When set to `true` on a fragment, the `metadata-complete` attribute
applies only to scanning of annotations in that particular jar.

.. Web fragments are merged into the main
`web.xml` unless the `metadata-complete` is set to `true`. The merging
takes place after annotation processing on the corresponding fragment.

.. The following are considered configuration
conflicts when augmenting a `web.xml` with web fragments:

... Multiple `<init-param>` elements with the
same `<param-name>` but different `<param-value>`

... Multiple `<mime-mapping>` elements with the
same `<extension>` but different `<mime-type>`

.. The above configuration conflicts are
resolved as follows:

... Configuration conflicts between the main
`web.xml` and a web fragment are resolved such that the configuration in
the `web.xml` takes precedence.

... Configuration conflicts between two web
fragments, where the element at the center of the conflict is not
present in the main `web.xml`, will result in an error. An informative
message must be logged, and the application must fail to deploy.

.. After the above conflicts have been resolved,
these additional rules are applied

... Elements that may be declared any number of
times are additive across the `web-fragments` in the resulting `web.xml`.
For example, `<context-param>` elements with different `<param-name>`
are additive.

... Elements that may be declared any number of
times, if specified in the `web.xml` overrides the values specified in
the `web-fragments` with the same name.

... If an element with a minimum occurrence of
zero, and a maximum occurrence of one, is present in a web fragment, and
missing in the main `web.xml`, the main `web.xml` inherits the setting
from the web fragment. If the element is present in both the main
`web.xml` and the web fragment, the configuration setting in the main
`web.xml` takes precedence. For example, if both the main `web.xml` and
a web fragment declare the same servlet, and the servlet declaration in
the web fragment specifies a `<load-on-startup>` element, whereas the
one in the main `web.xml` does not, then the `<load-on-startup>` element
from the web fragment will be used in the merged `web.xml`.

... It is considered an error if an element with
a minimum occurrence of zero, and a maximum occurrence of one, is
specified differently in two web fragments, while absent from the main
`web.xml`. For example, if two web fragments declare the same servlet,
but with different `<load-on-startup>` elements, and the same servlet is
also declared in the main `web.xml`, but without any
`<load-on-startup>`, then an error must be reported.

... `<welcome-file>` declarations are additive.

... `<servlet-mapping>` elements with the same
`<servlet-name>` are additive across `web-fragments`.
`<servlet-mapping>` specified in the `web.xml` overrides values
specified in the `web-fragments` with the same `<servlet-name>`.

... `<filter-mapping>` elements with the same
`<filter-name>` are additive across `web-fragments`. `<filter-mapping>`
specified in the `web.xml` overrides values specified in the
`web-fragments` with the same `<filter-name>`.

... Multiple `<listener>` elements with the same
`<listener-class>` are treated as a single `<listener>` declaration

... The `web.xml` resulting from the merge is
considered `<distributable>` only if the `web.xml` and all the web
fragments are marked as `<distributable>`.

... The top-level `<icon>` and its children
elements, `<display-name>`, and `<description>` elements of a web
fragment are ignored.

... `jsp-property-group` is additive. It is
recommended that `jsp-config` element use the `url-pattern` as opposed
to extension mappings when bundling static resources in the
`META-INF/resources` directory of a jar file. Further more JSP resources
for a fragment should be in a sub-directory same as the fragment name,
if there exists one. This helps prevent a web-fragment’s
`jsp-property-group` from affecting the JSPs in the main docroot of the
application and the `jsp-property-group` from affecting the JSPs in a
fragment’s `META-INF/resources` directory.

.. For all the resource reference elements (
`env-entry`, `ejb-ref`, `ejb-local-ref`, `service-ref`, `resource-ref`,
`resource-env-ref`, `message-destination-ref`, `persistence-context-ref` and
`persistence-unit-ref`) the following rules apply:

... If any resource reference element is present
in a web fragment, and is missing in the main `web.xml`, the main
`web.xml` inherits the value from the web fragment. If the element is
present in both the main `web.xml` and the web fragment, with the same
name, the `web.xml` takes precedence. None of the child elements from
the fragment are merged into the main `web.xml` except for the
`injection-target` as specified below. For example, if both the main
`web.xml` and a web fragment declare a `<resource-ref>` with the same
`<resource-ref-name>`, the `<resource-ref>` from the `web.xml` will be
used without any child elements being merged from the fragment except
`<injection-target>` as described below.

... If a resource reference element is specified
in two fragments, while absent from the main `web.xml`, and all the
attributes and child elements of the resource reference element are
identical, the resource reference will be merged into the main `web.xml`.
It is considered an error if a resource reference element has the same
name specified in two fragments, while absent from the main `web.xml`
and the attributes and child elements are not identical in the two
fragments. An error must be reported and the application MUST fail to
deploy. For example, if two web fragments declare a `<resource-ref>`
with the same `<resource-ref-name>` element but the type in one is
specified as `javax.sql.DataSource` while the type in the other is that
of a Jakarta Mail resource, it is an error and the application will fail to
deploy.

... For resource reference element with the
same name `<injection-target>` elements from the fragments will be
merged into the main `web.xml`.

.. In addition to the merging rules for
`web-fragment.xml` defined above, the following rules apply when using
the resource reference annotations (`@Resource`, `@Resources, @EJB`,
`@EJBs`, `@WebServiceRef`, `@WebServiceRefs`, `@PersistenceContext`,
`@PersistenceContexts`,`@PersistenceUnit`, and `@PersistenceUnits`).
+
If a resource reference annotation is
applied on a class, it is equivalent to defining a resource, however it
is not equivalent to defining an `injection-target`. The rules above
apply for `injection-target` element in this case.
+
If a resource reference annotation is used on
a field it is equivalent to defining the `injection-target` element in
the `web.xml`. However if there is no `injection-target` element in the
descriptor then the `injection-target` from the fragments will still be
merged into the `web.xml` as defined above.
+
If, on the other hand, there is an
`injection-target` in the main `web.xml` and there is a resource
reference `annotation` with the same resource name, then it is
considered an override for the resource reference annotation. In this
case since there is an `injection-target` specified in the descriptor,
the rules defined above would apply in addition to overriding the value
for the resource reference annotation.

.. If a `data-source` element is specified in
two fragments, while absent from the main `web.xml`, and all the
attributes and child elements of the `data-source` element are
identical, the `data-source` will be merged into the main `web.xml`. It
is considered an error if a `data-source` element has the same name
specified in two fragments, while absent from the main `web.xml` and the
attributes and child elements are not identical in the two fragments. In
such a case an error must be reported and the application MUST fail to
deploy.
+
Below are some examples that show the outcome
in the different cases.
+
.Example 1
--

.web.xml
no resource-ref definition



.Fragment 1 - web-fragment.xml
[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar</injection-target-class>
    <injection-target-name>baz</injection-target-name>
  </injection-target>
</resource-ref>
----

The effective metadata would be:

[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar</injection-target-class>
    <injection-target-name>baz</injection-target-name>
  </injection-target>
</resource-ref>
----

--
+
.Example 2
--

.web.xml
[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
</resource-ref>
----

.Fragment 1 - web-fragment.xml
[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar</injection-target-class>
    <injection-target-name>baz</injection-target-name>
  </injection-target>
</resource-ref>
----

.Fragment 2 - web-fragment.xml
[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar2</injection-target-class>
    <injection-target-name>baz2</injection-target-name>
  </injection-target>
</resource-ref>
----

The effective metadata would be:

[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar</injection-target-class>
    <injection-target-name>baz</injection-target-name>
  </injection-target>
  <injection-target>
    <injection-target-class>com.example.Bar2</injection-target-class>
    <injection-target-name>baz2</injection-target-name>
  </injection-target>
</resource-ref>
----

--
+
.Example 3
--

.web.xml
[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar3</injection-target-class>
    <injection-target-name>baz3</injection-target-name>
  </injection-target>
</resource-ref>
----

.Fragment 1 - web-fragment.xml
[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar</injection-target-class>
    <injection-target-name>baz</injection-target-name>
  </injection-target>
</resource-ref>
----

.Fragment 2 - web-fragment.xml
[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar2</injection-target-class>
    <injection-target-name>baz2</injection-target-name>
  </injection-target>
</resource-ref>
----

The effective metadata would be:

[source,xml]
----
<resource-ref>
  <resource-ref-name="foo">
  ...
  <injection-target>
    <injection-target-class>com.example.Bar3</injection-target-class>
    <injection-target-name>baz3</injection-target-name>
    <injection-target-class>com.example.Bar</injection-target-class>
    <injection-target-name>baz</injection-target-name>
    <injection-target-class>com.example.Bar2</injection-target-class>
    <injection-target-name>baz2</injection-target-name>
  </injection-target>
</resource-ref>
----


The `<injection-target>` from fragment 1 and
2 will be merged into the main web.xml.

--

.. If the main `web.xml` does not have any
`<post-construct>` element specified and web-fragments have specified
`<post-construct>` then the `<post-construct>` elements from the
fragments will be merged into the main `web.xml`. However if in the
main `web.xml` at least one `<post-construct>` element is specified then
the `<post-construct>` elements from the fragment will not be merged. It
is the responsibility of the author of the `web.xml` to make sure that
the `<post-construct>` list is complete.

.. If the main `web.xml` does not have any
`<pre-destroy>` element specified and web-fragments have specified
`<pre-destroy>` then the `<pre-destroy>` elements from the fragments
will be merged into the main `web.xml`. However if in the main
`web.xml` at least one `<pre-destroy>` element is specified then the
`<pre-destroy>` elements from the fragment will not be merged. It is the
responsibility of the author of the `web.xml` to make sure that the
`<pre-destroy>` list is complete.

.. After processing the `web-fragment.xml`,
annotations from the corresponding fragment are processed to complete
the effective metadata for the fragment before processing the next
fragment. The following rules are used for processing annotations:

... Any metadata specified via an annotation that
isn’t already present in the descriptor will be used to augment the
effective descriptor.

... Configuration specified in the main `web.xml`
or a web fragment takes precedence over the configuration specified via
annotations.

... For a servlet defined via the `@WebServlet`
annotation, to override values via the descriptor, the name of the
servlet in the descriptor MUST match the name of the servlet specified
via the annotation (explicitly specified or the default name, if one is
not specified via the annotation).

... Init params for servlets and filters defined
via annotations, will be overridden in the descriptor if the name of the
init param exactly matches the name specified via the annotation. Init
params are additive between the annotations and descriptors.

... `url-patterns`, when specified in a
descriptor for a given servlet name overrides the url patterns specified
via the annotation.

... For a filter defined via the `@WebFilter`
annotation, to override values via the descriptor, the name of the
filter in the descriptor MUST match the name of the filter specified via
the annotation (explicitly specified or the default name, if one is not
specified via the annotation).

... `url-patterns` to which a filter is applied,
when specified in a descriptor for a given filter name overrides the url
patterns specified via the annotation.

... DispatcherTypes to which a filter applies,
when specified in a descriptor for a given filter name overrides the
DispatcherTypes specified via the annotation.

... The following examples demonstrates some of
the above rules:
+
--

A servlet declared via an annotation and
packaged with the corresponding `web.xml` in the descriptor:

[source,java]
----
@WebServlet(urlPatterns="/MyPattern",
        initParams={@WebInitParam(name="ccc", value="333")})
public class com.example.Foo extends HttpServlet {
    ...
}
----

.web.xml
[source,xml]
----
<servlet>
  <servlet-class>com.example.Foo</servlet-class>
  <servlet-name>Foo</servlet-name>
  <init-param>
    <param-name>aaa</param-name>
    <param-value>111</param-value>
  </init-param>
</servlet>
<servlet>
  <servlet-class>com.example.Foo</servlet-class>
  <servlet-name>Fum</servlet-name>
  <init-param>
    <param-name>bbb</param-name>
    <param-value>222</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>Foo</servlet-name>
  <url-pattern>/foo/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
  <servlet-name>Fum</servlet-name>
  <url-pattern>/fum/*</url-pattern>
</servlet-mapping>
----

Since the name of the servlet declared via
the annotation does not match the name of the servlet declared in the
`web.xml`, the annotation specifies a new servlet declaration in
addition to the other declarations in `web.xml` and is equivalent to:

.web.xml
[source,xml]
----
<servlet>
  <servlet-class>com.example.Foo</servlet-class>
  <servlet-name>com.example.Foo</servlet-name>
  <init-param>
    <param-name>ccc</param-name>
    <param-value>333</param-name>
  </init-param>
</servlet>
----

If the above `web.xml` were replaced with the following:

.web.xml
[source,xml]
----
<servlet>
  <servlet-class>com.example.Foo</servlet-class>
  <servlet-name>com.example.Foo</servlet-name>
  <init-param>
    <param-name>aaa</param-name>
    <param-value>111</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>com.example.Foo</servlet-name>
  <url-pattern>/foo/*</url-pattern>
</servlet-mapping>
----

Then the effective descriptor would be equivalent to:

.web.xml
[source,xml]
----
<servlet>
  <servlet-class>com.example.Foo</servlet-class>
  <servlet-name>com.example.Foo</servlet-name>
  <init-param>
    <param-name>aaa</param-name>
    <param-value>111</param-value>
  </init-param>
  <init-param>
    <param-name>ccc</param-name>
    <param-value>333</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>com.example.Foo</servlet-name>
  <url-pattern>/foo/*</url-pattern>
</servlet-mapping>
----

--

==== Shared Libraries / Runtimes Pluggability

In addition to supporting fragments and use
of annotations, one of the requirements is that not only we be able to
plug-in things that are bundled in the `WEB-INF/lib` but also plugin
shared copies of frameworks - including being able to plug-in to the web
container things like Jakarta XML Web Services, Jakarta Restful Web Services and Jakarta
Server Faces that build on top of the
web container. The `ServletContainerInitializer` allows handling such a
use case as described below.

The `ServletContainerInitializer` class is
looked up via the jar services API. For each application, an instance of
the `ServletContainerInitializer` is created by the container at
application startup time. The framework providing an implementation of
the `ServletContainerInitializer` MUST bundle in the `META-INF/services`
directory of the jar file a file called
`jakarta.servlet.ServletContainerInitializer`, as per the jar services
API, that points to the implementation class of the
`ServletContainerInitializer`.

In addition to the
`ServletContainerInitializer` we also have an annotation -
`HandlesTypes`. The `HandlesTypes` annotation on the implementation of
the `ServletContainerInitializer` is used to express interest in classes
that may have annotations (type, method or field level annotations)
specified in the value of the `HandlesTypes` or if it extends /
implements one those classes anywhere in the class’s super types. The
`HandlesTypes` annotation is applied irrespective of the setting of
`metadata-complete`.

When examining the classes of an application
to see if they match any of the criteria specified by the `HandlesTypes`
annotation of a `ServletContainerInitializer`, the container may run
into class loading problems if one or more of the application's optional
JAR files are missing. Since the container is not in a position to
decide whether these types of class loading failures will prevent the
application from working correctly, it must ignore them, while at the
same time providing a configuration option that would log them.

If an implementation of
`ServletContainerInitializer` does not have the `@HandlesTypes`
annotation, or if there are no matches to any of the `HandlesType`
specified, then it will get invoked once for every application with
`null` as the value of the `Set`. This will allow for the initializer
to determine based on the resources available in the application whether
it needs to initialize a servlet / filter or not.

The `onStartup` method of the
`ServletContainerInitializer` will be invoked when the application is
coming up before any of the servlet listener events are fired.

The `onStartup` method of the
`ServletContainerInitializer` is called with a `Set` of Classes that
either extend / implement the classes that the initializer expressed
interest in or if it is annotated with any of the classes specified via
the `@HandlesTypes` annotation.

A concrete example below showcases how this
would work.

Let's take the Jakarta XML Web Services web services runtime.

The implementation of Jakarta XML Web Services runtime isn't
typically bundled in each and every war file. The implementation would
bundle an implementation of the `ServletContainerInitializer` (shown
below) and the container would look that up using the services API (the
jar file will bundle in it's `META-INF/services` directory a file called
`jakarta.servlet.ServletContainerInitializer` that will point to the
`JAXWSServletContainerInitializer` (shown below).

.JAXWSServletContainerInitializer.java
[source,java]
----
@HandlesTypes(WebService.class)
JAXWSServletContainerInitializer implements ServletContainerInitializer {

    public void onStartup(Set<Class<?>> c, ServletContext ctx) throws ServletException {
        // Jakarta XML Web Services specific code here to initialize the runtime
        // and setup the mapping etc.
        ServletRegistration reg = ctx.addServlet("JAXWSServlet",
                "com.sun.webservice.JAXWSServlet");
        reg.addServletMapping("/foo");
    }

----

The framework jar file can also be bundled in
`WEB-INF/lib` directory of the war file. If the
`ServletContainerInitializer` is bundled in a JAR file inside the
`WEB-INF/lib` directory of an application, its `onStartup` method will
be invoked only once during the startup of the bundling application. If,
on the other hand, the `ServletContainerInitializer` is bundled in a JAR
file outside of the `WEB-INF/lib` directory, but still discoverable by
the runtime’s service provider lookup mechanism, its `onStartup` method
will be invoked every time an application is started.

Implementations of the
`ServletContainerInitializer` interface will be discovered by the
runtime's service lookup mechanism or a container specific mechanism
that is semantically equivalent to it. In either case,
`ServletContainerInitializer` services from web fragment JAR files that
are excluded from an absolute ordering MUST be ignored, and the order in
which these services are discovered MUST follow the application’s class
loading delegation model.

=== JSP Container Pluggability

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.

=== Processing Annotations and Fragments

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.

.Annotations and web fragment processing requirements
[caption="Table 8-1  "]
[%breakable]
[cols="3", options="header"]
|===
|Deployment descriptor
|metadata-complete
|process annotations and web fragments

|web.xml 2.5
|yes
|no

|web.xml 2.5
|no
|yes

|web.xml 3.0 or later
|yes
|no

|web.xml 3.0 or later
|no
|yes
|===


== Dispatching Requests


When building a web application, it is often
useful to forward processing of a request to another servlet, or to
include the output of another servlet in the response. The
`RequestDispatcher` interface provides a mechanism to accomplish this.

When asynchronous processing is enabled on
the request, the `AsyncContext` allows a user to dispatch the request
back to the servlet container.

=== Obtaining a RequestDispatcher

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

* `getRequestDispatcher`

* `getNamedDispatcher`

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
<<Mapping Requests to Servlets>>, associates
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 associated 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")`.

==== Query Strings in Request Dispatcher Paths

The `ServletContext` and `ServletRequest`
methods that create `RequestDispatcher` objects using path information
allow the optional attachment of query string information to the path.
For example, an Application Developer may obtain a `RequestDispatcher` by using the
following code:

[source,java]
----
String path = "/raisins.jsp?orderno=5";
RequestDispatcher rd = context.getRequestDispatcher(path);
rd.include(request, response);
----

Parameters specified in the query string used
to create the `RequestDispatcher` take precedence over other parameters
of the same name passed to the included servlet. The parameters
associated with a `RequestDispatcher` are scoped to apply only for the
duration of the `include` or `forward` call.

=== Using a Request Dispatcher

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

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.

Any references to the request or response objects taken by filter(s)
and/or servlets invoked by the `include` call must continue to act as
the included request/response even after the dispatch has returned.
Specifically any references to the request or response held by
asynchronous processing commenced by the included resource will
continue to act as the included request or response, even after
the dispatch to the include has returned.

==== Included Request Parameters

Except for servlets obtained by using the
`getNamedDispatcher` method, a servlet that has been invoked by another
servlet using the `include` method of `RequestDispatcher` has access to
the path by which it was invoked.

The following request attributes must be set:

[source]
----
jakarta.servlet.include.request_uri
jakarta.servlet.include.context_path
jakarta.servlet.include.servlet_path
jakarta.servlet.include.mapping
jakarta.servlet.include.path_info
jakarta.servlet.include.query_string
----

These attributes are accessible from the
included servlet via the `getAttribute` method on the request object and
their values must be equal to the request URI, context path, servlet
path, mapping, path info, and query string of the included servlet,
respectively. If the request is subsequently included, these attributes
are replaced for that include.

If the included servlet was obtained by using
the `getNamedDispatcher` method, these attributes must not be set.

=== The Forward Method

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

Any references to the request or response objects taken by filter(s)
and/or servlets invoked by the `forward` call must continue to act as
the forwarded request/response even after the dispatch has returned.
Specifically any references to the request or response held by
asynchronous processing commenced by the forwarded resource will
continue to act as the forwarded request or response, even after
the dispatch to the include has returned.

==== Forwarded Query String

The request dispatching mechanism is
responsible for aggregating query string parameters when forwarding or
including requests.

==== Forwarded Request Parameters

Except for servlets obtained by using the
`getNamedDispatcher` method, a servlet that has been invoked by another
servlet using the `forward` method of `RequestDispatcher` has access to
the path of the original request.

The following request attributes must be set:

[source]
----
jakarta.servlet.forward.mapping
jakarta.servlet.forward.request_uri
jakarta.servlet.forward.context_path
jakarta.servlet.forward.servlet_path
jakarta.servlet.forward.path_info
jakarta.servlet.forward.query_string
----

The values of these attributes must be equal
to the return values of the `HttpServletRequest` methods
`getHttpServletMapping`, `getRequestURI`, `getContextPath`,
`getServletPath`, `getPathInfo`, `getQueryString` respectively, invoked
on the request object passed to the first servlet object in the call chain
that received the request from the client.

These attributes are accessible from the
forwarded servlet via the `getAttribute` method on the request object.
Note that these attributes must always reflect the information in the
original request even under the situation that multiple forwards and
subsequent includes are called.

If the forwarded servlet was obtained by using
the `getNamedDispatcher` method, these attributes must not be set.

=== Error Handling

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.

=== Obtaining an AsyncContext

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 Dispatch Method

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

`dispatch(path)`::

The `dispatch` 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 `"/"`.

`dispatch(servletContext, path)`::

The `dispatch` method takes a `String`
argument describing a path within the scope of the `ServletContext`
specified. This path must be relative to the root of the
`ServletContext` specified and begin with a `"/"`.

`dispatch()`::

The `dispatch` method takes no argument. It
uses the original URI as the path. If the `AsyncContext` was initialized
via the `startAsync(ServletRequest, ServletResponse)` and the request
passed is an instance of `HttpServletRequest`, then the dispatch is to
the URI returned by `HttpServletRequest.getRequestURI()`. Otherwise the
dispatch is to the URI of the request when it was last dispatched by the
container.

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`.

==== Query String

The request dispatching mechanism is
responsible for aggregating query string parameters when dispatching
requests.

==== Dispatched Request Parameters

A servlet that has been invoked by using the
`dispatch` method of `AsyncContext` has access to the path of the
original request.

The following request attributes must be set:

[source]
----
jakarta.servlet.async.mapping
jakarta.servlet.async.request_uri
jakarta.servlet.async.context_path
jakarta.servlet.async.servlet_path
jakarta.servlet.async.path_info
jakarta.servlet.async.query_string
----

The values of these attributes must be equal
to the return values of the `HttpServletRequest` methods
`getHttpServletMapping`, `getRequestURI`, `getContextPath`,
`getServletPath`, `getPathInfo`, `getQueryString` respectively, invoked on
the request object passed to the first servlet object in the call chain
that received the request from the client.

These attributes are accessible from the
dispatched servlet via the `getAttribute` method on the request object.
Note that these attributes must always reflect the information in the
original request even under the situation that multiple dispatches are
called.

== Web Applications


A web application is a collection of servlets,
HTML pages, classes, and other resources that make up a complete
application on a web server. The web application can be bundled and run
on multiple containers from multiple vendors.

=== Web Applications Within Web Servers

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.

=== Relationship to ServletContext

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.

=== Elements of a Web Application

A web application may consist of the following
items:

* Servlets
* JSP Pages footnote:[See the Jakarta Server Pages specification available from
`https://jakarta.ee/specifications/pages/`.]
* Utility Classes
* Static documents (HTML, images, sounds, etc.)
* Client side Java applets, beans, and classes
* Descriptive meta information that ties all of the above elements together

=== Deployment Hierarchies

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.

=== Directory Structure

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
<<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-INF/web.xml` deployment descriptor.

* The `/WEB-INF/classes/` directory for
servlet and utility classes. The classes in this directory must be
available to the application class loader.

* The `/WEB-INF/lib/*.jar` area for Java
ARchive files. These files contain servlets, beans, static resources and
JSPs packaged in a JAR file and other utility classes useful to the web
application. The web application class loader must be able to load
classes from any of these archive files.

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.

==== Example of Application Directory Structure

The following is a listing of all the files in
a sample web application:

[source]
----
/index.html
/howto.jsp
/feedback.jsp
/images/banner.gif
/images/jumping.gif
/WEB-INF/web.xml
/WEB-INF/lib/jspbean.jar
/WEB-INF/lib/catalog.jar!/META-INF/resources/catalog/moreOffers/books.html
/WEB-INF/classes/com/mycorp/servlets/MyServlet.class
/WEB-INF/classes/com/mycorp/util/MyUtils.class
----

=== Web Application Archive File

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.

=== Web Application Deployment Descriptor

The web application deployment descriptor (see
<<Deployment Descriptor>>) includes
the following types of configuration and deployment information:

* `ServletContext` Init Parameters

* Session Configuration

* Servlet/JSP Definitions

* Servlet/JSP Mappings

* MIME Type Mappings

* Welcome File list

* Error Pages

* Security

==== Common Dependencies

When a number of applications make use of the
same code or resources, they will typically be installed as library
files in the container. These files are often common or standard APIs
that can be used without sacrificing portability. Files used only by one
or a few applications will be made available for access as part of the
web application. The container must provide a directory for these
libraries. The files placed within this directory must be available
across all web applications. The location of this directory is
container-specific. The class loader the servlet container uses for
loading these library files must be the same for all web applications
within the same JVM. This class loader instance must be somewhere in the
chain of parent class loaders of the web application class loader.

==== Web Application Class Loader

The class loader that a container uses to load
a servlet in a WAR must allow the developer to load any resources
contained in library JARs within the WAR following normal Java SE
semantics using `getResource`.
Servlet containers that are not part of a Jakarta EE product
should not allow the application to override Jakarta EE platform classes,
such as those in the jakarta.* namespaces, that Jakarta EE does
not allow to be modified. The container should not allow applications to
override or access the container’s implementation classes. It is
recommended also that the application class loader be implemented so
that classes and resources packaged within the WAR are loaded in
preference to classes and resources residing in container-wide library
JARs. An implementation MUST also guarantee that for every web
application deployed in a container, a call to
`Thread.currentThread.getContextClassLoader()` MUST return a
`ClassLoader` instance that implements the contract specified in this
section. Furthermore, the `ClassLoader` instance MUST be a separate
instance for each deployed web application. The container is required to
set the thread context `ClassLoader` as described above before making
any callbacks (including listener callbacks) into the web application,
and set it back to the original `ClassLoader`, once the callback
returns.

=== Replacing a Web Application

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.

[[_Error_Handling]]
=== Error Handling

==== Request Attributes

A web application must be able to specify that
when errors occur, other resources in the application are used to
provide the content body of the error response. The specification of
these resources is done in the deployment descriptor.

If the location of the error handler is a
servlet or a JSP page:

* The original unwrapped request and response
objects created by the container are passed to the servlet or JSP page.

* The request path and attributes are set as if
a `RequestDispatcher.forward` to the error resource had been performed.

* The request attributes in <<Request_Attributes_and_their_types>> must be set.

[[Request_Attributes_and_their_types]]
.Request Attributes and their types
[caption="Table 10-1  "]
[%breakable]
[cols="2", options="header"]
|===
|Request Attributes
|Type

|`jakarta.servlet.error.status_code`
|`java.lang.Integer`

|`jakarta.servlet.error.exception_type`
|`java.lang.Class`

|`jakarta.servlet.error.message`
|`java.lang.String`

|`jakarta.servlet.error.exception`
|`java.lang.Throwable`

|`jakarta.servlet.error.request_uri`
|`java.lang.String`

|`jakarta.servlet.error.query_string`
|`java.lang.String`

|`jakarta.servlet.error.servlet_name`
|`java.lang.String`
|===

These attributes allow the servlet to generate
specialized content depending on the status code, the exception type,
the error message, the exception object propagated, the URI of the
request processed by the servlet in which the error occurred (as
determined by the `getRequestURI` call), the query string of the
request processed by the servlet in which the error occurred (as
determined by the `getQueryString` call) and the logical name of the
servlet in which the error occurred.

With the introduction of the exception object
to the attributes list for version 2.3 of this specification, the
exception type and error message attributes are redundant. They are
retained for backwards compatibility with earlier versions of the API.

==== Error Pages

To allow developers to customize the
appearance of content returned to a web client when a servlet generates
an error, the deployment descriptor defines a list of error page
descriptions. The syntax allows the configuration of resources to be
returned by the container either when a servlet or filter calls
`sendError` on the response for specific status codes, or if the servlet
generates an exception or error that propagates to the container.

If the `sendError` method is called on the
response, the container consults the list of error page declarations for
the web application that use the error-code syntax and attempts a
match. If there is a match, the container returns the resource as
indicated by the location entry.

A servlet or filter may throw the following
exceptions during processing of a request:

* runtime exceptions or errors

* `ServletExceptions` or subclasses thereof

* `IOExceptions` or subclasses thereof

The web application may have declared error
pages using the `exception-type` element. In this case the container
matches the exception type by comparing the exception thrown with the
list of error-page definitions that use the `exception-type` element. A
match results in the container returning the resource indicated in the
location entry. The closest match in the class hierarchy wins.

If no `error-page` declaration containing an
`exception-type` fits using the class-hierarchy match, and the exception
thrown is a `ServletException` or subclass thereof, the container
extracts the wrapped exception, as defined by the
`ServletException.getRootCause` method. A second pass is made over the
error page declarations, again attempting the match against the error
page declarations, but using the wrapped exception instead.

Error-page declarations using the
`exception-type` element in the deployment descriptor must be unique up
to the class name of the exception-type. Similarly, error-page
declarations using the `error-code` element must be unique in the
deployment descriptor up to the status code.

If an `error-page` element in the deployment
descriptor does not contain an `exception-type` or an `error-code`
element, the error page is a default error page.

The error page mechanism described does not
intervene when errors occur when invoked using the `RequestDispatcher`
or `filter.doFilter` method. In this way, a filter or servlet using the
`RequestDispatcher` has the opportunity to handle errors generated.

If a servlet generates an error that is not
handled by the error page mechanism as described above, the container
must ensure to send a response with status 500.

The default servlet and container will use the
`sendError` method to send 4xx and 5xx status responses, so that the
error mechanism may be invoked. The default servlet and container will
use the `setStatus` method for 2xx and 3xx responses and will not invoke
the error page mechanism.

If the application is using
asynchronous operations as described in
<<Asynchronous processing>>, it is the
application’s responsibility to handle all errors in application created
threads. The container MAY take care of the errors from the thread
issued via `AsyncContext.start`. For handling errors that occur during
`AsyncContext.dispatch` see <<Dispatch_Errors>>.

To avoid unexpected behaviour, the container must dispatch all error dispatches
to error pages as HTTP GET requests. The original HTTP method must be provided
to the dispatched request via the request attribute
'RequestDispatcher.ERROR_METHOD'. The original HTTP method is the value returned
from 'HttpServletRequest.getMethod()' immediately before the error dispatch. 


==== Error Filters

The error page mechanism operates on the
original unwrapped/unfiltered request and response objects created by
the container. The mechanism described in
<<Filters and the RequestDispatcher>>
may be used to specify filters that are applied before an error response
is generated.

=== Welcome Files

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:

* The deployment descriptor lists the following
welcome files.
+
--
[source,xml]
----
<welcome-file-list>
 <welcome-file>index.html</welcome-file>
 <welcome-file>default.jsp</welcome-file>
</welcome-file-list>
----
--

* The static content in the WAR is as follows
+
--
[source]
----
/foo/index.html
/foo/default.jsp
/foo/orderform.html
/foo/home.gif
/catalog/default.jsp
/catalog/products/shop.jsp
/catalog/products/register.jsp
----
--

* A request URI of `/foo` will be redirected to
a URI of `/foo/`.

* A request URI of `/foo/` will be returned as
`/foo/index.html`.

* A request URI of `/catalog` will be redirected
to a URI of `/catalog/`.

* A request URI of `/catalog/` will be returned
as `/catalog/default.jsp`.

* A request URI of `/catalog/index.html` will
cause a `404 not found`

* A request URI of `/catalog/products` will be
redirected to a URI of `/catalog/products/`.

* A request URI of `/catalog/products/` will be
passed to the “default” servlet, if any. If no “default” servlet is
mapped, the request may cause a `404 not found`, may cause a directory
listing including `shop.jsp` and `register.jsp`, or may cause other
behavior defined by the container. See
<<Specification of Mappings>> for the
definition of “default” servlet.

* All of the above static content can also be
packaged in a JAR file with the content listed above packaged in the
`META-INF/resources` directory of the jar file. The JAR file can then be
included in the `WEB-INF/lib` directory of the web application.

=== Web Application Environment

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
<<_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.

=== Web Application Deployment

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.

* Instantiate an instance of each event listener
identified by a `<listener>` element in the deployment descriptor.

* For instantiated listener instances that
implement `ServletContextListener`, call the `contextInitialized()`
method.

* Instantiate an instance of each filter
identified by a `<filter>` element in the deployment descriptor and call
each filter instance’s `init()` method.

* Instantiate an instance of each servlet
identified by a `<servlet>` element that includes a `<load-on-startup>`
element in the order defined by the load-on-startup element values, and
call each servlet instance’s `init()` method.

=== Inclusion of a web.xml Deployment Descriptor

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.


== Application Lifecycle Events


=== Introduction

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.

=== Event Listeners

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.

==== Event Types and Listener Interfaces

Events types and the listener interfaces used
to monitor them are shown in the following tables:

.Servlet Context Events
[caption="Table 11-1  "]
[%breakable]
[cols="25,35,40", options="header"]
|===
|Event Type
|Description
|Listener Interface

|Lifecycle
|The servlet context has just been created and
is available to service its first request, or the servlet context is
about to be shut down.
|`jakarta.servlet.ServletContextListener`

|Changes to attributes
|Attributes on the servlet context have been
added, removed, or replaced.
|`jakarta.servlet.` +
`ServletContextAttributeListener`
|===

.HTTP Session Events
[caption="Table 11-2  "]
[%breakable]
[cols="25,35,40", options="header"]
|===
|Event Type
|Description
|Listener Interface

|Lifecycle
|An `HttpSession` has been created,
invalidated, or timed out.
|`jakarta.servlet.http.` +
`HttpSessionListener`

|Changes to attributes
|Attributes have been added, removed, or
replaced on an `HttpSession`.
|`jakarta.servlet.http.` +
`HttpSessionAttributeListener`

|Changes to id
|The id of `HttpSession` has been changed.
|`jakarta.servlet.http.` +
`HttpSessionIdListener`

|Session migration
|`HttpSession` has been activated or passivated.
|`jakarta.servlet.http.` +
`HttpSessionActivationListener`

|Object binding
|Object has been bound to or unbound from `HttpSession`
|`jakarta.servlet.http.` +
`HttpSessionBindingListener`
|===

.Table 11-3 Servlet Request Events
[caption="Table 11-3  "]
[%breakable]
[cols="25,35,40", options="header"]
|===
|Event Type
|Description
|Listener Interface

|Lifecycle
|A servlet request has started being processed by web components.
|`jakarta.servlet.ServletRequestListener`

|Changes to attributes
|Attributes have been added, removed, or replaced on a `ServletRequest`.
|`jakarta.servlet.` +
`ServletRequestAttributeListener`

|Async events
|A timeout, connection termination or completion of async processing
|`jakarta.servlet.AsyncListener`
|===

For details of the API, refer to the API
reference.

==== An Example of Listener Use

To illustrate a use of the event scheme,
consider a simple web application containing a number of servlets that
make use of a database. The Application Developer has provided a servlet context
listener class for management of the database connection.

. When the application starts up, the listener
class is notified. The application logs on to the database, and stores
the connection in the servlet context.

. Servlets in the application access the
connection as needed during activity in the web application.

. When the web server is shut down, or the
application is removed from the web server, the listener class is
notified and the database connection is closed.

=== Listener Class Configuration

==== Provision of Listener Classes

The Application Developer of the web application provides
listener classes implementing one or more of the listener interfaces in
the `jakarta.servlet` API. Each listener class must have a public
constructor taking no arguments. The listener classes are packaged into
the WAR, either under the `WEB-INF/classes` archive entry, or inside a
JAR in the `WEB-INF/lib` directory.

==== Deployment Declarations

Listener classes are declared in the web
application deployment descriptor using the `listener` element. They are
listed by class name in the order in which they are to be invoked.
Unlike other listeners, listeners of type `AsyncListener` may only be
registered (with a `ServletRequest`) programmatically.

==== Listener Registration

The web container creates an instance of each
listener class and registers it for event notifications prior to the
processing of the first request by the application. The web container
registers the listener instances according to the interfaces they
implement and the order in which they appear in the deployment
descriptor. During web application execution, listeners for the given
events are mostly invoked in their registration orders, but there are
some exceptions. For instance, `HttpSessionListener.destroy` are invoked
in reverse order. See <<Assembling_the_descriptor>> for details.

==== Notifications At Shutdown

On application shutdown, listeners are
notified in reverse order to their declarations with notifications to
session listeners preceding notifications to context listeners. Session
listeners must be notified of session invalidations prior to context
listeners being notified of application shutdown.

=== Deployment Descriptor Example

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:

.web.xml
[source,xml]
----
<web-app>
  <display-name>MyListeningApplication</display-name>
  <listener>
    <listener-class>com.example.MyConnectionManager</listener-class>
   </listener>

  <listener>
    <listener-class>com.example.MyLoggingModule</listener-class>
  </listener>

  <servlet>
    <display-name>RegistrationServlet</display-name>
    ...
  </servlet>
</web-app>
----

=== Listener Instances and Threading

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.

=== Listener Exceptions

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 <<_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.

=== Distributed Containers

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.

=== Session Events

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.


== Mapping Requests to Servlets


The mapping techniques described in
this chapter are required for web containers mapping client requests to
servlets.

=== Use of URL Paths

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 <<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 will try to find an exact match
of the path of the request to the path of the servlet. A successful
match selects the servlet.

. The container will recursively try to match
the longest path-prefix. This is done by stepping down the path tree a
directory at a time, using the `"/"` character as a path
separator. The longest match determines the servlet selected.

. If the last segment in the URL path contains
an extension (e.g. `.jsp`), the servlet container will try to match a
servlet that handles requests for the extension. An extension is defined
as the part of the last segment after the last `"."` character.

. If neither of the previous three rules result
in a servlet match, the container will attempt to serve content
appropriate for the resource requested. If a "default" servlet is
defined for the application, it will be used. Many containers provide an
implicit default servlet for serving content.

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

=== Specification of Mappings

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

* A string beginning with a `"/"`
character and ending with a `"/*"` suffix is used for path
mapping.

* A string beginning with a `"*."` prefix
is used as an extension mapping.

* The empty string (`+""+`) is a special URL pattern that exactly maps
to the application's context root, i.e., requests of the form
`\http://host:port/<context-root>` or `\http://host:port/<context-root>/`.
In this case the path info is `"/"` and the servlet path is empty string
(`+""+`).

* A string containing only the `"/"`
character indicates the "default" servlet of the application. In this
case the servlet path is the request URI minus the context path and the
path info is null.

* All other strings are used for exact matches
only.

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.

==== Implicit Mappings

If the container has an internal JSP
container, the `\*.jsp` extension is mapped to it, allowing JSP pages to
be executed on demand. This mapping is termed an _implicit_ mapping. If
a `*.jsp` mapping is defined by the web application, its mapping takes
precedence over the implicit mapping.

A servlet container is allowed to make other
implicit mappings as long as explicit mappings take precedence. For
example, an implicit mapping of `*.shtml` could be mapped to include
functionality on the server.

==== Example Mapping Set

Consider the following set of mappings:

.Example Set of Maps
[caption="Table 12-1  "]
[%breakable]
[cols="2", options="header"]
|===
|Path Pattern
|Servlet

|`/foo/bar/*`
|`servlet1`

|`/baz/*`
|`servlet2`

|`/catalog`
|`servlet3`

|`*.bop`
|`servlet4`
|===

The following behavior would result:

.Incoming Paths Applied to Example Maps
[caption="Table 12-2  "]
[%breakable]
[cols="2", options="header"]
|===
|Incoming Path
|Servlet Handling Request

|`/foo/bar/index.html`
|`servlet1`

|`/foo/bar/index.bop`
|`servlet1`

|`/baz`
|`servlet2`

|`/baz/index.html`
|`servlet2`

|`/catalog`
|`servlet3`

|`/catalog/index.html`
|`"default" servlet`

|`/catalog/racecar.bop`
|`servlet4`

|`/index.bop`
|`servlet4`
|===

Note that in the case of `/catalog/index.html`
and `/catalog/racecar.bop`, the servlet mapped to `/catalog` is not
used because the match is not exact.

=== Runtime Discovery of Mappings

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.

==== Runtime Discovery of Servlet Mappings

The method `getHttpServletMapping()` on
`HttpServletRequest` returns an `HttpServletMapping` implementation that
provides information for the mapping that caused the current `Servlet`
to be invoked. Please see the javadocs for the normative specification.
Please see sections <<Included Request Parameters>>,
<<Forwarded Request Parameters>> and <<Dispatched Request Parameters>>
for relevant request attributes. As with the included and
forwarded request parameters, the `HttpServletMapping` is not available
for servlets that have been obtained with a call to
`ServletContext.getNamedDispatcher()`.

== Security


Web applications are created by Application
Developers who give, sell, or otherwise transfer the application to a
Deployer for installation into a runtime environment. Application
Developers communicate the security requirements to the Deployers and
the deployment system. This information may be conveyed declaratively
via the application’s deployment descriptor, by using annotations within
the application code, or programmatically via the `setServletSecurity`
method of the `ServletRegistration.Dynamic` interface.

This chapter describes the servlet container
security mechanisms and interfaces and the deployment descriptor,
annotation, and programmatic mechanisms for conveying the security
requirements of applications.

=== Introduction

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:

Authentication::
The means by which
communicating entities prove to one another that they are acting on
behalf of specific identities that are authorized for access.

Access control for resources::
The means by
which interactions with resources are limited to collections of users or
programs for the purpose of enforcing integrity, confidentiality, or
availability constraints.

Data Integrity::
The means used to prove
that information has not been modified by a third party while in
transit.

Confidentiality or Data Privacy::
The means
used to ensure that information is made available only to users who are
authorized to access it.

=== Declarative Security

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

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:

* `authenticate`

* `login`

* `logout`

* `getRemoteUser`

* `isUserInRole`

* `getUserPrincipal`

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:

[source,xml]
----
<security-role-ref>
  <role-name>FOO</role-name>
  <role-link>manager</role-link>
</security-role-ref>
----

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 `"pass:[*]"` should never be used as an
argument in calling `isUserInRole`. Any call to `isUserInRole` with `"pass:[*]"`
must return false. If the role-name of the security-role to be tested is
`"pass:[*]pass:[*]"`, and the application has NOT declared an application security-role
with role-name `"pass:[*]pass:[*]"`, `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.

=== Programmatic Security Policy Configuration

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

==== @ServletSecurity Annotation

The `@ServletSecurity` annotation provides
an alternative mechanism for defining access control constraints
equivalent to those that could otherwise have been expressed
declaratively via `security-constraint` elements in the portable
deployment descriptor or programmatically via the `setServletSecurity`
method of the `ServletRegistration` interface. Servlet containers MUST
support the use of the `@ServletSecurity` annotation on classes (and
subclasses thereof) that implement the `jakarta.servlet.Servlet`
interface.

[source,java]
----
package jakarta.servlet.annotation;

@Inherited
@Documented
@Target(value=TYPE)
@Retention(value=RUNTIME)
public @interface ServletSecurity {
    HttpConstraint value();
    HttpMethodConstraint[] httpMethodConstraints();
}
----

.The ServletSecurity Interface
[caption="Table 13-1   "]
[%breakable]
[cols="25,50,25", options="header"]
|===
|Element
|Description
|Default

|`value`
|the HttpConstraint that defines the
protection to be applied to all HTTP methods that are NOT represented in
the array returned by httpMethodConstraints.
|`@HttpConstraint`

|`httpMethodConstraints`
|the array of HTTP method specific
constraints.
|`{}`
|===

[discrete]
===== `@HttpConstraint`

The `@HttpConstraint` annotation is used
within the `@ServletSecurity` annotation to represent the security
constraint to be applied to all HTTP protocol methods for which a
corresponding `@HttpMethodConstraint` does NOT occur within the
`@ServletSecurity` annotation.

For the special case where an
`@HttpConstraint` that returns all default values footnote:[From methods value(),
rolesAllowed(), and transportGuarantee().]
occurs in combination with at least one `@HttpMethodConstraint` that
returns other than all default values, the `@HttpConstraint` represents
that no security constraint is to be applied to any of the HTTP protocol
methods to which a security constraint would otherwise apply. This
exception is made to ensure that such potentially non-specific uses of
`@HttpConstraint` do not yield constraints that will explicitly
establish unprotected access for such methods; given that they would not
otherwise be covered by a constraint.

[source,java]
----
package jakarta.servlet.annotation;

@Documented
@Retention(value=RUNTIME)
public @interface HttpConstraint {
    ServletSecurity.EmptyRoleSemantic value();
    java.lang.String[] rolesAllowed();
    ServletSecurity.TransportGuarantee transportGuarantee();
}
----

.The HttpConstraint Interface
[caption="Table 13-2   "]
[%breakable]
[cols="25,50,25", options="header"]
|===
|Element
|Description
|Default

|`value`
|The default authorization semantic that
applies (only) when rolesAllowed returns an-empty array.
|`PERMIT`

|`rolesAllowed`
|An array containing the names of the
authorized roles
|`{}`

|`transportGuarantee`
|The data protection requirements that must be
satisfied by the connections on which requests arrive.
|`NONE`
|===

[discrete]
===== `@HttpMethodConstraint`

The `@HttpMethodConstraint` annotation is
used within the `@ServletSecurity` annotation to represent security
constraints on specific HTTP protocol messages.

[source,java]
----
package jakarta.servlet.annotation;

@Documented
@Retention(value=RUNTIME)
public @interface HttpMethodConstraint {
    ServletSecurity.EmptyRoleSemantic value();
    java.lang.String[] rolesAllowed();
    ServletSecurity.TransportGuarantee transportGuarantee();
}
----

.The HttpMethodConstraint Interface
[caption="Table 13-3   "]
[%breakable]
[cols="25,50,25", options="header"]
|===
|Element
|Description
|value
|Default




|`emptyRoleSemantic`
|The default authorization semantic that
applies (only) when rolesAllowed returns an empty array.
|`PERMIT`

|`rolesAllowed`
|An array containing the names of the
authorized roles
|{}

|`transportGuarantee`
|The data protection requirements that must be
satisfied by the connections on which requests arrive.
|`NONE`
|===

The `@ServletSecurity` annotation may be
specified on (that is, targeted to) a `Servlet` implementation class,
and its value is inherited by subclasses according to the rules defined
for the `@Inherited` meta-annotation. At most one instance of the
`@ServletSecurity` annotation may occur on a servlet implementation
class, and the `@ServletSecurity` annotation MUST NOT be specified on
(that is, targeted to) a Java method.

When one or more `@HttpMethodConstraint`
annotations are defined within a `@ServletSecurity` annotation, each
`@HttpMethodConstraint` defines the `security-constraint` that applies
to the HTTP protocol method identified within the
`@HttpMethodConstraint`. Except for the case where its
`@HttpConstraint` returns all default values, and where it contains at
least one `@HttpMethodConstraint` that returns other than all default
values, the `@ServletSecurity` annotation defines another
`security-constraint` that applies to all HTTP protocol methods for
which a corresponding `@HttpMethodConstraint` has not been defined.

The `security-constraint` elements defined in
the portable deployment descriptors are authoritative for all the
`url-patterns` occurring within the constraints.

When a `security-constraint` in the portable
deployment descriptor includes a `url-pattern` that is an exact match
for a pattern mapped to a class annotated with `@ServletSecurity`, the
annotation must have no effect on the constraints enforced by the
servlet container on the pattern.

When `metadata-complete=true` is defined for
a portable deployment descriptor, the `@ServletSecurity` annotation does
not apply to any of the `url-patterns` mapped to (any servlet mapped to)
the annotated class in the deployment descriptor.

The `@ServletSecurity` annotation is not
applied to the `url-patterns` of a `ServletRegistration` created using
the `addServlet(String, Servlet)` method of the `ServletContext`
interface, unless the `Servlet` was constructed by the `createServlet`
method of the `ServletContext` interface.

With the exceptions listed above, when a
servlet class is annotated with `@ServletSecurity`, the annotation
defines the security constraints that apply to all the `url-patterns`
mapped to all the servlets mapped to the class.

When a class has not been annotated with the
`@ServletSecurity` annotation, the access policy that is applied to a
servlet mapped from that class is established by the applicable
`security-constraint` elements, if any, in the corresponding portable
deployment descriptor, or barring any such elements, by the constraints,
if any, established programmatically for the target servlet via the
`setServletSecurity` method of the `ServletRegistration` interface.

===== Examples

The following examples demonstrate the use of
the ServletSecurity annotation.

.for all HTTP methods, no constraints
[source,java]
----
@ServletSecurity
public class Example1 extends HttpServlet {

}
----

.for all HTTP methods, no auth-constraint, confidential transport required
[source,java]
----
@ServletSecurity(@HttpConstraint(transportGuarantee = TransportGuarantee.CONFIDENTIAL))
public class Example2 extends HttpServlet {

}
----

.for all HTTP methods, all access denied
[source,java]
----
@ServletSecurity(@HttpConstraint(EmptyRoleSemantic.DENY))
public class Example3 extends HttpServlet {

}
----

.for all HTTP methods, auth-constraint requiring membership in Role R1
[source,java]
----
@ServletSecurity(@HttpConstraint(rolesAllowed = "R1"))
public class Example4 extends HttpServlet {

}
----

.for All HTTP methods except GET and POST, no constraints; for methods GET and POST, auth-constraint requiring membership in Role R1; for POST, confidential transport required
[source,java]
----
@ServletSecurity((httpMethodConstraints = {
    @HttpMethodConstraint(value = "GET", rolesAllowed = "R1"),
    @HttpMethodConstraint(value = "POST", rolesAllowed = "R1",
                          transportGuarantee = TransportGuarantee.CONFIDENTIAL)
})
public class Example5 extends HttpServlet {

}
----

.for all HTTP methods except GET auth-constraint requiring membership in Role R1; for GET, no constraints
[source,java]
----
@ServletSecurity(value = @HttpConstraint(rolesAllowed = "R1"),
                 httpMethodConstraints = @HttpMethodConstraint("GET"))
public class Example6 extends HttpServlet {

}
----

.for all HTTP methods except TRACE,
auth-constraint requiring membership in Role R1; for TRACE, all access denied
[source,java]
----
@ServletSecurity(value = @HttpConstraint(rolesAllowed = "R1"),
                 httpMethodConstraints = @HttpMethodConstraint(value="TRACE",
                         emptyRoleSemantic = EmptyRoleSemantic.DENY))
public class Example7 extends HttpServlet {

}
----

===== Mapping @ServletSecurity to security-constraint

This section describes the mapping of the
`@ServletSecurity` annotation to its equivalent representation as
`security-constraint` elements. It is provided to facilitate enforcement
using the existing `security-constraint` enforcement mechanism of the
container. The enforcement by servlet containers, of the
`@ServletSecurity` annotation must be equivalent in effect to
enforcement, by the container, of the `security-constraint` elements
resulting from the mapping defined in this section.

The `@ServletSecurity` annotation is used to
define one method-independent `@HttpConstraint` followed by a list of
zero or more `@HttpMethodConstraint` specifications. The
method-independent constraint is applied to all HTTP methods for which
no HTTP method-specific constraint has been defined.

When no `@HttpMethodConstraint` elements are
included, a `@ServletSecurity` annotation corresponds to a single
`security-constraint` element containing a `web-resource-collection`
that contains no `http-method` elements, and thus pertains to all HTTP
methods.

The following example depicts the
representation of a `@ServletSecurity` annotation with no contained
`@HttpMethodConstraint` annotations as a single `security-constraint`
element. The `url-pattern` elements defined by the corresponding servlet
(registration) would be included in the `web-resource-collection`, and
the presence and value of any contained `auth-constraint` and
`user-data-constraint` elements would be determined by the mapping of
the `@HttpConstraint` value as defined in
<<Mapping @HttpConstraint and @HttpMethodConstraint to XML.>>

.mapping @ServletSecurity with no contained @HttpMethodConstraint
[source,java]
----
@ServletSecurity(@HttpConstraint(rolesAllowed = "Role1"))
----

[source,xml]
----
<security-constraint>
  <web-resource-collection>
    <url-pattern>...</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>Role1</role-name>
  </auth-constraint>
</security-constraint>
----

When one or more `@HttpMethodConstraint`
elements are specified, the method-independent constraint corresponds to
a single `security-constraint` containing a `web-resource-collection`
that contains on `http-method-omission` for each of the HTTP methods
named in the `@HttpMethodConstraint` elements. The `security-constraint`
containing `http-method-omission` elements must NOT be created if the
method-independent constraint returns all default values and at least
one `@HttpMethodConstraint` does not. Each `@HttpMethodConstraint`
corresponds to another `security-constraint` containing a
`web-resource-collection` containing an `http-method` element naming the
corresponding HTTP method.

The following example depicts the
mapping of a `@ServletSecurity` annotation with a single contained
`@HttpMethodConstraint` to two security-constraint elements. The
`url-pattern` elements defined by the corresponding servlet
(registration) would be included in the `web-resource-collection` of
both constraints, and the presence and value of any contained
`auth-constraint` and `user-data-constraint` elements would be
determined by the mapping of the associated `@HttpConstraint` and
`@HttpMethodConstraint` values as defined in
<<Mapping @HttpConstraint and @HttpMethodConstraint to XML.>>

.mapping @ServletSecurity with contained @HttpMethodConstraint
[source,java]
----
@ServletSecurity(value=@HttpConstraint(rolesAllowed = "Role1"),
        httpMethodConstraints = @HttpMethodConstraint(value = "TRACE",
                emptyRoleSemantic = EmptyRoleSemantic.DENY))
----

[source,xml]
----
<security-constraint>
  <web-resource-collection>
    <url-pattern>...</url-pattern>
    <http-method-omission>TRACE</http-method-omission>
  </web-resource-collection>
  <auth-constraint>
    <role-name>Role1</role-name>
  </auth-constraint>
</security-constraint>
<security-constraint>
  <web-resource-collection>
    <url-pattern>...</url-pattern>
    <http-method>TRACE</http-method>
  </web-resource-collection>
  <auth-constraint/>
</security-constraint>
----

===== Mapping @HttpConstraint and @HttpMethodConstraint to XML.

This section describes the mapping of the
`@HttpConstraint` and `@HttpMethodConstraint` annotation values (defined
for use within `@ServletSecurity`) to their corresponding
`auth-constraint` and `user-data-constraint` representations, These
annotations share a common model for expressing the equivalent of the
`auth-constraint` and `user-data-constraint` elements used within the
portable deployment descriptor. That model is composed of the following
3 elements:

`emptyRoleSemantic`::

The authorization semantic, either `PERMIT`
or `DENY`, that applies when no roles are named in `rolesAllowed`. The
default value for this element is `PERMIT`, and `DENY` is not supported
in combination with a non-empty `rolesAllowed` list.

`rolesAllowed`::

A list containing the names of the
authorized roles. When this list is empty, its meaning depends on the
value of the `emptyRoleSemantic`. The role name `\*` has no special
meaning when included in the list of allowed roles. When the special
role name `**` appears in `rolesAllowed`, it indicates that user
authentication, independent of role, is required and sufficient. The
default value for this element is an empty list.

`transportGuarantee`::

The data protection requirements, either
`NONE` or `CONFIDENTIAL`, that must be satisfied by the connections on
which requests arrive. This element is equivalent in meaning to a
`user-data-constraint` containing a `transport-guarantee` with the
corresponding value. The default value for this element is `NONE`.

The following examples depict the
correspondence between the `@HttpConstraint` model described above and
`auth-constraint` and `user-data-constraint` elements in web.xml.

.emptyRoleSemantic=PERMIT, rolesAllowed={}, transportGuarantee=NONE
[source,xml]
----
<!-- no constraints -->
----

.emptyRoleSemantic=PERMIT, rolesAllowed={}, transportGuarantee=CONFIDENTIAL
[source,xml]
----
<user-data-constraint>
  <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
----

.emptyRoleSemantic=PERMIT,rolesAllowed={Role1}, transportGuarantee=NONE
[source,xml]
----
<auth-constraint>
  <security-role-name>Role1</security-role-name>
</auth-constraint>
----

.emptyRoleSemantic=PERMIT,rolesAllowed={Role1}, transportGuarantee=CONFIDENTIAL
[source,xml]
----
<auth-constraint>
  <security-role-name>Role1</security-role-name>
</auth-constraint>
<user-data-constraint>
  <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
----

.emptyRoleSemantic=DENY, rolesAllowed={}, transportGuarantee=NONE
[source,xml]
----
<auth-constraint/>
----

.emptyRoleSemantic=DENY, rolesAllowed={}, transportGuarantee=CONFIDENTIAL
[source,xml]
----
<auth-constraint/>
<user-data-constraint>
  <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
----

==== setServletSecurity of ServletRegistration.Dynamic

The `setServletSecurity` method may be used
within a `ServletContextListener` to define the security constraints to
be applied to the mappings defined for a `ServletRegistration`.

 Collection<String> setServletSecurity(ServletSecurityElement arg);

The `jakarta.servlet.ServletSecurityElement`
argument to `setServletSecurity` is analogous in structure and model to
the `ServletSecurity` interface of the `@ServletSecurity` annotation. As
such, the mappings defined in <<Mapping @ServletSecurity to security-constraint>>, apply analogously to
the mapping of a `ServletSecurityElement` with contained
`HttpConstraintElement` and `HttpMethodConstraintElement` values, to its
equivalent `security-constraint` representation.

The `setServletSecurity` method returns the
(possibly empty) Set of URL patterns that are already the exact target
of a `security-constraint` element in the portable deployment descriptor
(and thus were unaffected by the call).

This method throws an `IllegalStateException`
if the `ServletContext` from which the `ServletRegistration` was
obtained has already been initialized.

When a `security-constraint` in the portable
deployment descriptor includes a `url-pattern` that is an exact match
for a pattern mapped by a `ServletRegistration`, calls to
`setServletSecurity` on the `ServletRegistration` must have no effect on
the constraints enforced by the servlet container on the pattern.

With the exceptions listed above and
including when the servlet class is annotated with `@ServletSecurity`,
when `setServletSecurity` is called on a `ServletRegistration` it
establishes the security constraints that apply to the `url-patterns` of
the registration.

=== Roles

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 deployer has mapped a security role to a
user group in the operational environment. The user groups to which the
calling principal belongs are retrieved from its security attributes.
The principal is in the security role only if the principal belongs to
the user group to which the security role has been mapped by the
deployer.

. A deployer has mapped a security role to a
principal name in a security policy domain. In this case, the principal
name of the calling principal is retrieved from its security attributes.
The principal is in the security role only if the principal name is the
same as a principal name to which the security role was mapped.

=== Authentication

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

* HTTP Basic Authentication

* HTTP Digest Authentication

* HTTPS Client Authentication

* Form Based Authentication

==== HTTP Basic Authentication

HTTP Basic Authentication, which is based on a
username and password, is the authentication mechanism defined in RFC 7617.
A web server requests a web client to
authenticate the user. As part of the request, the web server passes the
`realm` (a string) in which the user is to be authenticated. The web
client obtains the username and the password from the user and transmits
them to the web server. The web server then authenticates the user in
the specified realm.

Basic Authentication is not a secure
authentication protocol. User passwords are sent in simple base64
encoding, and the target server is not authenticated. Additional
protection can alleviate some of these concerns: a secure transport
mechanism (HTTPS), or security at the network level (such as the IPSEC
protocol or VPN strategies) is applied in some deployment scenarios.

==== HTTP Digest Authentication

Like HTTP Basic Authentication, HTTP Digest
Authentication authenticates a user based on a username and a password.
However, unlike HTTP Basic Authentication, HTTP Digest Authentication
does not send user passwords over the network. In HTTP Digest
authentication the client sends a one-way cryptographic hash of the
password (and additional data). Although passwords are not sent on the
wire, HTTP Digest authentication requires that clear text password
equivalents footnote:[The password equivalents can be such that they can
only be used to authenticate as the user at a specific realm.]
 be avaialble to the authenticating
container so that it can validate received authenticators by calculating
the expected digest. Servlet containers SHOULD support HTTP_DIGEST
authentication.

==== Form Based Authentication

The look and feel of the “login screen” cannot
be varied using the web browser’s built-in authentication mechanisms.
This specification introduces a required form based authentication
mechanism which allows an Application Developer to control the look and feel of the
login screens.

The web application deployment descriptor
contains entries for a login form and error page. The login form must
contain fields for entering a username and a password. These fields must
be named `j_username` and `j_password`, respectively.

When a user attempts to access a protected web
resource, the container checks the user’s authentication. If the user is
authenticated and possesses authority to access the resource, the
requested web resource is activated and a reference to it is returned.
If the user is not authenticated, all of the following steps occur:

. The login form associated with the security
constraint is sent to the client and the URL path and HTTP protocol
method triggering the authentication is stored by the container.

. The user is asked to fill out the form,
including the username and password fields.

. The client posts the form back to the server.

. The container attempts to authenticate the
user using the information from the form.

. If authentication fails, the error page is
returned using either a forward or a redirect, and the status code of
the response is set to 200. The error page contains information about
the failure.

. If authentication succeeds, the client is
redirected to the resource using the store URL path.

. When the redirected and authenticated request
arrives at the container, the container restores the request and HTTP
protocol method, and the authenticated user’s principal is checked to
see if it is in an authorized role for accessing the resource.

. If the user is authorized, the request is
accepted for processing by the container.

The HTTP protocol method of the redirected
request that arrives in step 7, may differ from the HTTP method of the
request that triggered the authentication. As such, following the
redirection of step 6, the form authenticator must process the
redirected request even if authentication is not required for the HTTP
method with which the request arrives. To improve the predictability of
the HTTP method of the redirected request, containers should redirect
(in step 6) using the 303 (`SC_SEE_OTHER`) status code, except where
interoperability with HTTP/1.0 user agents is required; in which cases
the 302 status code should be used.

When conducted over an unprotected transport,
Form Based Authentication is subject to some of the same vulnerabilities
as Basic Authentication.

When the request that is triggering
authentication arrives over a secure transport, or the login page is
subject to a user-data-constraint of `CONFIDENTIAL`, the login page must
be returned to the user, and submitted to the container over a secure
transport.

The login page should be subject to a
`user-data-constraint` of `CONFIDENTIAL`, and a `user-data-constraint` of
CONFIDENTIAL should be included in every `security-constraint` that
contains a requirement for authentication.

The login method of the HttpServletRequest
interface provides an alternative means for an application to control
the look and feel of its login screens.

===== Login Form Notes

Form based login and URL based session
tracking can be problematic to implement. Form based login should be
used only when sessions are being maintained by cookies or by SSL
session information.

In order for the authentication to proceed
appropriately, the action of the login form must always be
`j_security_check`. This restriction is made so that the login form
will work no matter which resource it is for, and to avoid requiring the
server to specify the action field of the outbound form. The login form
should specify `autocomplete="off"` on the password form field.

Here is an example showing how the form should
be coded into the HTML page:

[source,xml]
----
<form method="POST" action="j_security_check">
  <input type="text" name="j_username">
  <input type="password" name="j_password" autocomplete="off">
</form>
----

If the form based login is invoked because of
an HTTP request, the original request parameters must be preserved by
the container for use if, on successful authentication, it redirects the
call to the requested resource.

If the user is authenticated using form login
and has created an HTTP session, the timeout or invalidation of that
session leads to the user being logged out in the sense that subsequent
requests must cause the user to be re-authenticated. The scope of the
logout is the same as that of the authentication: for example, if the
container supports single signon, such as Jakarta EE technology compliant
web containers, the user would need to reauthenticate with any of the
web applications hosted on the web container.

==== HTTPS Client Authentication

End user authentication using HTTPS (HTTP over
SSL) is a strong authentication mechanism. This mechanism requires the
client to possess a Public Key Certificate (PKC). Currently, PKCs are
useful in e-commerce applications and also for a single-signon from
within the browser.

==== Additional Container Authentication Mechanisms

Servlet containers should provide public
interfaces that may be used to integrate and configure additional HTTP
message layer authentication mechanisms for use by the container on
behalf of deployed applications. These interfaces should be offered for
use by parties other than the container vendor (including application
developers, system administrators, and system integrators).

To facilitate portable implementation and
integration of additional container authentication mechanisms, it is
recommended that all servlet containers implement the Servlet Container
Profile of The Jakarta Authentication Specification.
The specification is available for download at:
https://jakarta.ee/specifications/authentication/


=== Server Tracking of Authentication Information

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:

. Make login mechanisms and policies a property
of the environment the web application is deployed in.

. Be able to use the same authentication
information to represent a principal to all applications deployed in the
same container, and

. Require re-authentication of users only when a
security policy domain boundary has been crossed.

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.

=== Specifying Security Constraints

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:

* web resource collection (`web-resource-collection` in deployment descriptor)

* authorization constraint (`auth-constraint` in deployment descriptor)

* user data constraint (`user-data-constraint` in deployment descriptor)

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:

* URL patterns (`url-pattern` in deployment descriptor)

* HTTP methods (`http-method` or `http-method-omission` elements in the deployment descriptor)

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 `"pass:[*]"` is a shorthand for all
role names defined in the deployment descriptor. The special role name
`"pass:[*]pass:[*]"` is a shorthand for any authenticated user independent of role. When
the special role name `"pass:[*]pass:[*]"` 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:

* role name (`role-name` in deployment descriptor)

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:

* transport guarantee (`transport-guarantee` in deployment descriptor)

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.

==== Combining Constraints

For the purpose of combining constraints, an
HTTP method is said to occur within a `web-resource-collection` when no
HTTP methods are named in the collection, or the collection specifically
names the HTTP method in a contained `http-method` element, or the
collection contains one or more `http-method-omission` elements, none of
which names the HTTP method.

When a url-pattern and HTTP method pair
occurs in combination( i.e, within a `web-resource-collection`) in
multiple security constraints, the constraints (on the pattern and
method) are defined by combining the individual constraints. The rules
for combining constraints in which the same pattern and method occur are
as follows:

The combination of authorization constraints
that name roles or that imply roles via the name `"pass:[*]"` shall yield the
union of the role names in the individual constraints as permitted
roles. An authorization constraint that names the role `"pass:[*]pass:[*]"` shall
combine with authorization constraints that name or imply roles to
permit any authenticated user independent of role. A security constraint
that does not contain an authorization constraint shall combine with
authorization constraints that name or imply roles to allow
unauthenticated access. The special case of an authorization constraint
that names no roles shall combine with any other constraints to override
their affects and cause access to be precluded.

The combination of `user-data-constraints`
that apply to a common `url-pattern` and `http-method` shall yield the
union of connection types accepted by the individual constraints as
acceptable connection types. A security constraint that does not contain
a `user-data-constraint` shall combine with other `user-data-constraint`
to cause the unprotected connection type to be an accepted connection
type.

==== Example

The following example illustrates the
combination of constraints and their translation into a table of
applicable constraints. Suppose that a deployment descriptor contained
the following security constraints.

[source,xml]
----
<security-constraint>
  <web-resource-collection>
    <web-resource-name>precluded methods</web-resource-name>
    <url-pattern>/*</url-pattern>
    <url-pattern>/acme/wholesale/*</url-pattern>
    <url-pattern>/acme/retail/*</url-pattern>
    <http-method-omission>GET</http-method-omission>
    <http-method-omission>POST</http-method-omission>
  </web-resource-collection>
  <auth-constraint/>
</security-constraint>

<security-constraint>
  <web-resource-collection>
    <web-resource-name>wholesale</web-resource-name>
    <url-pattern>/acme/wholesale/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>PUT</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>SALESCLERK</role-name>
  </auth-constraint>
</security-constraint>

<security-constraint>
  <web-resource-collection>
    <web-resource-name>wholesale 2</web-resource-name>
    <url-pattern>/acme/wholesale/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>CONTRACTOR</role-name>
  </auth-constraint>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>

<security-constraint>
  <web-resource-collection>
    <web-resource-name>retail</web-resource-name>
    <url-pattern>/acme/retail/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>

  <auth-constraint>
    <role-name>CONTRACTOR</role-name>
    <role-name>HOMEOWNER</role-name>
  </auth-constraint>
</security-constraint>
----

The translation of this hypothetical
deployment descriptor would yield the constraints defined in
<<Security_Constraint_Table>>.

[[Security_Constraint_Table]]
.Security Constraint Table
[caption="Table 13-4  "]
[%breakable]
[cols="4", options="header"]
|===
|url-pattern
|http-method
|permitted roles
|supported connection types

|`/*`
|all methods except GET, POST
|access precluded
|not constrained

|`/acme/wholesale/*`
|all methods except GET, POST
|access precluded
|not constrained

|`/acme/wholesale/*`
|GET
|CONTRACTOR SALESCLERK
|not constrained

|`/acme/wholesale/*`
|POST
|CONTRACTOR
|CONFIDENTIAL

|`/acme/retail/*`
|all methods except GET, POST
|access precluded
|not constrained

|`/acme/retail/*`
|GET
|CONTRACTOR HOMEOWNER
|not constrained

|`/acme/retail/*`
|POST
|CONTRACTOR HOMEOWNER
|not constrained
|===

==== Processing Requests

When a servlet container receives a request,
it shall use the algorithm described in
<<Use of URL Paths>> to select the
constraints (if any) defined on the `url-pattern` that is the best match
to the request URI. If no constraints are selected, the container shall
accept the request. Otherwise the container shall determine if the HTTP
method of the request is constrained at the selected pattern. If it is
not, the request shall be accepted. Otherwise, the request must satisfy
the constraints that apply to the HTTP method at the `url-pattern`.
Both of the following rules must be satisfied for the request to be
accepted and dispatched to the associated servlet.

. The characteristics of the connection
on which the request was received must satisfy at least one of the
supported connection types defined by the constraints. If this rule is
not satisfied, the container shall reject the request and redirect it to
the HTTPS port. footnote:[As an optimization, a
container should reject the request as forbidden and return a 403
(`SC_FORBIDDEN`) status code if it knows that access will ultimately be
precluded (by an authorization constraint naming no roles).]


. The authentication characteristics of the
request must satisfy any authentication and role requirements defined by
the constraints. If this rule is not satisfied because access has been
precluded (by an authorization constraint naming no roles), the request
shall be rejected as forbidden and a 403 (SC_FORBIDDEN) status code
shall be returned to the user. If access is restricted to permitted
roles and the request has not been authenticated, the request shall be
rejected as unauthorized and a 401 (SC_UNAUTHORIZED) status code shall
be returned to cause authentication. If access is restricted to
permitted roles and the authentication identity of the request is not a
member of any of these roles, the request shall be rejected as forbidden
and a 403 (SC_FORBIDDEN) status code shall be returned to the user.

==== Uncovered HTTP Protocol Methods

The `security-constraint` schema provides the
ability to enumerate the HTTP methods
to which the protection requirements defined in a `security-constraint`
apply. When HTTP methods are enumerated within a `security-constraint`,
the protections defined by the constraint apply only to the methods
included in the enumeration. We refer to the HTTP methods that are
not included in the enumeration as "uncovered" HTTP methods because
requests using those methods are NOT subject to the `security-constraint` for
all request URLs for which a
`url-pattern` of the `security-constraint` is a best match.

The HTTP methods for a security constraint may be enumerated directly using
`http-method` elements or may be enumerated by omission using
`http-method-omission` elements. In the latter case, the HTTP methods for a
security constraint are all those methods NOT listed by the
`http-method-omission` elements.

When HTTP methods are not enumerated within a
`security-constraint`, the protections defined by the constraint apply
to the complete set of HTTP (extension) methods. In that case, there are
no uncovered HTTP methods at all request URLs for which a `url-pattern`
of the `security-constraint` is a best match.

The examples that follow depict the three
ways in which HTTP protocol methods may be left uncovered. The
determination of whether methods are uncovered for a `url-pattern` is made after
all the constraints that apply to that `url-pattern` have been combined as
described in <<Combining Constraints>>.

. A `security-constraint` names one or more
HTTP methods in `http-method` elements. All HTTP methods other than
those named in the constraint are uncovered.
+
[source,xml]
----
<security-constraint>
  <web-resource-collection>
    <web-resource-name>wholesale</web-resource-name>
    <url-pattern>/acme/wholesale/*</url-pattern>
    <http-method>GET</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>SALESCLERK</role-name>
  </auth-constraint>
</security-constraint>
----
+
All HTTP Methods except GET are uncovered.

. A `security-constraint` names one or more
HTTP methods in `http-method-omission` elements. All HTTP methods named
in the constraint are uncovered.
+
[source,xml]
----
<security-constraint>
  <web-resource-collection>
    <web-resource-name>wholesale</web-resource-name>
    <url-pattern>/acme/wholesale/*</url-pattern>
    <http-method-omission>GET</http-method-omission>
  </web-resource-collection>
  <auth-constraint/>
</security-constraint>
----
+
GET is uncovered. All other methods are covered by the excluding
`auth-constraint`.

. A `@ServletSecurity` annotation includes an
`@HttpConstraint` that returns all default values and it also includes
at least one `@HttpMethodConstraint` that returns other than all default
values. All HTTP methods other than those named in an
`@HTTPMethodConstraint` are uncovered by the annotation. This case is
analogous to case 1, and equivalent use of the `setServletSecurity`
method of the `ServletRegistration` interface will also produce an
analogous result.
+
[source,java]
----
@ServletSecurity((httpMethodConstraints = {
    @HttpMethodConstraint(value = "GET", rolesAllowed = "R1"),
    @HttpMethodConstraint(value = "POST", rolesAllowed = "R1",
            transportGuarantee = TransportGuarantee.CONFIDENTIAL)
    })
public class Example5 extends HttpServlet {

}
----
+
All HTTP Methods except GET and POST are uncovered.

===== Rules for Security Constraint Configuration

Objective: Make sure all HTTP methods at all
constrained URL patterns have the intended security protections (that
is, are covered).

. Do not name HTTP methods in constraints; in
which case, the security protections defined for the URL patterns will
apply to all HTTP methods.

. If you can’t follow rule #1, add the
`<deny-uncovered-http-methods>` and declare (using the `<http-method>`
element, or equivalent annotation) all the HTTP methods (with security
protections) that are to be allowed at the constrained URL patterns.

. If you can’t follow rule #2, declare
constraints to cover all HTTP methods at each constrained URL pattern.
Use the `<http-method-omission>` element or the `HttpMethodConstraint`
annotation to represent the set of all HTTP methods other than those
named by `<http-method>` or `HttpMethodConstraint`. When using
annotations, use the `HttpConstraint` annotation to define the security
semantic to be applied to all other HTTP methods and configure
`EmptyRoleSemantic=DENY` to cause all other HTTP methods to be denied.

===== Handling Uncovered HTTP Methods

During application deployment, the container
must inform the deployer of any uncovered HTTP methods present in the
application security constraint configuration resulting from the
combination of the constraints defined for the application. The provided
information must identify the uncovered HTTP protocol methods, and the
corresponding URL patterns at which the HTTP methods are uncovered. The
requirement to notify the deployer may be satisfied by logging the
required information.

When the `deny-uncovered-http-methods` flag
is set in the web.xml of an application, the container must deny any
HTTP protocol method when it is used with a request URL for which the
HTTP method is uncovered at the combined security constraint that
applies to the url-pattern that is the best match for the request URL.
The denied request shall be rejected as forbidden and a 403
(SC_FORBIDDEN) status code shall be returned.

To cause uncovered HTTP methods to be denied,
the deployment system should establish additional excluding
auth-constraints, to cover these HTTP methods at the constrained
url-patterns at which the HTTP methods are uncovered.

When an application’s security configuration does not create any
uncovered methods, the `deny-uncovered-http-methods` flag
must have no effect on the effective security configuration of the
application.

Applying the `deny-uncovered-http-methods`
flag to an application whose security configuration creates uncovered
methods, may, in some cases, deny access to resources that must be
accessible in order for the application to function. In such cases, the
security configuration of the application should be completed such that
all uncovered methods are covered by an appropriate constraint
configuration.

Application Developers should define security
constraint configurations that leave no HTTP methods uncovered, and they
should set the `deny-uncovered-http-methods` flag to ensure that their
applications do not become dependent on being accessible via uncovered
methods.

A servlet container may provide a
configurable option to select whether the default behavior for uncovered
methods is ALLOW or DENY. This option may be configured on a
per-application granularity or larger. Note that setting this default to
DENY may cause some applications to fail.

=== Default Policies

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.

=== Login and Logout

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.


== Deployment Descriptor


This chapter specifies the Jakarta Servlet
Specification requirements for web container support of deployment
descriptors. The deployment descriptor conveys the elements and
configuration information of a web application between Application
Developers, Application Assemblers, and Deployers.

For Servlet {spec-version}, the deployment descriptor is defined in terms of an XML schema document.

For backwards compatibility of applications
written to previous versions of the API, any deployment descriptors
written to comply with earlier versions of the specification, must still
be supported such that applications continue to deploy. For the actual XSD files
please visit `https://jakarta.ee/xml/ns/jakartaee/`.

=== Deployment Descriptor Elements

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

* `ServletContext` Init Parameters
* Session Configuration
* Servlet Declaration
* Servlet Mappings
* Application Lifecyle Listener classes
* Filter Definitions and Filter Mappings
* MIME Type Mappings
* Welcome File list
* Error Pages
* Locale and Encoding Mappings
* Security configuration, including
`login-config`, `security-constraint`, `deny-uncovered-http-methods`,
`security-role`, `security-role-ref` and `run-as`

=== Rules for Processing the Deployment Descriptor

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

* Web containers must remove all leading and
trailing whitespace, which is defined as `S(white space)` in XML 1.0
(http://www.w3.org/TR/2000/WD-xml-2e-20000814), for the element
content of the text nodes of a deployment descriptor.

* The deployment descriptor must be valid
against the schema. Web containers and tools that manipulate web
applications have a wide range of options for checking the validity of a
WAR. This includes checking the validity of the deployment descriptor
document held within.
+
Additionally, it is recommended that web
containers and tools that manipulate web applications provide a level of
semantic checking. For example, it should be checked that a role
referenced in a security constraint has the same name as one of the
security roles defined in the deployment descriptor.
+
In cases of non-conformant web applications,
tools and containers should inform the developer with descriptive error
messages. High-end application server vendors are encouraged to supply
this kind of validity checking in the form of a tool separate from the
container.

* The sub elements under `web-app` can be in an
arbitrary order in this version of the specification. Because of the
restriction of XML Schema, The multiplicity of the elements
`distributable`, `session-config`, `welcome-file-list`, `jsp-config`,
`login-config`, and `locale-encoding-mapping-list` was changed from
`optional` to `0 or more`. The containers must inform the developer with
a descriptive error message when the deployment descriptor contains more
than one element of `session-config`, `jsp-config`, and `login-config`.
The container must concatenate the items in `welcome-file-list` and
`locale-encoding-mapping-list` when there are multiple occurrences. The
multiple occurrence of `distributable` must be treated exactly in the
same way as the single occurrence of `distributable`.

* URI paths specified in the deployment
descriptor are assumed to be in URL-decoded form. The containers must
inform the developer with a descriptive error message when URL contains
`CR(#xD)` or `LF(#xA)`. The containers must preserve all other
characters including whitespace in URL.

* Containers must attempt to canonicalize paths
in the deployment descriptor. For example, paths of the form `/a/../b`
must be interpreted as `/b`. Paths beginning or resolving to paths that
begin with `../` are not valid paths in the deployment descriptor.

* URI paths referring to a resource relative to
the root of the WAR, or a path mapping relative to the root of the WAR,
unless otherwise specified, should begin with a leading `"/"`.

* In elements whose value is an enumerated type,
the value is case sensitive.

=== Deployment Descriptor

The deployment descriptor for this revision
of the specification is available at
`https://jakarta.ee/xml/ns/jakartaee/web-app_{spec-version-underscore}.xsd`


=== Examples

The following examples illustrate the usage
of the definitions listed in the deployment descriptor schema.

==== A Basic Example

.Basic Deployment Descriptor Example

[source,xml,subs="attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
         web-app_{spec-version-underscore}.xsd"
         version="{spec-version}">

  <display-name>A Simple Application</display-name>

  <context-param>
    <param-name>Webmaster</param-name>
    <param-value>webmaster@example.com</param-value>
  </context-param>

  <servlet>
    <servlet-name>catalog</servlet-name>
    <servlet-class>com.example.CatalogServlet</servlet-class>
    <init-param>
      <param-name>catalog</param-name>
      <param-value>Spring</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>catalog</servlet-name>
    <url-pattern>/catalog/*</url-pattern>
  </servlet-mapping>

  <session-config>
    <session-timeout>30</session-timeout>
  </session-config>

  <mime-mapping>
    <extension>pdf</extension>
    <mime-type>application/pdf</mime-type>
  </mime-mapping>

  <welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>

  <error-page>
    <error-code>404</error-code>
    <location>/404.html</location>
  </error-page>

</web-app>
----


==== An Example of Security

.Deployment Descriptor Example Using Security
[source,xml,subs="attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
         web-app_{spec-version-underscore}.xsd"
         version="{spec-version}">

  <display-name>A Secure Application</display-name>

  <servlet>
    <servlet-name>catalog</servlet-name>
    <servlet-class>com.example.CatalogServlet</servlet-class>
    <init-param>
      <param-name>catalog</param-name>
      <param-value>Spring</param-value>
    </init-param>
    <security-role-ref>
      <role-name>MGR</role-name>
      <!-- role name used in code -->
      <role-link>manager</role-link>
    </security-role-ref>
  </servlet>

  <security-role>
    <role-name>manager</role-name>
  </security-role>

  <servlet-mapping>
    <servlet-name>catalog</servlet-name>
    <url-pattern>/catalog/*</url-pattern>
  </servlet-mapping>

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>SalesInfo</web-resource-name>
      <url-pattern>/salesinfo/*</url-pattern>
      <http-method>GET</http-method>
      <http-method>POST</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>manager</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
</web-app>
----


== Requirements related to other Specifications

This chapter lists the requirements for web
containers that are included in products that also include other Jakarta
technologies.

In the following sections any reference to
Jakarta applies to not only the full Jakarta EE profile but also any
profile that includes support for servlet, like the Jakarta Web Profile.
For more information on profiles please refer to the Jakarta EE Platform
Specification.

=== Sessions

Distributed servlet containers that are part
of a Jakarta EE Platform implementation must support the mechanism necessary for
migrating other Jakarta objects from one JVM to another.

=== Web Applications

==== Web Application Class Loader

Servlet containers that are part of a Jakarta EE Platform
product should not allow the application to override Java SE or Jakarta EE
platform classes, such as those in `java.\*`, `javax.*`, and `jakarta.*` namespaces,
that either Java SE or Jakarta EE do not allow to be modified.

[[_Web_Application_Environment]]
==== Web Application Environment

The Jakarta EE Platform defines a naming environment that
allows applications to easily access resources and external information
without explicit knowledge of how the external information is named or
organized.

As servlets are an integral component type of
Jakarta technology, provision has been made in the web application
deployment descriptor for specifying information allowing a servlet to
obtain references to resources and enterprise beans. The deployment
elements that contain this information are:

* `env-entry`
* `ejb-ref`
* `ejb-local-ref`
* `resource-ref`
* `resource-env-ref`
* `service-ref`
* `message-destination-ref`
* `persistence-context-ref`
* `persistence-unit-ref`

The developer uses these elements to describe
certain objects that the web application requires to be registered in
the JNDI namespace in the web container at runtime.

The requirements of the Jakarta environment
with regard to setting up the environment are described in Chapter 5 of
the Jakarta EE Platform Specification.

Servlet containers that are part of a Jakarta
technology-compliant implementation are required to support this syntax.
Consult the Jakarta EE Platform Specification for more details. This type of servlet
container must support lookups of such objects and calls made to those
objects when performed on a thread managed by the servlet container.
This type of servlet container should support this behavior when
performed on threads created by the developer, but are not currently
required to do so. Such a requirement may be added to a future version
of this specification. Developers are cautioned that depending on this
capability for application-created threads is not recommended, as it is
non-portable.

==== JNDI Name for Web Module Context Root URL

The Jakarta EE Platform Specification defines a
standardized global JNDI namespace and a series of related namespaces
that map to various scopes of a Jakarta application. These namespaces
can be used by applications to portably retrieve references to
components and resources. This section defines the JNDI names by which
the base url for a web application is required to be registered.

The name of the pre-defined `java.net.URL`
resource for the context root of a web application has the following
syntax:

`java:global[/<app-name>]/<module-name>!ROOT` in the global namespace
and

`java:app/<module-name>!ROOT` in the application-specific namespace.

Please see section EE 8.1.1 (Component
creation) and EE 8.1.2 (Application assembly) for the rules to determine
the `app-name` and `module-name`.

The `<app-name>` is applicable only when the
web application is packaged within a `.ear` file.

The `java:app` prefix allows a component
executing within a Jakarta application to access an application-specific
namespace. The `java:app` name allows a module in an enterprise
application to reference the context root of another module in the same
enterprise application. The `<module-name>` is a required part of the
syntax for `java:app` url.

.Examples

The above URL can then be used within an
application as follows:

If a web application is deployed standalone
with `module-name` as `myWebApp.` The URL can then be injected into
another web module as follows:

[source,java]
----
@Resource(lookup="java:global/myWebApp!ROOT")
URL myWebApp;
----

When packaged in an ear file named `myApp` it
can be used as follows:

[source,java]
----
@Resource(lookup="java:global/myApp/myWebApp!ROOT")
URL myWebApp;
----

=== Security

This section details the additional security
requirements for web containers when included in a product that also
contains Jakarta Enterprise Beans, Jakarta Authorisation and/or
Jakarta Authentication. The following sections call out the
requirements

==== Propagation of Security Identity in Jakarta Enterprise Bean Calls

A security identity, or principal, must always
be provided for use in a call to an enterprise bean. The default mode in
calls to enterprise beans from web applications is for the security
identity of a web user to be propagated to the Jakarta Enterprise Bea
container.

In other scenarios, web containers are
required to allow web users that are not known to the web container or
to the Jakarta Enterprise Bean container to make calls:

* Web containers are required to support access
to web resources by clients that have not authenticated themselves to
the container. This is the common mode of access to web resources on the
Internet.

* Application code may be the sole processor of
signon and customization of data based on caller identity.

In these scenarios, a web application
deployment descriptor may specify a `run-as` element. When a `run-as`
role is specified for a servlet, the servlet container must propagate a
principal mapped to the role as the security identity in any call from
the servlet to an Jakarta Enterprise Beans, including calls
originating from the servlet’s `init` and `destroy` methods. The
security role name must be one of the security role names defined for
the web application.

For web containers running as part of a Jakarta EE platform,
the use of `run-as` elements must be supported both for
calls to Jakarta Enterprise Bean components within the same Jakarta
application, and for calls to Jakarta Enterprise Bean components
deployed in other Jakarta applications.

==== Container Authorization Requirements

In a Jakarta product or in a product that includes support for Jakarta
Authorization, all servlet containers MUST implement support for
Jakarta Authorization. The Jakarta Authorization Specification is
available for download at
`https://jakarta.ee/specifications/authorization/`

==== Container Authentication Requirements

In a Jakarta product, or a product that includes support for Jakarta
Authentication, all servlet containers MUST implement the Servlet
Container Profile of the Jakarta Authentication specification. The
Jakarta Authentication specification is available for download at
`https://jakarta.ee/specifications/authentication/`

=== Deployment

This section details the deployment
descriptor, packaging and deployment descriptor processing requirements
of a Jakarta EE Platform technology compliant container and products that include
support for JSP and or web services.

==== Deployment Descriptor Elements

The following additional elements exist in the
web application deployment descriptor to meet the requirements of web
containers that are JSP pages enabled or part of a Jakarta application
server. They are not required to be supported by containers wishing to
support only the servlet specification:

* `jsp-config`
* Syntax for declaring resource references (`env-entry`, `ejb-ref`, `ejb-local-ref`, `resource-ref`, `resource-env-ref`)
* Syntax for specifying the message destination(`message-destination`, `message-destination-ref`)
* Reference to a web service (`service-ref`)
* Reference to a Persistence context (`persistence-context-ref`)
* Reference to a Persistence Unit (`persistence-unit-ref`)

The syntax for these elements is now held in
the Jakarta Server Pages specification version 3.0,
and the Jakarta EE Platform specification.

==== Packaging and Deployment of Jakarta XML Web Services Components

Web containers may choose to support running
components written to implement a web service endpoint as defined by the
Jakarta XML Web Services specifications. Web containers embedded in a Jakarta
conformant implementation are required to support Jakarta XML Web Services
web service components. This section describes the packaging and
deployment model for web containers when included in a product which
also supports Jakarta XML Web Services.

Jakarta XML Web Services specification `https://jakarta.ee/specifications/enterprise-ws/`
defines the model for packaging a web service interface with its
associated WSDL description and associated classes. It defines a
mechanism for Jakarta XML Web Services enabled web containers to link to a
component that implements this web service. A Jakarta XML Web Services
implementation component uses the APIs defined by the Jakarta XML Web Services
specification, which defines its contract with the
Jakarta XML Web Services enabled web containers. It is packaged into the
WAR file. The web service developer makes a declaration of this
component using the usual `<servlet>` declaration.

Jakarta XML Web Services enabled web containers must
support the developer in using the web deployment descriptor to define
the following information for the endpoint implementation component,
using the same syntax as for HTTP servlet components using the `servlet`
element. The child elements are used to specify endpoint information in
the following way:

* the `servlet-name` element defines a logical
name which may be used to locate this endpoint description among the
other web components in the WAR

* the `servlet-class` element provides the fully
qualified Java class name of this endpoint implementation

* the `description` element(s) may be used to
describe the component and may be displayed in a tool

* the `load-on-startup` element specifies the
order in which the component is initialized relative to other web
components in the web container

* the `security-role-ref` element may be used to
test whether the authenticated user is in a logical security role

* the `run-as` element may be used to override the identity propagated
to Jakarta Enterprise Beans called by this component

Any servlet initialization parameters defined
by the developer for this web component may be ignored by the container.
Additionally, the Jakarta XML Web Services enabled web component inherits the
traditional web component mechanisms for defining the following
information:

* mapping of the component to the web
container’s URL namespace using the servlet mapping technique

* authorization constraints on web components
using security constraints

* the ability to use servlet filters to provide
low-level byte stream support for manipulating Jakarta XML Web Services
messages using the filter mapping technique

* the time out characteristics of any HTTP
sessions that are associated with the component

* links to Jakarta objects stored in the JNDI
namespace

All of the above requirements can be met
using the pluggability mechanism defined in
<<Pluggability>>.

==== Rules for Processing the Deployment Descriptor

The containers and tools that are part of Jakarta EE Platform
technology-compliant implementation are required to validate the
deployment descriptor against the XML schema for structural correctness.
The validation is recommended, but not required for the web containers
and tools that are not part of a Jakarta EE Platform technology compliant
implementation.

=== Annotations and Resource Injection

The Java Metadata specification (JSR-175),
which is part of J2SE 5.0 and later versions, provides a means of
specifying configuration data in Java code. Metadata in Java code is
also referred to as annotations. In the Jakarta EE Platform, annotations are used to
declare dependencies on external resources and configuration data in
Java code without the need to define that data in a configuration file.

This section describes the behavior of
annotations and resource injection in Jakarta technology compliant
servlet containers. This section expands on the Jakarta EE Platform specification
section 5 titled “Resources, Naming, and Injection”.

Annotations must be supported on container managed classes
that implement the following interfaces and are declared in the web
application deployment descriptor or using the annotations defined in
<<_Annotations_and_pluggability>> or added programmatically.

.Components and Interfaces supporting Annotations and Resource Injection
[caption="Table 15-1  "]
[%breakable]
[cols="20,80", options="header"]
|===
|Component Type
|Classes implementing the following interfaces

|Servlets
|`jakarta.servlet.Servlet`

|Filters
|`jakarta.servlet.Filter`

|Listeners
|`jakarta.servlet.ServletContextListener` +
`jakarta.servlet.ServletContextAttributeListener` +
`jakarta.servlet.ServletRequestListener` +
`jakarta.servlet.ServletRequestAttributeListener` +
`jakarta.servlet.http.HttpSessionListener` +
`jakarta.servlet.http.HttpSessionAttributeListener` +
`jakarta.servlet.http.HttpSessionIdListener` +
`jakarta.servlet.AsyncListener`
|Handlers
|`jakarta.servlet.http.HttpUgradeHandler`
|===

Web containers are not required to perform
resource injection for annotations occurring in classes other than those
listed above in TABLE 15-1.

References must be injected prior to any
lifecycle methods being called and the component instance being made
available the application.

In a web application, classes using resource
injection 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`. Containers may optionally process
resource injection annotations for classes found elsewhere in the
application’s classpath.

==== Handling of metadata-complete

The web application deployment descriptor
contains a `metadata-complete` attribute on the `web-app` element. The
`metadata-complete` attribute defines whether the `web.xml` descriptor
is complete, or whether other sources of metadata used by the deployment
process should be considered. Metadata may come from the `web.xml` file,
`web-fragment.xml` files, annotations on class files in
`WEB-INF/classes`, and annotations on classes in jar files in the
`WEB-INF/lib` directory. If `metadata-complete` is set to `true`,
the deployment tool only examines the `web.xml` file and must ignore
annotations such as `@WebServlet`, `@WebFilter`, and `@WebListener`
present in the class files of the application, and must also ignore any
`web-fragment.xml` descriptor packaged in a jar file in `WEB-INF/lib`.
If the `metadata-complete` attribute is not specified or is set to
`false`, the deployment tool must examine the class files and
`web-fragment.xml` files for metadata, as previously specified.

The `web-fragment.xml` also contains the
`metadata-complete` attribute on the `web-fragment` element. The
attribute defines whether the `web-fragment.xml` descriptor is complete
for the given fragment, or whether the deployment tool should scan for annotations in the
classes in the associated jar file. If `metadata-complete` is set to
`true` the deployment tool only examines the `web-fragment.xml` and
must ignore annotations such as `@WebServlet`, `@WebFilter` and
`@WebListener` present in the class files of the fragment. If
`metadata-complete` is not specified or is set to `false` the
deployment tool must examine the class files for metadata.

Following are the annotations that are
required by a Jakarta technology compliant web container.

==== @DeclareRoles

This annotation is used to define the security
roles that comprise the security model of the application. This
annotation is specified on a class, and it is used to define roles that
could be tested (i.e., by calling `isUserInRole`) from within the
methods of the annotated class. Roles that are implicitly declared as a
result of their use in a `@RolesAllowed` need not be explicitly declared
using the `@DeclareRoles` annotaion. The `@DeclareRoles` annotation may
only be defined in classes implementing the `jakarta.servlet.Servlet`
interface or a subclass thereof.

Following is an example of how this
annotation would be used.

.@DeclareRoles Annotation Example
[source,java]
----
@DeclareRoles("BusinessAdmin")
public class CalculatorServlet extends HttpServlet {
    ...
}
----

Declaring `@DeclareRoles` ("BusinessAdmin")
is equivalent to defining the following in the web.xml.

.@DeclareRoles web.xml
[source,xml]
----
<web-app>
  <security-role>
    <role-name>BusinessAdmin</role-name>
  </security-role>
</web-app>
----

This annotation is not used to relink
application roles to other roles. When such linking is necessary, it is
accomplished by defining an appropriate security-role-ref in the
associated deployment descriptor.

When a call is made to `isUserInRole` from the
annotated class, the caller identity associated with the invocation of
the class is tested for membership in the role with the same name as the
argument to `isCallerInRole`. If a `security-role-ref` has been defined
for the argument role-name the caller is tested for membership in the
role mapped to the `role-name`.

For further details on the `@DeclareRoles`
annotation refer to the Jakarta Annotations for the Jakarta EE Platform
specification section 2.12.

==== @EJB Annotation

Jakarta Enterprise Beans 4.0 components
may be referenced from a web component using the `@EJB` annotation. The
`@EJB` annotation provides the equivalent functionality of declaring the
`ejb-ref` or `ejb-local-ref` elements in the deployment descriptor.
Fields that have a corresponding `@EJB` annotation are injected with the
a reference to the corresponding Jakarta Enterprise Bean component.

An example:

[source,java]
----
@EJB private ShoppingCart myCart;
----

In the case above a reference to the Jakarta Enterprise Bean
component `myCart` is injected as the value of the private field
`myCart` prior to the classs declaring the injection being made
available.

The behavior the `@EJB` annotation is further detailed in section
11.5.1 of the Jakarta Enterprise Bean 4.0 specification.

==== @EJBs Annotation

The `@EJBs` annotation allows more than one
`@EJB` annotations to be declared on a single resource.

An example:

.@EJBs Annotation Example
[source,java]
----
@EJBs({@EJB(Calculator),@EJB(ShoppingCart)})
public class ShoppingCartServlet extends HttpServlet {
    ...
}
----

The example above the Jakarta Enterprise Bean components
`ShoppingCart` and `Calculator` are made available to
`ShoppingCartServlet`. The `ShoppingCartServlet` must still look up
the references using JNDI but the Jakarta Enterprise Beans do not
need to declared in the web.xml file.

==== @Resource Annotation

The `@Resource` annotation is used to declare
a reference to a resource such as a data source, Jakarta Messaging
(JMS) destination, or environment entry. This annotation is equivalent
to declaring a `resource-ref`, `message-destination-ref` or `env-ref`,
or `resource-env-ref` element in the deployment descriptor.

The `@Resource` annotation is specified on a
class, method or field. The container is responsible injecting
references to resources declared by the `@Resource` annotation and
mapping it to the proper JNDI resources. See the Jakarta EE Platform Specification
Chapter 5 for further details.

An example of a @Resource annotation follows:

.@Resource Example
[source,java]
----
@Resource
private javax.sql.DataSource catalogDS;

public getProductsByCategory() {

    // get a connection and execute the query
    Connection conn = catalogDS.getConnection();
    ...
}
----

In the example code above, a servlet, filter,
or listener declares a field `catalogDS` of type `javax.sql.DataSource`
for which the reference to the data source is injected by the container
prior to the component being made available to the application. The data
source JNDI mapping is inferred from the field name `catalogDS` and
type (`javax.sql.DataSource`). Moreover, the `catalogDS` resource no
longer needs to be defined in the deployment descriptor.

The semantics of the `@Resource` annotation
are further detailed in the Jakarta Annotations for the Jakarta EE Platform
specification Section 5.2.5.

==== @PersistenceContext Annotation

This annotation specifies the container
managed entity manager for referenced persistence units.

An example:

.@PersistenceContext Example
[source,java]
----
@PersistenceContext(type=EXTENDED)
EntityManager em;
----

The behavior the `@PersistenceContext`
annotation is further detailed in section 10.5.1 of the Jakarta Persistence
API, Version 3.0.

==== @PersistenceContexts Annotation

The `PersistenceContexts` annotation allows
more than one `@PersistenceContext` to be declared on a resource. The
behavior the `@PersistenceContexts` annotation is further detailed in
section 10.5.1 of the Jakarta Persistence API, version 3.0.

==== @PersistenceUnit Annotation

The `@PersistenceUnit` annotation provides
Jakarta Enterprise Beans components declared in a servlet a reference to a
entity manager factory. The entity manager factory is bound to a
separate persistence.xml configuration file as described in section
11.10 of the Jakarta Enterprise Bean 4.0 specification.

An example:

.@PersistenceUnit Example
[source,java]
----
@PersistenceUnit
EntityManagerFactory emf;
----

The behavior the `@PersistenceUnit` annotation
is further detailed in section 10.5.2 of the Jakarta Persistence API,
version 3.0.

==== @PersistenceUnits Annotation

This annotation allows for more than one
`@PersistentUnit` annotations to be declared on a resource. The behavior
the `@PersistenceUnits` annotation is further detailed in section 10.5.2
of the Jakarta Persistence API, version 3.0.

==== @PostConstruct Annotation

The `@PostConstruct` annotation is declared on
a method that does not take any arguments, and must not throw any
checked exceptions. The return value must be void. The method MUST be
called after the resources injections have been completed and before any
lifecycle methods on the component are called.

An example:

.@PostConstruct Example
[source,java]
----
@PostConstruct
public void postConstruct() {
    ...
}
----

The example above shows a method using the
`@PostConstruct` annotation.

The `@PostConstruct` annotation MUST be
supported by all classes that support dependency injection and called
even if the class does not request any resources to be injected. If the
method throws an unchecked exception the class MUST not be put into
service and no method on that instance can be called.

Refer to the Jakarta EE Platform specification section 2.5
and the Jakarta Annotations specification section 2.5 for more details.

==== @PreDestroy Annotation

The @PreDestroy annotation is declared on a
method of a container managed component. The method is called prior to
component being removed by the container.

An example:

.@PreDestroy Example
[source,java]
----
@PreDestroy
public void cleanup() {
    // clean up any open resources
    ...
}
----

The method annotated with `@PreDestroy` must
return void and must not throw a checked exception. The method may be
public, protected, package private or private. The method must not be
static however it may be final.

Refer to the Jakarta Annotations specification section 2.6 for more
details.

==== @Resources Annotation

The `@Resources` annotation acts as a
container for multiple `@Resource` annotations because the Jakarta MetaData
specification does not allow for multiple annotations with the same name
on the same annotation target.

An example:

.@Resources Example
[source,java]
----
@Resources ({
    @Resource(name="myDB" type=javax.sql.DataSource),
    @Resource(name="myMQ" type=jakarta.jms.ConnectionFactory)
})
public class CalculatorServlet extends HttpServlet {
    ...
}
----

In the example above a JMS connection factory
and a data source are made available to the `CalculatorServlet` by means
of an `@Resources` annotation.

The semantics of the `@Resources` annotation
are further detailed in the Jakarta Annotations specification
specification section 2.0

==== @RunAs Annotation

The `@RunAs` annotation is equivalent to the
`run-as` element in the deployment descriptor. The `@RunAs` annotation
may only be defined in classes implementing the `jakarta.servlet.Servlet`
interface or a subclass thereof.

An example:

.@RunAs Example
[source,java]
----
@RunAs("Admin")
public class CalculatorServlet extends HttpServlet {

    @EJB private ShoppingCart myCart;

    public void doGet(HttpServletRequest, req, HttpServletResponse res) {
        ...
        myCart.getTotal();
        ...
    }

    ...
}
----

The `@RunAs("Admin")` statement would be
equivalent to defining the following in the web.xml.

.@RunAs web.xml Example
[source,xml]
----
<servlet>
  <servlet-name>CalculatorServlet</servlet-name>
  <run-as>Admin</run-as>
</servlet>
----

The example above shows how a servlet uses the
`@RunAs` annotation to propagate the security identity `Admin` to an
Jakarta Enterprise Bean component when the `myCart.getTotal()` method
is called. For further details on propagating identities see
<<Propagation of Security Identity in Jakarta Enterprise Bean Calls>>.

For further details on the `@RunAs` annotation
refer to the Jakarta Annotations specification section 2.7.

==== @WebServiceRef Annotation

The @WebServiceRef annotation provides a
reference to a web service in a web component in same way as a
`resource-ref` element would in the deployment descriptor.

An example:
[source,java]
----
@WebServiceRef
private MyService service;
----

In this example a reference to the web service
`MyService` will be injected to the class declaring the annotation.

This annotation and behavior are further
detailed in the Jakarta XML Web Services Specification section 7.

==== @WebServiceRefs Annotation

This annotation allows for more than one
`@WebServiceRef` annotations to be declared on a single resource. The
behavior of this annotation is further detailed in the Jakarta XML Web Services
Specification.

==== Contexts and Dependency Injection for Jakarta EE Platform Requirements

In a product that supports Contexts and
Dependency Injection (CDI) for Jakarta EE Platform and in which CDI is enabled,
implementations MUST support the use of CDI managed beans. Servlets,
filters, listeners and HttpUpgradeHandlers MUST support CDI injection
and the use of interceptors as described in Section 5.24, "Support
for Dependency Injection" of the Jakarta EE Platform 11 specification.

[appendix]
== Change Log

This document is the final release of the
Jakarta Servlet {spec-version} specification developed under the Jakarta EE Working Group.

=== Changes Since Jakarta Servlet 6.0

link:https://github.com/eclipse-ee4j/servlet-api/issues/59[Issue 59]::
A new attribute, `jakarta.servlet.error.query_string`, has been added to the
attributes that must be set on the request as part of an error dispatch.

link:https://github.com/eclipse-ee4j/servlet-api/issues/74[Issue 74]::
Add additional methods to `HttpServletResponse` to allow the status code used
with the redirect to be chosen and/or the response body used for the redirect to
be controlled.
 
link:https://github.com/eclipse-ee4j/servlet-api/issues/95[Issue 95]::
Clarify that Servlet containers are required to support HTTPS.
 
link:https://github.com/eclipse-ee4j/servlet-api/issues/130[Issue 130]::
Add the `jakarta.servlet.request.secure_protocol` attribute to the list of
request attributes that servlet containers are required to populate if the
request has been transmitted over a secure protocol.
 
link:https://github.com/eclipse-ee4j/servlet-api/issues/159[Issue 159]::
Clarify the behaviour of the various methods for adding headers when passed
`null` or the empty string.
 
link:https://github.com/eclipse-ee4j/servlet-api/issues/164[Issue 164]::
Clarify Javadoc for `ServletResponse` and `HttpServletResponse` methods that are
NO-OPs once the response has been committed.

link:https://github.com/eclipse-ee4j/servlet-api/issues/273[Issue 273]::
Clarify the meaning of "write operation" in the Javadoc for
`ServletOutputStream.isReady()` and, in particular, that this does not include
`ServletOutputStream.close()`, `AsyncContext.complete()` nor any of the
`AsyncContext.dispatch()` methods. Further clarify the Javadoc regarding the
serialization of asynchronous dispatches.

link:https://github.com/eclipse-ee4j/servlet-api/issues/275[Issue 275]::
Containers may provide an option to send redirects using a location header with
a relative URL.

link:https://github.com/eclipse-ee4j/servlet-api/issues/300[Issue 300]::
Correct the wording in section 12.2 since the context path is not always
the empty string when a servlet is mapped using context root mapping.
Also clarify that context root mapping occurs for URIs with or without the
trailing `/`.

link:https://github.com/eclipse-ee4j/servlet-api/issues/316[Issue 316]::
Clarify the behaviour of `HttpServletMapping.getMatchValue()`.

link:https://github.com/eclipse-ee4j/servlet-api/issues/325[Issue 325]::
Clarify the behaviour of `getDateHeader()` and `getIntHeader()` when multiple
headers with the same name are present in the `HttpServletRequest`. The expected
behaviour is aligned with `getHeader()`. 

link:https://github.com/eclipse-ee4j/servlet-api/issues/336[Issue 336]::
Add new constants to `HttpServletResponse` for the HTTP response codes 308, 421,
422 and 426.

link:https://github.com/eclipse-ee4j/servlet-api/issues/415[Issue 415]::
Add overloaded `setCharacterEncoding()` methods that support `Charset`.

link:https://github.com/eclipse-ee4j/servlet-api/issues/431[Issue 431]::
`ServletRequest.getParameter()` and the other parameter methods are now
documented to throw a runtime exception if the call triggers parsing of the
parameters and an error is encountered during that parsing. Containers may
provide container specific options to handle some or all of such errors in
an alternative manner that may include not throwing the runtime exception.  

link:https://github.com/eclipse-ee4j/servlet-api/issues/443[Issue 443]::
Remove references to the SecurityManager and associated APIs.

link:https://github.com/eclipse-ee4j/servlet-api/issues/453[Issue 453]::
Add a security warning and a clarification of canonicalization requirements to
all `ServletContext` methods that accept a path parameter.

link:https://github.com/eclipse-ee4j/servlet-api/issues/463[Issue 463]::
Clarify Javadoc for `MultipartConfigElement` and `MultipartConfig` that sizes
are in bytes.

link:https://github.com/eclipse-ee4j/servlet-api/issues/468[Issue 468]::
Update references to the HTTP RFCs to use the current versions.

link:https://github.com/eclipse-ee4j/servlet-api/issues/469[Issue 469]::
Remove sensitive HTTP headers from responses to `TRACE` requests.

link:https://github.com/eclipse-ee4j/servlet-api/issues/473[Issue 473]::
The Javadoc for `HttpServletRequest.isTrailerFieldsReady()` has been corrected
to correctly describe the default implementation.

link:https://github.com/eclipse-ee4j/servlet-api/issues/484[Issue 484]::
Add ByteBuffer support to `ServletInputStream` and `ServletOutputStream`.

Clarify the expected behavior if the container receives an HTTP request using
the `CONNECT` method.

link:https://github.com/eclipse-ee4j/servlet-api/issues/538[Issue 538]::
Deprecate support for HTTP/2 server push and make implementaing support for this
feature optional.

link:https://github.com/eclipse-ee4j/servlet-api/issues/544[Issue 544]::
Require that all error dispatches are performed as HTTP GET requests with the
original HTTP method being made available via a new request attribute
`jakarta.servlet.error.method`.

link:https://github.com/eclipse-ee4j/servlet-api/issues/546[Issue 546]::
Provide a mechanism to allow applications to interact with the `HttpSession`
object outside of the standard HTTP request processing. This is expected to be
particularly useful to applications using the Jakarta WebSocket API.

link:https://github.com/eclipse-ee4j/servlet-api/issues/571[Issue 571]::
Clarify the behaviour of `Cookie.setAttribute(String,String)` and
`Cookie.getAttribute(String)` with cookie attributes such as `HttpOnly`,
`Secure` and `Partitioned` that do not have a value.

=== Changes Since Jakarta Servlet 5.0

The minimum Java version has been increased to Java 11.

link:https://github.com/eclipse-ee4j/servlet-api/issues/18[Issue 18]::
Clarify the decoding and normalization of URI paths.

link:https://github.com/eclipse-ee4j/servlet-api/issues/37[Issue 37]::
Update Cookie class, related classes and the specification to remove references
to RFC 2109 and to replace them with RFC 6265.

link:https://github.com/eclipse-ee4j/servlet-api/issues/105[Issue 105]::
Clarify the behaviour of `getRealPath(String)`.

link:https://github.com/eclipse-ee4j/servlet-api/issues/133[Issue 133]::
Add support for the HTTP `PATCH` method.

link:https://github.com/eclipse-ee4j/servlet-api/issues/175[Issue 175]::
Provide generic attribute support to cookies, including session cookies, to
provide support for additional attributes such as the `SameSite` attribute.

link:https://github.com/eclipse-ee4j/servlet-api/issues/201[Issue 201]::
Add a `module-info.java` to support using the Servlet API in a modular
environment as per the Java module system and the Jakarta EE 10 
link:https://github.com/jakartaee/specification-committee/blob/master/names.adoc[recommendations].

link:https://github.com/eclipse-ee4j/servlet-api/issues/225[Issue 225]::
Deprecated wrapped response handling in the `doHead` method in favour of container implementation of `HEAD` method behavior.

link:https://github.com/eclipse-ee4j/servlet-api/issues/272[Issue 272]::
Remove the recommendation that Servlet containers should include an `X-Powered-By`header.

link:https://github.com/eclipse-ee4j/servlet-api/issues/365[Issue 365]::
Correct the list of valid orderings for example 2 in <<Ordering of web.xml and web-fragment.xml>>.

link:https://github.com/eclipse-ee4j/servlet-api/issues/368[Issue 368]::
Clarify the behaviour of `getRemoteAddress()`.

link:https://github.com/eclipse-ee4j/servlet-api/issues/377[Issue 377]::
Clarify the behaviour of `setCharacterEncoding(null)` and similar calls.

link:https://github.com/eclipse-ee4j/servlet-api/issues/407[Issue 407]::
Add new methods to obtain unique identifiers for the current request and/or
associated connection. 

link:https://github.com/eclipse-ee4j/servlet-api/issues/411[Issue 411]::
Relax the requirements set out in <<Wrapping Requests and Responses>> and allow
the container to wrap Requests and Responses to meet the requirements of
implementing the `RequestDispatcher` functionality.

link:https://github.com/eclipse-ee4j/servlet-api/issues/416[Issue 416]::
Remove the restriction on programatically added listeners calling some `ServletContext` getter methods.

link:https://github.com/eclipse-ee4j/servlet-api/issues/418[Issue 418]::
Remove API classes and methods that were deprecated in Servlet 5.0 and earlier.
This includes removing the `SingleThreadModel` and `HttpSessionContext`
interfaces and the `HttpUtils` class as well as various deprecated methods.

Add a new method `getErrorOnELNotFound()` to `JspPropertyGroupDescriptor` to
align with changes in the Jakarta Pages 3.1 specification.

Clarify the Javadoc for `ServletRequest.isAsyncStarted()` to align it with the
specification text.

Update the Javadoc to clarify the scheduling implications when `ServletInputStream.isReady()`
or `ServletOutputStream.isReady()` return `false`.

link:https://github.com/eclipse-ee4j/servlet-api/issues/460[Issue 460]::
Reword the description of uncovered HTTP methods for improved clarity.

=== Compatibility with Jakarta Servlet Specification Version 4.0
Jakarta Servlet version 5.0 is only a change of namespaces
(see <<Changes Since Jakarta Servlet 4.0>>).
Thus, migrating a Servlet 4.0 project to Servlet 5.0 and above,
requires the replacement of the namespace `javax.\*` with `jakarta.*`.

=== Changes Since Jakarta Servlet 4.0
The only major change was a change of namespaces.
The `javax.\*` namespaces have been replaced with `jakarta.*`.

[glossary]
== Glossary

[glossary]
Application Developer::

The producer of a web application. The output
of an Application Developer is a set of servlet classes, JSP pages, HTML
pages, and supporting libraries and files (such as images, compressed
archive files, etc.) for the web application. The Application Developer
is typically an application domain expert. The developer is required to
be aware of the servlet environment and its consequences when
programming, including concurrency considerations, and create the web
application accordingly.

 Application Assembler::

Takes the output of the Application Developer
and ensures that it is a deployable unit. Thus, the input of the
Application Assembler is the servlet classes, JSP pages, HTML pages, and
other supporting libraries and files for the web application. The output
of the Application Assembler is a web application archive or a web
application in an open directory structure.

Deployer::

The Deployer takes one or more web application
archive files or other directory structures provided by an Application
Developer and deploys the application into a specific operational
environment. The operational environment includes a specific servlet
container and web server. The Deployer must resolve all the external
dependencies declared by the developer. To perform this role, the
deployer uses tools provided by the Servlet Container Provider.
+
The Deployer is an expert in a specific
operational environment. For example, the Deployer is responsible for
mapping the security roles defined by the Application Developer to the
user groups and accounts that exist in the operational environment where
the web application is deployed.

principal::

A principal is an entity that can be
authenticated by an authentication protocol. A principal is identified
by a _principal name_ and authenticated by using _authentication data_.
The content and format of the principal name and the authentication data
depend on the authentication protocol.

role (development)::

The actions and responsibilities taken by
various parties during the development, deployment, and running of a web
application. In some scenarios, a single party may perform several
roles; in others, each role may be performed by a different party.

role (security)::

An abstract notion used by an Application
Developer in an application that can be mapped by the Deployer to a
user, or group of users, in a security policy domain.

security policy domain::

The scope over which security policies are
defined and enforced by a security administrator of the security
service. A security policy domain is also sometimes referred to as a
_realm_.

security technology domain::

The scope over which the same security
mechanism, such as Kerberos, is used to enforce a security policy.
Multiple security policy domains can exist within a single technology
domain.

Servlet Container Provider::

A vendor that provides the runtime
environment, namely the servlet container and possibly the web server,
in which a web application runs as well as the tools necessary to deploy
web applications.
+
The expertise of the Container Provider is in
HTTP-level programming. Since this specification does not specify the
interface between the web server and the servlet container, it is left
to the Container Provider to split the implementation of the required
functionality between the container and the server.

servlet definition::

A unique name associated with a fully
qualified class name of a class implementing the `Servlet` interface. A
set of initialization parameters can be associated with a servlet
definition.

servlet mapping::

A servlet definition that is associated by a
servlet container with a URL path pattern. All requests to that path
pattern are handled by the servlet associated with the servlet
definition.

System Administrator::

The person responsible for the configuration
and administration of the servlet container and web server. The
administrator is also responsible for overseeing the well-being of the
deployed web applications at run time.
+
This specification does not define the
contracts for system management and administration. The administrator
typically uses runtime monitoring and management tools provided by the
Container Provider and server vendors to accomplish these tasks.

uniform resource locator (URL)::

A compact string representation of resources
available via the network. Once the resource represented by a URL has
been accessed, various operations may be performed on that
resource. footnote:[See RFC 1738]
 A URL is a type of uniform resource
identifier (URI). URLs are typically of the form:
+
--
 <protocol>//<servername>/<resource>
--
+
For the purposes of this specification, we are
primarily interested in HTTP based URLs which are of the form:
+
--
 http[s]://<servername>[:port]/<url-path>[?<query-string>]
--
+
For example:
+
--
 http://www.example.com/products/servlet/index.html

 https://example.com/purchase
--
+
In HTTP-based URLs, the `"/"` character is
reserved to separate a hierarchical path structure in the URL-path
portion of the URL. The server is responsible for determining the
meaning of the hierarchical structure. There is no correspondence
between a URL-path and a given file system path.

web application::

A collection of servlets, JSP pages , HTML
documents, and other web resources which might include image files,
compressed archives, and other data. A web application may be packaged
into an archive or exist in an open directory structure.
+
All compatible servlet containers must accept
a web application and perform a deployment of its contents into their
runtime. This may mean that a container can run the application directly
from a web application archive file or it may mean that it will move the
contents of a web application into the appropriate locations for that
particular container.

web application archive::

A single file that contains all of the
components of a web application. This archive file is created by using
standard JAR tools which allow any or all of the web components to be
signed.
+
Web application archive files are identified
by the `.war` extension. A new extension is used instead of `.jar`
because that extension is reserved for files which contain a set of
class files and that can be placed in the classpath or double clicked
using a GUI to launch an application. As the contents of a web
application archive are not suitable for such use, a new extension was
in order.

web application, distributable::

A web application that is written so that it
can be deployed in a web container distributed across multiple Java
virtual machines running on the same host or different hosts. The
deployment descriptor for such an application uses the `distributable`
element.
