HTTP Server Libraries

HttpConnectionFactory creates HttpConnection objects that parse bytes and generate bytes for the HTTP/1.1 protocol.

This is how you configure Jetty to support clear-text HTTP/1.1:

Supporting encrypted HTTP/1.1 (that is, requests with the https scheme) is supported by configuring an SslContextFactory that has access to the KeyStore containing the private server key and public server certificate, in this way:

You can customize the SSL/TLS provider as explained in this section.

It is well known that the HTTP ports are 80 (for clear-text HTTP) and 443 for encrypted HTTP. By using those ports, a client had prior knowledge that the server would speak, respectively, the HTTP/1.x protocol and the TLS protocol (and, after decryption, the HTTP/1.x protocol).

HTTP/2 was designed to be a smooth transition from HTTP/1.1 for users and as such the HTTP ports were not changed. However the HTTP/2 protocol is, on the wire, a binary protocol, completely different from HTTP/1.1. Therefore, with HTTP/2, clients that connect to port 80 (or to a specific Unix-Domain path) may speak either HTTP/1.1 or HTTP/2, and the server must figure out which version of the HTTP protocol the client is speaking.

Jetty can support both HTTP/1.1 and HTTP/2 on the same clear-text port by configuring both the HTTP/1.1 and the HTTP/2 ConnectionFactorys:

Note how the ConnectionFactorys passed to ServerConnector are in order: first HTTP/1.1, then HTTP/2. This is necessary to support both protocols on the same port: Jetty will start parsing the incoming bytes as HTTP/1.1, but then realize that they are HTTP/2 bytes and will therefore upgrade from HTTP/1.1 to HTTP/2.

This configuration is also typical when Jetty is installed in backend servers behind a load balancer that also takes care of offloading TLS. When Jetty is behind a load balancer, you can always prepend the PROXY protocol as described in this section.

When using encrypted HTTP/2, the unencrypted protocol is negotiated by client and server using an extension to the TLS protocol called ALPN.

Jetty supports ALPN and encrypted HTTP/2 with this configuration:

Note how the ConnectionFactorys passed to ServerConnector are in order: TLS, ALPN, HTTP/2, HTTP/1.1.

Jetty starts parsing TLS bytes so that it can obtain the ALPN extension. With the ALPN extension information, Jetty can negotiate a protocol and pick, among the ConnectionFactorys supported by the ServerConnector, the ConnectionFactory correspondent to the negotiated protocol.

The fact that the HTTP/2 protocol comes before the HTTP/1.1 protocol indicates that HTTP/2 is the preferred protocol for the server.

Note also that the default protocol set in the ALPN ConnectionFactory, which is used in case ALPN is not supported by the client, is HTTP/1.1 — if the client does not support ALPN is probably an old client so HTTP/1.1 is the safest choice.

You can customize the SSL/TLS provider as explained in this section.

The HTTP/3 protocol is layered on top of the QUIC protocol, which is based on UDP. This is rather different with respect to HTTP/1 and HTTP/2, that are based on TCP.

Jetty only implements the HTTP/3 layer in Java; the QUIC implementation is provided by the Quiche native library, that Jetty calls via JNA (and possibly, in the future, via the Foreign APIs).

HTTP/3 clients may not know in advance if the server supports QUIC (over UDP), but the server typically supports either HTTP/1 or HTTP/2 (over TCP) on the default HTTP secure port 443, and advertises the availability HTTP/3 as an HTTP alternate service, possibly on a different port and/or on a different host.

For example, an HTTP/2 response may include the following header:

The presence of this header indicates that protocol h3 is available on the same host (since no host is defined before the port), but on port 843 (although it may be the same port 443). The HTTP/3 client may now initiate a QUIC connection on port 843 and make HTTP/3 requests.

It is therefore common for HTTP/3 clients to initiate connections using the HTTP/2 protocol over TCP, and if the server supports HTTP/3 switch to HTTP/3 as indicated by the server.

