Eclipse Jetty: Old Documentation

When using JDK 8 or later, you can use the Conscrypt security provider to provide the ALPN service implementation.

Conscrypt binds natively to BoringSSL (a fork of OpenSSL by Google), so ALPN will be supported via the support provided by BoringSSL (bundled together with Conscrypt).

When using Jetty as a standalone server via the Jetty distribution, ALPN is enabled by enabling the conscrypt module.

When using Jetty embedded, ALPN is enabled by the jetty-alpn-conscrypt-client and jetty-alpn-conscrypt-server artifacts, respectively for client usage and server usage. In addition, you also need the Conscrypt artifacts, typically the org.conscrypt:conscrypt-openjdk-uber artifact. All these artifacts must be added to the classpath.

When using JDK 9 or later and Jetty as a standalone server via the Jetty distribution, ALPN support is automatically enabled when the http2 module is enabled. This enables transitively the alpn-9 module which puts the jetty-alpn-java-server artifact in the server classpath, providing the ALPN JDK 9 service implementation.

When using JDK 9 or later and Jetty embedded, the ALPN service implementation is provided by the jetty-alpn-java-client and jetty-alpn-java-server artifacts, respectively for client usage and server usage, and must be added to the classpath.

When starting the Jetty server, especially when using Jetty embedded, it may be possible that you see an error similar to this:

The error means that you don’t have the ALPN dependencies setup correctly in your classpath.

For example, you do not have the jetty-alpn-java-server artifact in the classpath.

If you are using the jetty distribution, then annotations are enabled by default. The annotations module and its transitive dependencies are responsible for making annotation processing available.

Note that annotations that relate to JNDI, such as @Resource and @Resources are enabled via the JNDI module, which is a transitive dependency on the annotations module.

Annotations and JNDI are pre-enabled for the Maven plugin.

To use annotations in an embedded scenario, you will need to include the jetty-annotations jar and all its dependencies onto your classpath. You will also need to include the org.eclipse.jetty.annotations.AnnotationConfiguration class into the list of Configuration classes applied to the org.eclipse.jetty.ee9.webapp.WebAppContext class representing your webapp.

Below is an example application that sets up the standard test-spec.war webapp from the distribution in embedded fashion. It can also be found in the Jetty GitHub repository on the examples/embedded page as ServerWithAnnotations.java. Note that the test-spec.war uses not only annotations, but also JNDI, so this example also enables their processing (via the org.eclipse.jetty.plus.webapp.EnvConfiguration, org.eclipse.jetty.plus.webapp.PlusConfiguration and their related jars).

Unresolved directive in annotations/chapter.adoc - include::using-annotations.adoc[]

You will need to place the following Jetty jar files onto the classpath of your application. You can obtain them from the Jetty distribution, or the Maven repository:

You will also need the asm jar, which you can obtain from this link.

Here’s an example application that sets up a Jetty server, performs some setup to ensure that annotations are scanned, and then deploys a webapp that uses annotations. This example also uses the @Resource annotation which involves JNDI, so we would also add the necessary JNDI jars to the classpath. The example also adds in the configuration classes that are responsible for JNDI (see line 19).

The code is as follows:

On line 19 the configuration classes responsible for setting up JNDI and java:comp/env are added.

On line 20 we add in the configuration class that ensures annotations are inspected.

On lines 30, 33 and 37 JNDI resources that we will be able to reference with @Resource annotations are configured.

With the setup above, a servlet that uses annotations and Jetty will honour the annotations when the webapp is deployed can be created:

Jetty provides configuration options to control the three webapp class loading issues identified above.

You can configure webapp classloading by several methods on the WebAppContext. You can call these methods directly if you are working with the Jetty API, or you can inject methods from a context XML file if you are using the Context Provider ([using-context-provider]). You CANNOT set these methods from a jetty-web.xml file, as it executes after the classloader configuration is set. As a note, jetty-web.xml uses the webapp classpath and not the classpath of the server.

