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.

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

Example Jetty Configuration

An example of a Jetty server assembled and configured in embedded style is:

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

You can achieve the exact same server configuration with the Jetty XML file:

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

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

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