The code necessary to configure HTTP/2 is described in this section.

To setup HTTP/3, for example on port 843, you need the following code (some of which could be shared with other connectors such as HTTP/2’s):

If not explicitly configured, the TLS implementation is provided by the JDK you are using at runtime.

OpenJDK’s vendors may replace the default TLS provider with their own, but you can also explicitly configure an alternative TLS provider.

The standard TLS provider from OpenJDK is implemented in Java (no native code), and its performance is not optimal, both in CPU usage and memory usage.

A faster alternative, implemented natively, is Google’s Conscrypt, which is built on BoringSSL, which is Google’s fork of OpenSSL.

To use Conscrypt as TLS provider, you must have the Conscrypt jar and the Jetty dependency jetty-alpn-conscrypt-server-12.0.16-SNAPSHOT.jar in the class-path or module-path.

Then, you must configure the JDK with the Conscrypt provider, and configure Jetty to use the Conscrypt provider, in this way:

It is often the case that Jetty receives connections from a load balancer configured to distribute the load among many Jetty backend servers.

From the Jetty point of view, all the connections arrive from the load balancer, rather than the real clients, but is possible to configure the load balancer to forward the real client IP address and IP port to the backend Jetty server using the PROXY protocol.

To support this case, Jetty can be configured in this way:

Note how the ConnectionFactorys passed to ServerConnector are in order: first PROXY, then HTTP/1.1. Note also how the PROXY ConnectionFactory needs to know its next protocol (in this example, HTTP/1.1).

Each ConnectionFactory is asked to create a Connection object for each accepted TCP connection; the Connection objects will be chained together to handle the bytes, each for its own protocol. Therefore the ProxyConnection will handle the PROXY protocol bytes and HttpConnection will handle the HTTP/1.1 bytes producing a request object and response object that will be processed by Handlers.

The load balancer may be configured to communicate with Jetty backend servers via Unix-Domain sockets (requires Java 16 or later). For example:

Note that the only difference when using Unix-Domain sockets is instantiating UnixDomainServerConnector instead of ServerConnector and configuring the Unix-Domain path instead of the IP port.

ContextHandler is a Handler that represents a context for a web application. It is a Handler.Wrapper that performs some action before and after delegating to the nested Handler.

The simplest use of ContextHandler is the following:

The Handler tree structure looks like the following:

Server applications may need to deploy to Jetty more than one web application.

Recall from the introduction that Jetty offers Handler.Collection that contains a sequence of child Handlers. However, this has no knowledge of the concept of context and just iterates through the sequence of Handlers.

A better choice for multiple web application is ContextHandlerCollection, that matches a context from either its context path or virtual host, without iterating through the Handlers.

If ContextHandlerCollection does not find a match, it just returns false from its handle(...) method. What happens next depends on the Handler tree structure: other Handlers may be invoked after ContextHandlerCollection, for example DefaultHandler (see this section). Eventually, if no Handler returns true from their own handle(...) method, then Jetty returns an HTTP 404 response to the client.

The Handler tree structure looks like the following:

Static content such as images or files (HTML, JavaScript, CSS) can be sent by Jetty very efficiently because Jetty can write the content asynchronously, using direct ByteBuffers to minimize data copy, and using a memory cache for faster access to the data to send.

Being able to write content asynchronously means that if the network gets congested (for example, the client reads the content very slowly) and the server stalls the send of the requested data, then Jetty will wait to resume the send without blocking a thread to finish the send.

ResourceHandler supports the following features:

The number of features supported and the efficiency in sending static content are on the same level as those of common front-end servers used to serve static content such as Nginx or Apache. Therefore, the traditional architecture where Nginx/Apache was the front-end server used only to send static content and Jetty was the back-end server used only to send dynamic content is somehow obsolete as Jetty can perform efficiently both tasks. This leads to simpler systems (less components to configure and manage) and more performance (no need to proxy dynamic requests from front-end servers to back-end servers).