You can add extra classpaths to Jetty in several ways.

If none of the alternatives already described meet your needs, you can always provide a custom classloader for your webapp. We recommend, but do not require, that your custom loader subclasses WebAppClassLoader.

If you do not subclass WebAppClassLoader, we recommend that you implement the ClassVisibilityChecker interface. Without this interface, session persistence will be slower.

You configure the classloader for the webapp like so:

You can also accomplish this in a context xml file.

If you start a Jetty server using a custom class loader–consider the Jetty classes not being available to the system class loader, only your custom class loader–you may run into class loading issues when the WebAppClassLoader kicks in. By default the WebAppClassLoader uses the system class loader as its parent, hence the problem. This is easy to fix, like so:

or

Out of the box, Jetty provides several modules for enabling different types of connectors, from HTTP to HTTPS, HTTP/2, and others. If you startup Jetty with the --list-modules=connector command, you can see a list of all available connector modules:

To enable a connector, simply activate the associated module. Below is an example of activating both the http and https modules in a fresh Jetty base using the start.d directory:

When the http and https modules were activated, so too were any modules they were dependent on, in this case server and ssl, as well as any dependencies for those modules, such as the etc and ketystore directories for ssl.

At this point the server has been configured with connectors for both HTTP and HTTPS and can be started:

When modules are enabled, they are loaded with several default options. These can be changed by editing the associated module ini file in the start.d directory (or the associated lines in server.ini if your implementation does not use start.d). For example, if we examine the http.ini file in our start.d directory created above, we will see the following settings:

