Table of Contents
To understand Jetty Configuration, you need to understand the "How" - what configuration mechanisms exist; and "What" the actual objects and fields that can be configured with those mechanisms.
The main components of Jetty are simply Plain Old Java Objects ( POJOs) and the process of configuring jetty can be considered mostly as the process of instantiating, assembling and setting fields on the Jetty POJOs. This can be achieved either by:
Writing java code to directly instantiate and assemble Jetty objects. This is referred to as ???Jetty.
Using Jetty XML Configuration, which is a Inversion of Control (IoC) framework, to instantiate and assemble Jetty object as XML objects
Using a third party IoC framework like Spring, to instantiate and assemble Jetty objects as spring beans.
Because the main Jetty configuration is done by IoC, it is the Jetty API documentation that is the ultimate configuration reference.
Some Jetty Components do have configuration files that are not IoC
The Servlet Specification defines the web.xml deployment descriptor that defines and configures the Filters, Servlets and resources used by a Web Application. The Jetty WebAppContext component uses this XML format to:
set up the default configuration of a web application context
interpret the application specific configuration supplied with a web application in the WEB-INF/web.xml file
interpret descriptor fragments included in the META-INF directory of jar files within WEB-INF/lib
Standard java property files are also used for jetty configuration in several ways:
to parameterize Jetty IoC XML via the use of the Property element
to configure the default logging mechanism (StdErrLog). Other logging frameworks may also be plugged into jetty and also use property files (eg log4j)
as a simple database for login usernames and credentials
The Jetty start mechanism uses a ini file to hold command line arguments that would otherwise have to be passed to the command to start Jetty.
An example of a Jetty server assembled and configured in embedded style is:
public class ExampleServer { public static void main(String[] args) throws
Exception { Server server = new Server(); ServerConnector connector=new ServerConnector(server);
connector.setPort(8080); server.setConnectors(new Connector[]{connector}); ServletContextHandler context = new
ServletContextHandler(); context.setContextPath("/hello"); context.addServlet(HelloServlet.class,"/");
HandlerCollection handlers = new HandlerCollection(); handlers.setHandlers(new Handler[]{context,new
DefaultHandler()}); server.setHandler(handlers); server.start(); server.join(); } }The exact same server configuration can be achieve with the Jetty XML file:
<?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure id="ExampleServer" class="org.eclipse.jetty.server.Server"> <Set name="connectors"> <Array type="org.eclipse.jetty.server.Connector"> <Item> <New class="org.eclipse.jetty.server.ServerConnector"> <Arg><Ref id="ExampleServer"/></Arg> <Set name="port">8080</Set> </New> </Item> </Array> </Set> <New id="context" class="org.eclipse.jetty.servlet.ServletContextHandler"> <Set name="contextPath">/hello</Set> <Call name="addServlet"> <Arg>org.eclipse.jetty.embedded.HelloServlet</Arg> <Arg>/</Arg> </Call> </New> <Set name="handler"> <New class="org.eclipse.jetty.server.handler.HandlerCollection"> <Set name="handlers"> <Array type="org.eclipse.jetty.server.Handler"> <Item> <Ref id="context" /> </Item> <Item> <New class="org.eclipse.jetty.server.handler.DefaultHandler" /> </Item> </Array> </Set> </New> </Set> </Configure>
In practise, most commonly used Jetty features have had xml files created for them that are included in the standard distribution in the etc directory. Thus configuring Jetty is often a matter of just editing the existing XML files and altering the configuration values within them.
This section gives an overview of the what components of Jetty typically configured using the mechanisms outline in the previous section. The structure of a Jetty server is described in Jetty 7 Architecturewhich is good background reading to understand configuration and is vital to if you wish to change the structure of the server as set up by the default configurations in the jetty distribution. However, for most purposes, configuration is a matter of identifying the correct configuration file and modifying existing configuration values.
The Server instance is the central coordination object of a Jetty server and it provides services and life cycle management for all other jetty server components. In the standard jetty distribution by the core server configuration is in etc/jetty.xml file, but other server configuration may be mixed in (see below). Server configuration can include:
The Server instance provides a ThreadPool instance that is the default Executor service used by other Jetty server components. The prime configuration of the thread pool is the maximum and minimum size and is set in etc/jetty.xml
A Jetty Server can have only a single Handler instance to handle incoming HTTP requests. However a Handler may be a container or wrapper of other handlers forming a tree of handlers that typically handle a request request as a collaboration between the handlers from the a branch of the tree from root to leaf. The default handler tree set up in the etc/jetty.xml file is a Handler Collection containing a Context Handler Collection and the Default Handler. The Context Handler Collection selects the next handler by context path and is where deployed Context Handler and Web Application Contexts are added to the handler tree. The Default Handler handles any requests not already handled and generates the standard 404 page. Other configuration files may add handlers to this tree (eg jetty-rewrite.xml, jetty-requestlog.xml ) or configure components to hot deploy handlers (eg jetty-deploy.xml).
The server holds a generic attribute map of Strings to Objects so that other jetty components may associated named objects with the server and if the value objects implement the LifeCycle interface then they are started and stopped with the server. Typically server attributes are used for holding server-wide default values.
The server also has some specific configuration fields that are set in etc/jetty.xml for controlling among other things, the sending of Dates and Versions in HTTP responses.
A Jetty Server Connector is a network end point that accepts connections for one or more protocols that can produce request and/or messages for the jetty server. In the standard Jetty Server distribution, there are several configuration files provided that add connectors to the server for various protocols and combinations of protocols: jetty-http.xml, jetty-https.xml and jetty-spdy.xml. The configuration needed for connectors is typically:
The TCP/IP port on which the connector listens for connections is set using the the XML Property element which looks up the jetty.port (or jetty.tls.port) property and if not found defaults to 8080 (or 8443 for TLS).
A host may be configured either as a host name or IP address to identify a specific network interface on which to listen. If not set, or set to the value of 0.0.0.0, then all local interfaces are listened on. The XML Property element is used to look up the host value from the jetty.host property.
This is the time in milliseconds that a connection is allowed to be idle before the connector will take actions to close the connection.
Connector types that accept HTTP semantics (including HTTP, HTTPS and SPDY) are configured with a HttpConfiguration instance that contains common HTTP configuration that is independent of the specific wire protocol used. Because these values are often common to multiple connector types, the standard Jetty Server distribution creates a single HttpConfiguration in the jetty.xml file which is used via the XML Ref element in the specific connector files.
The TLS connector types (HTTPS and SPDY) configure an SSL Context Factory with the location of the server keystore and truststore for obtaining server certificates.
Virtual Hosts are not configured on Connectors. Individual Contexts must be configured with the virtual hosts to which they respond.
Prior to Jetty-9, the type of the connector was chosen to reflect both the protocol supported (e.g. HTTP, HTTPS, AJP, SPDY) and the nature of the implementation (e.g. NIO or BIO). From Jetty-9 onwards there is only one prime Connector type (ServerConnector), which is NIO based and uses Connection Factories to be able to handle one or more protocols.
The Jetty deployer is a service object that scans a directory for contexts and web applications to hot deploy (see quickstart). A context is an instance of ContextHandler that aggregates other handlers with common resources for handling HTTP requests (eg resource base, class loader, configuration attributes). A standard Web Application is a specialized instance of a Context that uses standard layouts and web.xml deployment descriptors to configure the context.
In the standard Jetty distribution the deployer is configured by jetty-deploy.xml and scans the webapps directory.