This is how you configure a ResourceHandler to create a simple file server:

If you need to serve static resources from multiple directories:

If the resource is not found, ResourceHandler will not return true from the handle(...) method, so what happens next depends on the Handler tree structure. See also how to use DefaultHandler.

ConditionalHandler is an abstract Handler that matches conditions about the request, and allows subclasses to handle the request differently depending on whether the conditions have been met or not.

You may subclass ConditionalHandler.Abstract and override these methods:

Alternatively, you can use the following ConditionalHandler subclasses that implement common behaviors:

Conditions can be specified using an include/exclude mechanism, where a condition match if it is not excluded, and either it is included or the include set is empty.

For example, you can specify to match only the specific HTTP request method DELETE by adding it to the include set; or you can specify to match all HTTP request methods apart TRACE by adding it to the exclude set.

ConditionalHandler allows you to specify conditions for the following request properties:

Notable subclasses of ConditionalHandler are, for example, QoSHandler and ThreadLimitHandler.

GzipHandler provides supports for automatic decompression of compressed request content and automatic compression of response content.

GzipHandler is a Handler.Wrapper that inspects the request and, if the request matches the GzipHandler configuration, just installs the required components to eventually perform decompression of the request content or compression of the response content. The decompression/compression is not performed until the web application reads request content or writes response content.

GzipHandler can be configured at the server level in this way:

The Handler tree structure looks like the following:

However, in less common cases, you can configure GzipHandler on a per-context basis, for example because you want to configure GzipHandler with different parameters for each context, or because you want only some contexts to have compression support:

The Handler tree structure looks like the following:

RewriteHandler provides support for URL rewriting, very similarly to Apache’s mod_rewrite or Nginx rewrite module.

The Maven artifact coordinates are:

RewriteHandler can be configured with a set of rules; a rule inspects the request and when it matches it performs some change to the request (for example, changes the URI path, adds/removes headers, etc.).

The Jetty Server Libraries provide rules for the most common usages, but you can write your own rules by extending the org.eclipse.jetty.rewrite.handler.Rule class.

Please refer to the jetty-rewrite module javadocs for the complete list of available rules.

You typically want to configure RewriteHandler at the server level, although it is possible to configure it on a per-context basis.

The Handler tree structure looks like the following:

SizeLimitHandler tracks the sizes of request content and response content, and fails the request processing with an HTTP status code of 413 Content Too Large.

Server applications can set up the SizeLimitHandler before or after handlers that modify the request content or response content such as GzipHandler. When SizeLimitHandler is before GzipHandler in the Handler tree, it will limit the compressed content; when it is after, it will limit the uncompressed content.

The Handler tree structure look like the following, to limit uncompressed content:

StatisticsHandler gathers and exposes a number of statistic values related to request processing such as:

Server applications can read these values and use them internally, or expose them via some service, or export them to JMX.

StatisticsHandler can be configured at the server level or at the context level.

The Handler tree structure looks like the following:

It is possible to act on those statistics by subclassing StatisticsHandler. For instance, StatisticsHandler.MinimumDataRateHandler can be used to enforce a minimum read rate and a minimum write rate based of the figures collected by the StatisticsHandler:

EventsHandler allows applications to be notified of request processing events.

EventsHandler must be subclassed, and the relevant onXYZ() methods overridden to capture the request processing events you are interested in. The request processing events can be used in conjunction with Request APIs that provide the information you may be interested in.

For example, if you want to use EventsHandler to record processing times, you can use the request processing events with the following Request APIs:

EventsHandler emits the following events:

Your EventsHandler subclass should then be linked in the Handler tree in the relevant position, typically as the outermost Handler after Server:

The Handler tree structure looks like the following:

You can link the EventsHandler at any point in the Handler tree structure, and even have multiple EventsHandlers to be notified of the request processing events at the different stages of the Handler tree, for example:

In the example above, TotalEventsHandler may record the total times of request processing, from SlowHandler all the way to the ContextHandler. On the other hand, AppEventsHandler may record both the time it takes for the request to flow from TotalEventsHandler to AppEventsHandler, therefore effectively measuring the processing time due to SlowHandler, and the time it takes to process the request by the ContextHandler.

Refer to the EventsHandler javadocs for further information.

QoSHandler allows web applications to limit the number of active concurrent requests, that is requests that are currently being handled by a thread, and therefore are not waiting asynchronously, for example reading request content or writing response content.

QoSHandler extends ConditionalHandler, so you may be able to restrict what QoSHandler does to only requests that match the conditions (for example, only to POST requests, or only for certain request URIs, etc.)

Web applications may need to access resources with limited capacity, for example a relational database accessed through a JDBC connection pool. Limiting the number of active concurrent requests helps to control the load on the server, so that it does not become overloaded and possibly unresponsive. In turn, this improves the quality of service (QoS) for end users of the web application, because either their request is being handled actively by the server, or it is rejected sooner (after a configurable timeout in QoSHandler) rather than later (after a possibly longer idle timeout).

Consider the case where each HTTP request results in a JDBC query, and the capacity of the database is of 400 queries/s. Allowing more than 400 HTTP requests/s into the system, for example 500 requests/s, results in 100 requests blocking waiting for a JDBC connection for every second. It is evident that even a short load spike of few seconds eventually results in consuming all the server threads: some will be processing requests and queries, the remaining will be blocked waiting for a JDBC connection. When no more threads are available, additional requests will queue up as tasks in the thread pool, consuming more memory and potentially causing a complete server failure. This situation affects the whole server, so one bad behaving web application may affect other well behaving web applications. From the end user perspective the quality of service is terrible, because requests will take a lot of time to be served and eventually time out.

In cases of load spikes, caused for example by popular events (weather or social events), usage bursts (Black Friday sales), or even denial-of-service attacks, it is desirable to give priority to certain requests rather than others. For example, in an e-commerce site requests that lead to the checkout and to the payments should have higher priorities than requests to browse the products. Another example is to prioritize requests for certain users such as paying users or administrative users.

QoSHandler allows you to configure the maximum number of concurrent requests; by extending QoSHandler you can prioritize suspended requests for faster processing.

A simple example that just limits the number of concurrent requests:

This is an example of a QoSHandler subclass where you can implement a custom prioritization logic:

SecuredRedirectHandler allows to redirect requests made with the http scheme (and therefore to the clear-text port) to the https scheme (and therefore to the encrypted port).

For example a request to http://domain.com:8080/path?param=value is redirected to https://domain.com:8443/path?param=value.

Server applications must configure a HttpConfiguration object with the secure scheme and secure port so that SecuredRedirectHandler can build the redirect URI.

SecuredRedirectHandler is typically configured at the server level, although it can be configured on a per-context basis.

CrossOriginHandler supports the server-side requirements of the CORS protocol implemented by browsers when performing cross-origin requests.

An example of a cross-origin request is when a script downloaded from the origin domain http://domain.com uses fetch() or XMLHttpRequest to make a request to a cross domain such as http://cross.domain.com (a subdomain of the origin domain) or to http://example.com (a completely different domain).

This is common, for example, when you embed reusable components such as a chat component into a web page: the web page and the chat component files are downloaded from http://domain.com, but the chat server is at http://chat.domain.com, so the chat component must make cross-origin requests to the chat server.

This kind of setup exposes to cross-site request forgery (CSRF) attacks, and the CORS protocol has been established to protect against this kind of attacks.

For security reasons, browsers by default do not allow cross-origin requests, unless the response from the cross domain contains the right CORS headers.

CrossOriginHandler relieves server-side web applications from handling CORS headers explicitly. You can set up your Handler tree with the CrossOriginHandler, configure it, and it will take care of the CORS headers separately from your application, where you can concentrate on the business logic.

