Jetty Logo
Version: 9.2.2-SNAPSHOT
Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery

Chapter 3. Jetty Configuration Introduction

Table of Contents

How to Configure Jetty
What to Configure in Jetty

How to Configure Jetty

To understand Jetty configuration, you need to understand the "How" and the "What". This section covers how to configure Jetty in terms of what mechanisms exist to perform configuration. The next section gives an overview of the action components and fields that you can configure with these mechanisms.

Jetty POJO Configuration

The core components of Jetty are simply Plain Old Java Objects (POJOs); the process of configuring Jetty is mostly the process of instantiating, assembling and setting fields on the Jetty POJOs. You can achieve this either by:

  • Writing Java code to directly instantiate and assemble Jetty objects. This is referred to as Embedding Jetty.

  • Using Jetty XML configuration, which is an Inversion of Control (IoC) framework, to instantiate and assemble Jetty objects as XML objects. The etc/jetty.xml file is the main Jetty XML configuration file, but there are many other etc/jetty-feature.xml files included in the jetty distribution.

  • 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, the Jetty API documentation is the ultimate configuration reference.

Jetty Start Configuration Files

The Jetty distribution uses the following configuration files to instantiate, inject and start server via the start.jar mechanism

ini files

The Jetty Start mechanism uses the command line, the start.ini file and any start.d/*.ini files to create an effective command line of arguments. Arguments may be:

  • XML files in Jetty IoC (or spring) XML format

  • Module activations in the form --module=name

  • Property in the form of name=value, used to parameterize Jetty IoC XML

  • A standard Java property file containing additional start properties

  • Other start.jar options (see java -jar start.jar --help)

  • Some JVM options

Ini files are located in the jetty.base (if different from jetty.home) and are typically edited to change the configuration.

mod files

The modules/*.mod files contain the definition of modules that can be activated by --module=name. Each mod file defines:

  • Module dependencies for ordering and activation

  • The libraries needed by the module to be added to the classpath

  • The XML files needed by the module to be added to the effective command line

  • Files needed by the activated module

  • A template ini file to be used when activating with the --add-to-start=name option

Mod files are normally located in jetty.home, but may be overridden in jetty.base if need be. Typically module files are rarely edited and only for significant structural changes.

XML files

XML files in Jetty or spring IoC format are listed either on the command line, ini files or added to the effective command line by a module definition. The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts. Because Jetty IoC XML files frequently use properties, many common configuration tasks can be accomplished without editing these XML files. If XML configuration changes are required, the XML file should be copied from jetty.home/etc to jetty.base/etc before being modified.

Other Configuration Files

In addition to the start configuration files described above, the configuration of the server can use the following file:

Context XML files

Any XML files in Jetty or spring IoC format that is discovered in the webapps directory are used by the deploy module to instantiate and inject HttpContext instances to create a specific context. These may be standard web applications or bespoke contexts created from special purpose handlers.

web.xml

The Servlet Specification defines the web.xml deployment descriptor that defines and configures the filters, servlets and resources a web application uses. 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.

Normally the web.xml file for a web application is found in the WEB-INF/web.xml location within the war file/directory or as web.xml fragments with jar files found in WEB-INF/lib. Jetty also supports multiple web.xml files so that a default descriptor may be applied before WEB-INF/web.xml (typically set to etc/webdefault.xml by the deploy module) and an override descriptor may be applied after WEB-INF/web.xml (typically set by a context XML file see test.xml)

Property Files

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). You can also plug in other logging frameworks, and also use property files (for example, log4j).

  • As a simple database for login usernames and credentials.

Jetty IoC XML Configuration format

To understand the Jetty IoC XML format, consider the following example of an embedded Jetty server instantiated and configured in java:

Jetty IoC XML allows you to instantiate and configure the exact same server in XML without writing any java code:

In practise, most commonly used Jetty features have XML files that are included in the standard distribution in the etc directory. Thus configuring Jetty is often a matter of just editing existing XML files and altering the configuration values within them.

Configuring the Jetty Distribution

With a normal distribution of Jetty, the configuration mechanisms introduced above are typically used as follows:

$JETTY_HOME/start.ini

Used for global command line options. In the standard Jetty distribution since release 9.1 the contents of start.ini have been moved to modular ini files under the start.d/ .

$JETTY_HOME/start.d

A directory of modular ini files that are used to set the OPTION, parameters and configuration files for key Jetty modules. These modules may be enabled/disabled by renaming the files or since release 9.1 by using the --enable or --disable option of start.jar

$JETTY_HOME/lib/*.xml

Jetty IoC XML files that configure individual features; for example jetty.xml (for the server), jetty-http.xml, jetty-https.xml, jetty-jmx.xml.

$JETTY_HOME/webapps/*

The directory in which standard WAR files, web applications and context IoC XML files are deployed.

Jetty Port Configuration Example

The following example examines the common Jetty configuration mechanism using the HTTP port as an example. To run the Jetty server from the distribution, it is just a matter of running the following command:

> java -jar start.jar

The Jetty distribution uses the start.d/ directory to define what modules, configuration files and properties are defined. The start.d/http.ini module is enabled by default and contains the following lines (among others):

This sets the Jetty port parameter and activates the http module as defined by the modules/http.mod file, which lists the etc/jetty-http.xml configuration file as an effective command line argument. Looking inside that configuration file, we see that it calls addConnector on the server with a new instance of the ServerConnector class. This instance is configured in XML and includes the line:

The effect of this line is to call ServerConnector.setPort(int) with either the value of the jetty.port property if set or with the value 80. We can see from the start.ini except above that the jetty.port property line is set to 8080, so out of the box, the Jetty distribution will use the default 8080 port set inside the start.d/http.ini file.

If you wish to change the port, then the start.d/http.ini file can be edited and the default value there changed to the new port. However this does mean that a file which is part of the Jetty distribution has been modified, which can make future upgrades more difficult. Thus it is normally better to create a jetty.base directory and configure a new instance of a server there.

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-08-30T01:00:27-07:00)