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:

Because the main Jetty configuration is done by IoC, the Jetty API documentation is the ultimate configuration reference.

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

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.

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

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.