The Handler tree structure looks like the following:

The most important CrossOriginHandler configuration parameter that must be configured is allowedOrigins, which by default is the empty set, therefore disallowing all origins.

You want to restrict requests to your cross domain to only origins you trust. From the chat example above, the chat server at http://chat.domain.com knows that the chat component is downloaded from the origin server at http://domain.com, so the CrossOriginHandler is configured in this way:

Browsers send cross-origin requests in two ways:

Both preflight requests and cross-origin requests will be handled by CrossOriginHandler, which will analyze the request and possibly add appropriate CORS response headers.

By default, preflight requests are not delivered to the CrossOriginHandler child Handler, but it is possible to configure CrossOriginHandler by setting deliverPreflightRequests=true so that the web application can fine-tune the CORS response headers.

Another important CrossOriginHandler configuration parameter is allowCredentials, which controls whether cookies and authentication headers that match the cross-origin request to the cross domain are sent in the cross-origin requests. By default, allowCredentials=false so that cookies and authentication headers are not sent in cross-origin requests.

If the application deployed in the cross domain requires cookies or authentication, then you must set allowCredentials=true, but you also need to restrict the allowed origins only to the ones your trust, otherwise your cross domain application will be vulnerable to CSRF attacks.

For more CrossOriginHandler configuration options, refer to the CrossOriginHandler javadocs.

StateTrackingHandler is a troubleshooting Handler that tracks whether Handler/Request/Response asynchronous APIs are properly used by applications.</p>

Asynchronous APIs are notoriously more difficult to troubleshoot than blocking APIs, and may be subject to restrictions that applications need to respect (a typical case is that they cannot perform blocking operations).

For example, a Handler implementation whose handle(...) method returns true must eventually complete the callback passed to handle(...) (for more details on the Handler APIs, see this section).

When an application forgets to complete the callback passed to handle(...), the HTTP response may not be sent to the client, but it will be difficult to troubleshoot why the client is not receiving responses.

StateTrackingHandler helps with this troubleshooting because it tracks the callback passed to handle(...) and emits an event if the callback is not completed within a configurable timeout:

By default, events are logged at warning level, but it is possible to specify a listener to be notified of the events tracked by StateTrackingHandler:

Other events tracked by StateTrackingHandler are demand callbacks that block, writes that do not complete their callbacks, or write callbacks that block. The complete list of events is specified by the StateTrackingHandler.Listener class (javadocs).

DefaultHandler is a terminal Handler that always returns true from its handle(...) method and performs the following:

DefaultHandler is set directly on the server, for example:

The Handler tree structure looks like the following:

In the example above, ContextHandlerCollection will try to match a request to one of the contexts; if the match fails, Server will call the DefaultHandler that will return a HTTP 404 with an HTML page showing the existing contexts deployed on the Server.

ThreadLimitHandler tracks remote IP addresses and limits the number of concurrent requests (and therefore threads) for each remote IP address to protect against denial-of-service attacks.

ThreadLimitHandler extends ConditionalHandler, so you may be able to restrict what ThreadLimitHandler does to only requests that match the conditions (for example, only to POST requests, or only for certain request URIs, etc.)

The remote IP address can be derived from the network, or from the Forwarded (or the now obsolete X-Forwarded-For) HTTP header. The Forwarded header is typically present in requests that have been forwarded to Jetty by a reverse proxy such as HAProxy, Nginx, Apache, etc.

Note that ThreadLimitHandler is different from QoSHandler in that it limits the number of concurrent requests per remote IP address, while QoSHandler limits the total number of concurrent requests.

GracefulHandler allows to stop the Jetty server in a graceful way, by rejecting new requests but allowing existing requests to complete within a configurable timeout.

In this way, existing requests can be completed normally rather than with failures caused by the fact that the server is stopping; for example, stopping the server causes all TCP connections to be closed, so trying to write a response will result in a failure.