To make a change to these settings, uncomment the line (by removing the #) and change the property to the desired value. For example, if you wanted to change the HTTP port to 5231, you would edit the line as follows:

Now when the server is started, HTTP connections will enter on port 5231:

Every module has their own set of configuration options, and reviewing them all is recommended. For additional information on the module system, please refer to our documentation on Startup Modules.

Jetty also provides the means by which to limit connections to the server and/or contexts. This is provided by two different modules in the distribution.

As with the modules listed above, these can be enabled by adding --add-to-start=<module-name> to the command line.

Jetty primarily uses a single connector type called ServerConnector.

Prior to Jetty 9, the type of the connector specified both the protocol and the implementation used; for example, selector-based non blocking I/O vs blocking I/O, or SSL connector vs non-SSL connector. Jetty 9 has a single selector-based non-blocking I/O connector, and a collection of ConnectionFactories now configure the protocol on the connector.

The standard Jetty distribution comes with the following Jetty XML files that create and configure connectors; you should examine them as you read this section:

The services a ServerConnector instance uses are set by constructor injection and once instantiated cannot be changed. Many of the services may be defaulted with null or 0 values so that a reasonable default is used, thus for most purposes only the Server and the connection factories need to be passed to the connector constructor. In Jetty XML (that is, in jetty-http.xml) you can do this by:

You can see the other arguments that can be passed when constructing a ServerConnector in the Javadoc. Typically the defaults are sufficient for almost all deployments.

You can configure connector network settings by calling setters on the connector before it is started. For example, you can set the port with the Jetty XML:

Values in Jetty XML can also be parameterized so that they may be passed from property files or set on the command line. Thus typically the port is set within Jetty XML, but uses the Property element to be customizable:

The network settings available for configuration on the ServerConnector include:

The HttpConfiguration class holds the configuration for HttpChannels, which you can create 1:1 with each HTTP connection or 1:n on a multiplexed HTTP/2 connection. Thus a HttpConfiguration object is injected into both the HTTP and HTTP/2 connection factories. To avoid duplicate configuration, the standard Jetty distribution creates the common HttpConfiguration instance in jetty.xml, which is a Ref element then used in jetty-http.xml, jetty-https.xml and in jetty-http2.xml.

A typical configuration of HttpConfiguration is:

This example HttpConfiguration may be used by reference to the ID “httpConfig”:

This same httpConfig is referenced by the SecuredRedirectHandler when redirecting secure requests. Please note that if your httpConfig does not include a secureScheme or securePort or there is no HttpConfiguration present these types of secured requests will be returned a 403 error.

For SSL-based connectors (in jetty-https.xml and jetty-http2.xml), the common “httpConfig” instance is used as the basis to create an SSL specific configuration with ID “sslHttpConfig”:

This adds a SecureRequestCustomizer which adds SSL Session IDs and certificate information as request attributes.

The SSL/TLS connectors for HTTPS and HTTP/2 require a certificate to establish a secure connection. Jetty holds certificates in standard JVM keystores and are configured as keystore and truststores on a SslContextFactory.Server instance that is injected into an SslConnectionFactory instance. An example using the keystore distributed with Jetty (containing a self signed test certificate) is in jetty-https.xml. Read more about SSL keystores in Configuring SSL.

Often a Connector needs to be configured to accept connections from an intermediary such as a Reverse Proxy and/or Load Balancer deployed in front of the server. In such environments, the TCP/IP connection terminating on the server does not originate from the client, but from the intermediary, so that the Remote IP and port number can be reported incorrectly in logs and in some circumstances the incorrect server address and port may be used.

Thus Intermediaries typically implement one of several de facto standards to communicate to the server information about the original client connection terminating on the intermediary. Jetty supports the X-Forwarded-For header and the Proxy Protocol mechanisms as described below.

If you run Jetty from code as an embedded server (see Embedding), setting the context path is a matter of calling the setContextPath method on the ContextHandler instance (or WebAppContext instance).

If a web application is deployed using the WebAppProvider of the DeploymentManager without an XML IoC file, then the name of the WAR file is used to set the context path:

If a web application is deployed using the WebAppProvider of the DeploymentManager with an XML IoC file to configure the context, then the setContextPath method can be called within that file. For example:

You can also set the context path for webapps by embedding a WEB-INF/jetty-web.xml file in the WAR, which uses the same XML IoC format as the deployer example above. However this is not the preferred method as it requires the web application to be modified.

By default, Jetty will create a temporary directory for each web application. The name of the directory will be of the form:

For example:

Where 0.0.0.0 is the host address, 8080 is the port, test.war is the resourceBase, test is the context path (with / converted to _), any is the virtual host, and randomdigits are a string of digits guaranteed to be unique.

Once the temp directory is created, it is retrievable as the value (as a File) of the context attribute jakarta.servlet.context.tempdir.

There are several ways to use a particular directory as the temporary directory:

It is possible to create a directory named work in the $\{jetty.base} directory. If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in $\{jetty.base}. Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when Jetty exits (or more correctly speaking, the temp directory corresponding to a context is not cleaned up when that context stops).

When a work directory is used, the algorithm for generating the name of the context-specific temp directories omits the random digit string. This ensures the name of the directory remains consistent across context restarts.

Sometimes it is useful to keep the contents of the temporary directory between restarts of the web application. By default, Jetty will not persist the temp directory. To configure Jetty to keep it, use WebAppContext.setPersistTempDirectory(true).

You can use the standard webapp configuration file located in webapp/WEB-INF/web.xml to map errors to specific URLs with the error-page element. This element creates a mapping between the error-code or exception-type to the location of a resource in the web application.

Error code example:

Exception example:

The error page mappings created with the error-page element will redirect to a normal URL within the web application and will be handled as a normal request to that location and thus may be static content, a JSP or a filter and/or servlet. When handling a request generated by an error redirection, the following request attributes are set and are available to generate dynamic content:

You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with web.xml, specifically with the support of error code ranges. Context files are normally located in ${jetty.base}/webapps/ (see DeployerManager for more details) and an example of more flexible error page mapping is below:

If no error page mapping is defined, or if the error page resource itself has an error, then the error page will be generated by an instance of ErrorProcessor configured either the Context or the Server. An ErrorProcessor may extend the ErrorProcessor class and may totally replace the handle method to generate an error page, or it can implement some or all of the following methods to partially modify the error pages:

An ErrorProcessor instance may be set on a Context by calling the ContextHandler.setErrorHandler method. This can be done by embedded code or via context IoC XML. For example:

An ErrorProcessor instance may be set on the entire server by setting it as a dependent bean on the Server instance. This can be done by calling Server.addBean(Object) via embedded code or in jetty.xml IoC XML:

It is possible to get a 'page not found' when a request is made to the server for a resource that is outside of any registered contexts. As an example, you have a domain name pointing to your public server IP, yet no context is registered with Jetty to serve pages for that domain. As a consequence, the server, by default, gives a listing of all contexts running on the server.

One of the quickest ways to avoid this behavior is to create a catch all context. Create a "root" web app mapped to the "/" URI, and use the index.html redirect to whatever place with a header directive.

The methods to invoke are:

This can be done either in a context XML deployment descriptor external to the webapp, or in a jetty-web.xml file in the webapp’s WEB-INF directory.

In either case the syntax of the XML file is the same:

Use the system properties:

This can be set on the command line or in the $JETTY_BASE\start.ini or any $JETTY_BASE\start.d\*.ini module ini file. Using $JETTY_BASE\start.d\server.ini as an example:

Jetty supports deploying Web Applications via XML files which will build an instance of a ContextHandler that Jetty can then deploy.

In a default Jetty installation, Jetty scans its $JETTY_HOME/webapps directory for context deployment descriptor files. To deploy a web application using such a file, simply place the file in that directory.

The deployment descriptor file itself is an xml file that configures a WebAppContext class. For a basic installation only two properties need configured:

For example, here is a descriptor file that deploys the file /opt/myapp/myapp.war to the context path /wiki:

Both SystemProperty and Property elements can be used in the descriptor file. For example, if the system property is set to myapp.home=/opt/myapp, the previous example can be rewritten as:

If the home path for an application needs altered, only the system property needs changed. This is useful if the version of an app is frequently changed.

Official documentation for the for the WebAppContext class lists all the properties that can be set. Here are some examples that configure advanced options in the descriptor file.

This first example tells Jetty not to expand the WAR file when deploying it. This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.

The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it. The setAttribute method can also be used to set a Servlet context attribute. However, since the web.xml for the web application is processed after the deployment descriptor, the web.xml values overwrite identically named attributes from the deployment descriptor.

The following example sets a special web.xml override descriptor. This descriptor is processed after the web application’s web.xml, so it may override identically named attributes. This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.

The next example configures not only the web application context, but also a database connection pool (see Datasource Examples) that the application can then use. If the web.xml does not include a reference to this data source, an override descriptor mechanism (as shown in the previous example) can be used to include it.

There are many other settings that can be changed in a WebAppContext. The javadoc for WebAppContext is a good source of information. Also see the documentation on avoiding zip file exceptions for a description of WebAppContext settings that determine such things as whether or not the war is automatically unpacked during deployment, or whether certain sections of a webapp are copied to a temporary location.

As a webapp is being deployed, a series of org.eclipse.jetty.ee9.webapp.Configuration classes are applied to it, each one performing a specific function. The ordering of these Configurations is significant as subsequent Configurations tend to build on information extracted or setup in foregoing Configurations. These are the default list, in order, of Configurations that are applied to each org.eclipse.jetty.ee9.webapp.WebAppContext:

Before Jetty deploys an application, an AppProvider identifies the App and then provides it to the DeploymentManager. The main AppProvider with the Jetty distribution is the WebAppProvider.

The core feature of the DeploymentManager is the Application LifeCycle Graph.

The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found. These nodes and edges are not hardcoded; they can be adjusted and added to depending on need (for example, any complex requirements for added workflow, approvals, staging, distribution, coordinated deploys for a cluster or cloud, etc.).

New applications enter this graph at the Undeployed node, and the java.lang.String DeploymentManager.requestAppGoal(App,String) method pushes them through the graph.

A set of default AppLifeCycle.Bindings defines standard behavior, and handles deploying, starting, stopping, and undeploying applications. If desired, custom AppLifeCycle.Bindings can be written and assigned anywhere on the Application LifeCycle graph.

Examples of new AppLifeCycle.Binding implementations that can be developed include:

There are four default bindings:

A fifth, non-standard binding, called DebugBinding, is also available for debugging reasons; it logs the various transitions through the Application LifeCycle.

The WebAppProvider is used for the deployment of Web Applications packaged as WAR files, expanded as a directory, or declared in a Jetty Deployable Descriptor XML File. It supports hot (re)deployment.

The basic operation of the WebAppProvider is to periodically scan a directory for deployables. In the standard Jetty Distribution, this is configured in the ${jetty.home}/etc/jetty-deploy.xml file.

The above configuration will create a DeploymentManager tracked as a Server LifeCycle Bean, with the following configuration.

Of course precompiling JSPs is an excellent way to improve the start time of a web application. As of Jetty 9.2 the Apache Jasper JSP implementation has been used and has been augmented to allow the TLD scan to be skipped. This can be done by adding a context-param to the web.xml file (this is done automatically by the Jetty Maven JSPC plugin):

The Jetty start.jar mechanism is a very powerful and flexible mechanism for constructing a classpath and executing a configuration encoded in Jetty XML format. However, this mechanism does take some time to build the classpath. The start.jar mechanism can be bypassed by using the –dry-run option to generate and reuse a complete command line to start Jetty at a later time:

Note that --dry-run may create a properties file in the temp directory and include it on the generated command line. If so, then a copy of the temporary properties file should be taken and the command line updated with it’s new persistent location.

Jetty is decomposed into many jars and dependencies to achieve a minimal footprint by selecting the minimal set of jars. Typically it is best to use something like Maven to manage jars, however this tutorial uses an aggregate Jar that contains all of the required Jetty classes in one Jar. You can manually download the aggregate jetty-all.jar using curl or a browser.

Use curl as follows:

The Embedding Jetty section contains many examples of writing against the Jetty API. This tutorial uses a simple HelloWorld handler with a main method to run the server. You can either download or create in an editor the file HelloWorld.java with the following content:

The following command compiles the HelloWorld class:

The following command runs the HelloWorld example:

You can now point your browser at http://localhost:8080 to see your hello world page.

To learn more about Jetty, take these next steps:

To embed a Jetty server the following steps are typical and are illustrated by the examples in this tutorial:

The following code from SimplestServer.java instantiates and runs the simplest possible Jetty server:

This runs an HTTP server on port 8080. It is not a very useful server as it has no handlers, and thus returns a 404 error for every request.

To produce a response to a request, Jetty requires that you set a Handler on the server. A handler may:

In the previous examples, the Server instance is passed a port number and it internally creates a default instance of a Connector that listens for requests on that port. However, often when embedding Jetty it is desirable to explicitly instantiate and configure one or more Connectors for a Server instance.

Servlets are the standard way to provide application logic that handles HTTP requests. Servlets are similar to a Jetty Handler except that the request object is not mutable and thus cannot be modified. Servlets are handled in Jetty by a ServletHandler. It uses standard path mappings to match a Servlet to a request; sets the requests servletPath and pathInfo; passes the request to the servlet, possibly via Filters to produce a response.

The MinimalServlets example creates a ServletHandler instance and configures a single HelloServlet:

A ContextHandler is a ScopedHandler that responds only to requests that have a URI prefix that matches the configured context path. Requests that match the context path have their path methods updated accordingly and the contexts scope is available, which optionally may include:

The following OneContext example shows a context being established that wraps the HelloHandler:

When many contexts are present, you can embed a ContextHandlerCollection to efficiently examine a request URI to then select the matching ContextHandler(s) for the request. The ManyContexts example shows how many such contexts you can configure:

A ServletContextHandler is a specialization of ContextHandler with support for standard sessions and Servlets. The following OneServletContext example instantiates a DefaultServlet to server static content from /tmp/ and a DumpServlet that creates a session and dumps basic details about the request:

A WebAppContext is an extension of a ServletContextHandler that uses the standard layout and web.xml to configure the servlets, filters and other features from a web.xml and/or annotations. The following OneWebApp example configures the Jetty test webapp. Web applications can use resources the container provides, and in this case a LoginService is needed and also configured:

The typical way to configure an instance of the Jetty server is via jetty.xml and associated configuration files. However the Jetty XML configuration format is just a simple rendering of what you can do in code; it is very simple to write embedded code that does precisely what the jetty.xml configuration does. The LikeJettyXml example following renders in code the behavior obtained from the configuration files:

This example shows how to create a simple file server in Jetty. It is perfectly suitable for test cases where you need an actual web server to obtain a file from, it could easily be configured to serve files from a directory under src/test/resources. Note that this does not have any logic for caching of files, either within the server or setting the appropriate headers on the response. It is simply a few lines that illustrate how easy it is to serve out some files.

This example builds on the Simple File Server to show how chaining multiple ResourceHandlers together can let you aggregate multiple directories to serve content on a single path and how you can link these together with ContextHandlers.

This example shows how to configure Jetty to use multiple connectors, specifically so it can process both http and https requests. Since the meat of this example is the server and connector configuration it only uses a simple HelloHandler but this example should be easily merged with other examples like those deploying servlets or webapps.

This example shows how to wrap one handler with another one that handles security. We have a simple Hello Handler that just return a greeting but add on the restriction that to get this greeting you must authenticate. Another thing to remember is that this example uses the ConstraintSecurityHandler which is what supports the security mappings inside of the servlet api, it could be easier to show just the SecurityHandler usage, but the constraint provides more configuration power. If you don’t need that you can drop the Constraint bits and use just the SecurityHandler.

This example shows the bare minimum required for deploying a servlet into Jetty. Note that this is strictly a servlet, not a servlet in the context of a web application, that example comes later. This is purely just a servlet deployed and mounted on a context and able to process requests. This example is excellent for situations where you have a simple servlet that you need to unit test, just mount it on a context and issue requests using your favorite http client library (like our Jetty client found in [client-http]).

This example shows how to deploy a simple webapp with an embedded instance of Jetty. This is useful when you want to manage the lifecycle of a server programmatically, either within a production application or as a simple way to deploying and debugging a full scale application deployment. In many ways it is easier then traditional deployment since you control the classpath yourself, making this easy to wire up in a test case in Maven and issue requests using your favorite http client library (like our Jetty client found in [client-http]).

This example is very similar to the one in the previous section, although it enables the embedded webapp to use JSPs. As of jetty-9.2, we use the JSP engine from Apache, which relies on a Servlet Specification 3.1 style ServletContainerInitializer to initialize itself. To get this to work with Jetty, you need to enable annotations processing, as shown in this example code:

If you would like to add an example to this list, fork the documentation project from github (see the blue bar at the bottom of this page) and add the new page. Feel free to add the example contents directly as a [source.java] and we will take it from there.

If you feel and example is missing, feel free to open a bug to ask for it. No guarantees, but the more helpful and demonstrative it is the better.

The DefaultServlet implements the ResourceFactory interface and extends the HttpServlet abstract class. It is usually mapped to "/" and provides handling for static content, OPTION and TRACE methods for the context. The MOVE method is allowed if PUT and DELETE are allowed. See the DefaultServlet javadoc.

Jetty supports the following initParameters:

An asynchronous servlet that forwards requests to another server either as a standard web reverse proxy (as defined by RFC2616) or as a transparent reverse proxy. Internally it uses the async jetty-client.

To facilitate JMX monitoring, the HttpClient instance is set as context attribute, prefixed with the servlet’s name and exposed by the mechanism provided by ContextHandler.MANAGED_ATTRIBUTES.

The following init parameters may be used to configure the servlet:

In addition, there are a number of init parameters that can be used to configure the HttpClient instance used internally for the proxy.

The Balancer servlet allows for simple, sticky round robin load balancing leveraging the ProxyServlet that is distributed with Jetty.

In addition to the parameters for ProxyServlet, the following are available for the balancer servlet:

The Denial of Service (DoS) filter limits exposure to request flooding, whether malicious, or as a result of a misconfigured client. The DoS filter keeps track of the number of requests from a connection per second. If the requests exceed the limit, Jetty rejects, delays, or throttles the request, and sends a warning message. The filter works on the assumption that the attacker might be written in simple blocking style, so by suspending requests you are hopefully consuming the attacker’s resources.

Jetty places throttled requests in a queue, and proceed only when there is capacity available.

The header filter sets or adds headers to each response based on an optionally included/excluded list of path specs, mime types, and/or HTTP methods. This filter processes its configured headers before calling doFilter in the filter chain. Some of the headers configured in this filter may get overwritten by other filters and/or the servlet processing the request.

The Jetty GzipHandler is a compression handler that you can apply to any dynamic resource (servlet). It fixes many of the bugs in commonly available compression filters: it works with asynchronous servlets; it handles all ways to set content length. Some user-agents might be excluded from compression to avoid common browser bugs (yes, this means IE!).

The GzipHandler can be added to the entire server by enabling the gzip.mod module. It may also be added to individual contexts in a context xml file.

GzipHandler will gzip the content of a response if:

Compressing the content can greatly improve the network bandwidth usage, but at the cost of memory and CPU cycles. The DefaultServlet is capable of serving pre-compressed static content, which saves memory and CPU.

The GzipHandler installs an output interceptor which passes through to the DefaultServlet. If the content served by DefaultServlet is already compressed, the GzipHandler does nothing; if it is not compressed, the content is compressed on-the-fly.

HTTP requests made from a script are subject to well known restrictions, the most prominent being the same domain policy.

Firefox 3.5 introduced support for W3C’s Access Control for Cross-Site Requests specification, which requires a compliant client (for example, Firefox 3.5) and a compliant server (via this servlet filter).

This filter implements the required bits to support the server-side contract of the specification, and will allow a compliant client to perform cross-domain requests via the standard XMLHttpRequest object. If the client does not issue a compliant cross-domain request, this filter does nothing, and its overhead is the check of the presence of the cross-domain HTTP header.

This is extremely useful in CometD web applications where it is now possible to perform cross-domain long polling without using script injection (also known as the JSONP transport), and therefore removing all the downsides that the JSONP transport has (it’s chattier, does not react quickly to failures, has a message size limit, uses GET instead of POST, etc.).

You will need to put the jetty-servlets.jar file onto your classpath. If you are creating a webapp, ensure that this jar is included in your webapp’s WEB-INF/lib. Or, if you are running Jetty embedded you will need to ensure that jetty-servlets.jar is on the execution classpath. You can download the jetty-servlets.jar from the Maven Central Repository at https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-servlets/. It is also available as part of the Jetty distribution in the $JETTY_HOME/lib directory.

This is a regular servlet filter that must be configured in web.xml.

It supports the following configuration parameters:

A typical configuration could be:

This handler will serve static content and handle If-Modified-Since headers and is suitable for simple serving of static content.

The resource handler has a default stylesheet which you can change by calling setStyleSheet(String location) with the location of a file on the system that it can locate through the resource loading system. The default css is called jetty-dir.css and is located in the jetty-util package, pulled as a classpath resource from the jetty-util jar when requested through the ResourceHandler.

The following is an example of a split fileserver, able to serve static content from multiple directory locations. Since this handler does not return 404’s on content you are able to iteratively try multiple resource handlers to resolve content.

A simple handler that is useful to debug incoming traffic. It will log entry and exit points of HTTP requests as well as the response code.

The debug handler can be added to Jetty by activating the debug module.

Jetty currently has two main statistics collection mechanisms:

The StatisticsHandler and ConnectionStatistics are not included in the default Jetty configuration, these need to be configured manually or enabled using the Jetty stats module on the command line.

In addition to these, the SessionHandler and DefaultSessionCache classes collect statistics for sessions. These statistics are enabled by default and are accessible via JMX interface.

To collect request statistics a StatisticsHandler must be configured as one of the handlers of the server. Typically this can be done as the top level handler, but you may choose to configure a statistics handler for just one context by creating a context configuration file. You can enable the StatisticsHandler by activating the stats modules on the command line.

Alternately, if you are making multiple changes to the Jetty configuration, you could include statistics handler configuration into your own Jetty xml configuration. The following fragment shows how to configure a top level statistics handler:

Detailed statistics on connection duration and number of messages are only collated when a connection is closed. The current and maximum number of connections are the only "live" statistics.

The following example shows how to turn on connection statistics in the Jetty XML format.

A special variant of ConnectionStatistics called IncludeExcludeConnectionStatistics allows you to refine which types of connection you want to collect statistics for.

The following example shows how this can be used to record statistics only for WebSocket connections.

Session handling is built into Jetty for any servlet or webapp context. Detailed statistics on session duration are only collated when a session is closed. The current, minimum, and maximum number of sessions are the only "live" statistics. The session statistics are enabled by default and do not need to be configured.

Controls access to the wrapped handler using the real remote IP. Control is provided by and IncludeExcludeSet over a InetAddressSet. This handler uses the real internet address of the connection, not one reported in the forwarded for headers, as this cannot be as easily forged.

The InetAccess handler can be added to Jetty by activating the inetaccess module.

You can use the MovedContextHandler to relocate or redirect a context that has changed context path and/or virtual hosts.

You can configure it to permanently redirect the old URL to the new URL, in which case Jetty sends a Http Status code of 301 to the browser with the new URL. Alternatively, you can make it non-permanent, in which case Jetty sends a 302 Http Status code along with the new URL.

In addition, as with any other context, you can configure a list of virtual hosts, meaning that this context responds only to requests to one of the listed host names.

Suppose you have a context deployed at /foo, but that now you want to deploy at the root context / instead.

Below is an example. This is a permanent redirection, which also preserves pathinfo and query strings on the redirect:

A handler that shuts the server down on a valid request. This is used to perform "soft" restarts from Java. If _exitJvm is set to true a hard System.exit() call is being made.

This is an example of how you can setup this handler directly with the Server. It can also be added as a part of handler chain or collection.

This is an example that you can use to call the shutdown handler from within java.

A simple handler that is useful to terminate handler chains with a clean fashion. As in the example below, if a resource to be served is not matched within the resource handler the DefaultHandler will take care of producing a 404 page. This class is a useful template to either extend and embrace or simply provide a similar implementation for customizing to your needs. There is also an Error Handler that services errors related to the servlet api specification, so it is best to not get the two confused.

A handler that is used to report errors from servlet contexts and webapp contexts to report error conditions. Primarily handles setting the various servlet spec specific response headers for error conditions. Can be customized by extending; for more information on this see Creating Custom Error Pages.

The standard Jetty distribution bundle contains the jetty-rewrite module, so all you need to do is to enable it using one of the module commands, eg:

The rewrite module enables the following Jetty xml config file on the execution path:

As the commented out code shows, you configure the RewriteHandler by adding various rules.

There is an example of rules configuration in the standard distribution in the demo-base/etc/demo-rewrite-rules.xml file:

There are several types of rules that are written extending useful base rule classes.

The Jetty distribution come with several CDI modules. These modules do not provide CDI, but instead enable one of more integration mechanisms.