Jetty Logo
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. Quick Start Configuration

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

Other Configuration Files

Some Jetty Components do have configuration files that are not IoC.

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.

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.

Start.ini

The Jetty Start mechanism uses an ini file to hold command line arguments that would otherwise have to be passed to the command to start Jetty. The command line and/or ini files can be used to specify additional jetty xml files and can also set Properties that are used the jetty xml files.

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:

package org.eclipse.jetty.embedded;

import org.eclipse.jetty.server.Connector;
import org.eclipse.jetty.server.Handler;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.ServerConnector;
import org.eclipse.jetty.server.handler.DefaultHandler;
import org.eclipse.jetty.server.handler.HandlerCollection;
import org.eclipse.jetty.servlet.ServletContextHandler;

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();
    }
}

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

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.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 refid="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 refid="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 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 to enable/disable Jetty features by setting OPTIONS that setup the classpath, and declaring which configuration files to include on the command line and passing properties to the configuration files.

$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 start.jar mechanism uses the start.ini file in the distribution to define what OPTIONS, configuration files and Properties are defined. The default start.ini file configures a HTTP connector by including the following lines:

#===========================================================
# HTTP Connector
#-----------------------------------------------------------
# jetty.port=8080
etc/jetty-http.xml
#===========================================================

This lists the etc/jetty-http.xml configuration file as a default command line argument when starting the jetty server. 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:

        <Set name="port"><Property name="jetty.port" default="8080" /></Set>

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

If you wish to change the port, then the jetty-http.xml 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. Alternately the Property value can be set in one of several ways. Firstly the Property may be passed on the command line:

> java -jar start.jar jetty.port=9999

This can be convenient if you have a script (like bin/jetty.sh) that builds the command line for you. However, if the start script is located away from the distribution (eg in /etc/init.d) this can separate configuration from the installation, so the start mechanism also allows for any command line argument to be placed in the start.ini, so the jetty.port line can be uncommented in start.ini and the port set there. This works, but now we are modifying a part of the distribution again. If you want to avoid this, then you can create a start.d/myconfig.ini file to include your additional OPTIONS, configuration files and Properties:

> echo jetty.port=9999 > start.d/myconfig.ini
> java -jar start.jar

Finally, if your configuration results in a lot of properties that need to be set and you wish to work with standard property files, then these too can be added on the command line, in start.ini or your own start.d files:

> echo "jetty.port: 9999" > start.d/myconfig.properties
> echo start.d/myconfig.properties > start.d/myconfig.ini
> java -jar start.jar

In summary, Jetty is configured by calling setters and methods on POJO's which can be done either from java code or from Jetty IoC XML files. The XML files can either be edited or parameterised with properties that can be set on the command line or passed via an ini file. The XMLs to use are also set either on the command line and/or with ini files.

See an error or something missing? Contribute to this documentation at Github!