In order to stop Jetty gracefully, you need the following:

When the Server component is stopped, it will check the Server.stopTimeout, and if positive, it will initiate a graceful shutdown by notifying all components that implement the Graceful interface that the shutdown has been initiated.

GracefulHandler implements Graceful, so it will start rejecting new requests with status code 503 Service Available, but will allow existing requests to complete for a period of time up to Server.stopTimeout.

When all existing requests have completed, the Server stops all Connectors, closes all connections, and finally stops all the components.

This is how you configure and use GracefulHandler:

The Handler tree structure looks like the following:

Handlers are easy to write, but often web applications have already been written using the Servlet APIs, using Servlets and Filters.

ServletContextHandler is a ContextHandler that provides support for the Servlet APIs and implements the behaviors required by the Servlet specification.

However, differently from WebAppContext, it does not require web application to be packaged as a *.war, nor it requires a web.xml for configuration.

With ServletContextHandler you can just put all your Servlet components in a *.jar and configure each component using the ServletContextHandler APIs, in a way equivalent to what you would write in a web.xml.

The Maven artifact coordinates depend on the version of Jakarta EE you want to use, and they are:

For example, for Jakarta EE 10 the coordinates are: org.eclipse.jetty.ee10:jetty-ee10-servlet:12.0.16-SNAPSHOT.

Below you can find an example of how to set up a Jakarta EE 10 ServletContextHandler:

The Handler and Servlet components tree structure looks like the following:

Note how the Servlet components (they are not Handlers) are represented in italic.

Note also how adding a Servlet or a Filter returns a holder object that can be used to specify additional configuration for that particular Servlet or Filter, for example initialization parameters (equivalent to <init-param> in web.xml).

When a request arrives to ServletContextHandler the request URI will be matched against the Filters and Servlet mappings and only those that match will process the request, as dictated by the Servlet specification.

WebAppContext is a ServletContextHandler that autoconfigures itself by reading a web.xml Servlet configuration file.

The Maven artifact coordinates depend on the version of Jakarta EE you want to use, and they are:

Server applications can specify a *.war file or a directory with the structure of a *.war file to WebAppContext to deploy a standard Servlet web application packaged as a war (as defined by the Servlet specification).

Where server applications using ServletContextHandler must manually invoke methods to add Servlets and Filters as described in this section, WebAppContext reads WEB-INF/web.xml to add Servlets and Filters, and also enforces a number of restrictions defined by the Servlet specification, in particular related to class loading.

The Servlet specification requires that a web application class loader must load the web application classes from WEB-INF/classes and WEB_INF/lib. The web application class loader is special because it behaves differently from typical class loaders: where typical class loaders first delegate to their parent class loader and then try to find the class locally, the web application class loader first tries to find the class locally and then delegates to the parent class loader. The typical class loading model, parent-first, is inverted for web application class loaders, as they use a child-first model.

Furthermore, the Servlet specification requires that web applications cannot load or otherwise access the Servlet container implementation classes, also called server classes. Web applications receive the HTTP request object as an instance of the jakarta.servlet.http.HttpServletRequest interface, and cannot downcast it to the Jetty specific implementation of that interface to access Jetty specific features — this ensures maximum web application portability across Servlet container implementations.

Lastly, the Servlet specification requires that other classes, also called system classes, such as jakarta.servlet.http.HttpServletRequest or JDK classes such as java.lang.String or java.sql.Connection cannot be modified by web applications by putting, for example, modified versions of those classes in WEB-INF/classes so that they are loaded first by the web application class loader (instead of the class-path class loader where they are normally loaded from).

WebAppContext implements this class loader logic using a single class loader, WebAppClassLoader, with filtering capabilities: when it loads a class, it checks whether the class is a system class or a server class and acts according to the Servlet specification.

When WebAppClassLoader is asked to load a class, it first tries to find the class locally (since it must use the inverted child-first model); if the class is found, and it is not a system class, the class is loaded; otherwise the class is not found locally. If the class is not found locally, the parent class loader is asked to load the class; the parent class loader uses the standard parent-first model, so it delegates the class loading to its parent, and so on. If the class is found, and it is not a server class, the class is loaded; otherwise the class is not found and a ClassNotFoundException is thrown.

Unfortunately, the Servlet specification does not define exactly which classes are system classes and which classes are server classes. However, Jetty picks good defaults and allows server applications to customize system classes and server classes in WebAppContext.

If you have a Servlet web application, you may want to use a DefaultServlet instead of ResourceHandler. The features are similar, but DefaultServlet is more commonly used to serve static files for Servlet web applications.

The Maven artifact coordinates depend on the version of Jakarta EE you want to use, and they are:

Below you can find an example of how to set up DefaultServlet:

If you wish to serve resources from a non-default location, then ResourceServlet should be used instead of the DefaultServlet.

Below you can find an example of how to set up both a DefaultServlet and a ResourceServlet:

A simple "Hello World" Handler is the following:

Such a simple Handler can access the request and response main features, such as reading request headers and content, or writing response headers and content.

Note how HelloWorldHandler extends from Handler.Abstract.NonBlocking. This is a declaration that HelloWorldHandler does not use blocking APIs (of any kind) to perform its logic, allowing Jetty to apply optimizations (see here) that are not applied to Handlers that declare themselves as blocking.

If your Handler implementation uses blocking APIs (of any kind), extend from Handler.Abstract.

Note how the callback parameter is passed to Content.Sink.write(...) — a utility method that eventually calls Response.write(...), so that when the write completes, also the callback parameter is completed. Note also that because the callback parameter will eventually be completed, the value returned from handle(...) is true.

In this way the Handler contract is fully respected: when true is returned, the callback will eventually be completed.

A filtering Handler is a handler that perform some modification to the request or response, and then either forwards the request to another Handler or produces an error response:

Note how a filtering Handler extends from Handler.Wrapper and as such needs another handler to forward the request processing to, and how the two Handlers needs to be linked together to work properly.

The Request object can be accessed by web applications to inspect the HTTP request URI, the HTTP request headers and read the HTTP request content.

Since the Request object may be wrapped by filtering Handlers, the design decision for the Request APIs was to keep the number of virtual methods at a minimum. This minimizes the effort necessary to write Request wrapper implementations and provides a single source for the data carried by Request objects.

To use the Request APIs, you should look up the relevant methods in the following order:

Below you can find a list of the most common Request features and how to access them. Refer to the Request javadocs for the complete list.

Since Request is-a Content.Source, the section about reading from Content.Source applies to Request as well. The static Content.Source utility methods will allow you to read the request content as a string, or as an InputStream, for example.

There are two special cases that are specific to HTTP for the request content: form parameters (sent when submitting an HTML form) and multipart form data (sent when submitting an HTML form with file upload).

For form parameters, typical of HTML form submissions, you can use the FormFields APIs as shown here:

For multipart form data, typical for HTML form file uploads, you can use the MultiPartFormData.Parser APIs as shown here:

Application may add listeners to the Request object to be notified of particular events happening during the request/response processing.

Request.addIdleTimeoutListener(Predicate<TimeoutException>) allows you to add an idle timeout listener, which is invoked when an idle timeout period elapses during the request/response processing, if the idle timeout event is not notified otherwise.

When an idle timeout event happens, it is delivered to the application as follows:

The idle timeout listeners are therefore invoked only when the application is really idle, neither trying to read nor trying to write.

An idle timeout listener may return true to indicate that the idle timeout should be treated as a fatal failure of the request/response processing; otherwise the listener may return false to indicate that no further handling of the idle timeout is needed from the Jetty implementation.

When idle timeout listeners return false, then any subsequent idle timeouts are handled as above. In the case that the application does not initiate any read or write, then the idle timeout listeners are invoked again after another idle timeout period.

Request.addFailureListener(Consumer<Throwable>) allows you to add a failure listener, which is invoked when a failure happens during the request/response processing.

When a failure happens during the request/response processing, then:

Failure listeners are invoked also in case of idle timeouts, in the following cases:

Failures reported to a failure listener are always fatal failures; see also this section about fatal versus transient failures. This means that it is not possible to read or write from a failure listener: the read returns a fatal failure chunk, and the write will immediately fail the write callback.

Request.addCompletionListener(Consumer<Throwable>) allows you to add a completion listener, which is invoked at the very end of the request/response processing. This is equivalent to adding an HttpStream wrapper and overriding both HttpStream.succeeded() and HttpStream.failed(Throwable).

Completion listeners are typically (but not only) used to recycle or dispose resources used during the request/response processing, or get a precise timing for when the request/response processing finishes, to be paired with Request.getBeginNanoTime().

Note that while failure listeners are invoked as soon as the failure happens, completion listeners are invoked only at the very end of the request/response processing: after the Callback passed to Handler.handle(Request, Response, Callback) has been completed, all container dispatched threads have returned, and all the response writes have been completed.

In case of many completion listeners, they are invoked in the reverse order they have been added.

The Response object can be accessed by web applications to set the HTTP response status code, the HTTP response headers and write the HTTP response content.

The design of the Response APIs is similar to that of the Request APIs, described in this section.

To use the Response APIs, you should look up the relevant methods in the following order:

Below you can find a list of the most common Response features and how to access them. Refer to the Response javadocs for the complete list.

Since Response is-a Content.Sink, the section about writing to Content.Sink applies to Response as well. The static Content.Sink utility methods will allow you to write the response content as a string, or as an OutputStream, for example.

Committing the response means that the response status code and response headers are sent to the other peer, and therefore cannot be modified anymore. Trying to modify them may result in an IllegalStateException to be thrown, as it is an application mistake to commit the response and then try to modify the headers.

You can explicitly commit the response by performing an empty, non-last write:

Jetty can perform important optimizations for the HTTP/1.1 protocol if the response content length is known before the response is committed:

The HTTP protocol (any version) allows applications to write interim responses.

An interim response has a status code in the 1xx range (but not 101), and an application may write zero or more interim response before the final response.

This is an example of writing an interim 100 Continue response:

Note how writing an interim response is as asynchronous operation. As such you must perform subsequent operations using the CompletableFuture APIs, and remember to complete the Handler callback parameter both in case of success or in case of failure.

This is an example of writing an interim 103 Early Hints response:

An interim response may or may not have its own HTTP headers (this depends on the interim response status code), and they are typically different from the final response HTTP headers.

The HTTP/1.1 RFC allows for 1xx informational responses to be sent before a real content response. Unfortunately the servlet specification does not provide a way for these to be sent, so Jetty has had to provide non-standard handling of these headers.

The 100 Continue response should be sent by the server when a client sends a request with an Expect: 100-continue header, as the client will not send the body of the request until the 100 Continue response has been sent.

The intent of this feature is to allow a server to inspect the headers and to tell the client to not send a request body that might be too large or insufficiently private or otherwise unable to be handled.

Jetty achieves this by waiting until the input stream or reader is obtained by the filter/servlet, before sending the 100 Continue response. Thus a filter/servlet may inspect the headers of a request before getting the input stream and send an error response (or redirect etc.) rather than the 100 continues.

RFC 2518 defined the 102 Processing status code that can be sent:

However, a later update of RFC 2518, RFC 4918, removed the 102 Processing status code for "lack of implementation".

Jetty supports the 102 Processing status code. If a request is received with the Expect: 102-processing header, then a filter/servlet may send a 102 Processing response (without terminating further processing) by calling response.sendError(102).