Jetty XML Syntax

The Jetty XML syntax is a straightforward mapping of XML elements to a Java API so that POJOs can be instantiated and getters, setters, and methods called.
It is very similar to Inversion Of Control (IOC) or Dependency Injection (DI) frameworks like Spring or Plexus (but it predates all of them).
Typically Jetty XML is used by jetty.xml to configure a Jetty server or by a context.xml file to configure a ContextHandler or subclass, but you can also use the mechanism to configure arbitrary POJOs.

This page describes the basic syntax of Jetty XML configuration. See Jetty XML Usage for information on how you can use and combine Jetty XML.
See configuration files for specific examples.

Basic XML Configuration File Example

The following XML configuration file creates some Java objects and sets some attributes:

Overview

Understanding DTD and Parsing

The document type descriptor
(configure.dtd) describes all valid elements in a Jetty XML configuration file using the Jetty IoC format.
The first two lines of an XML must reference the DTD to be used to validate the XML like:

Typcically a good XML editor will fetch the DTD from the URL and use it to give syntax highlighting and validation while a configuration file is being edited.
Some editors also allows DTD files to be locally cached.
The URL may point to configure.dtd if you want the latest current version, or to a specific version like configure_9_0.dtd if you want a particular validation feature set.

Files that conform to the configure.dtd format are processed in Jetty by the XmlConfiguration class which may also validate the XML (using a version of the DTD from the classes jar file), but is by default run in a forgiving mode that tries to work around validation failures.

Jetty XML Configuration Scope

The configuration of object instances with Jetty IoC XML is done on a scoped basis, so that for any given XML element there is a corresponding Object in scope and the nested XML elements apply to that.
The outer most scope is given by a Configure element and elements like Call, New and Get establish new scopes.
The following example uses the name fields to explain the scope.

Coercing Arguments to a Type

When trying to match XML elements to java elements, Jetty XmlConfiguration may need to coerces values to match method arguments.
By default it does so on a best effort basis, but you can also specify explicit types with the type attribute.
Supported values for type are: String, Character, Short, Byte, Integer, Long, Boolean, Float, Double, char, short, byte, int, long, boolean, float, double, URL, InetAddress, InetAddrPort, and void.

Referring to a Class

If you do not specify the classname, Jetty assumes you are calling the method on the object that is current in scope (eg the object of the surrounding Configure, New or Get clause).
If the class attribute is specified to a fully-qualified class name, then it is either used to create a new instance (Configure and New elements) or is used to access a static (Call, Set or Get elements).

Referring to an Object

You can use the id attribute to store a reference to the current object when first creating or referring to this object.
You can then use the Ref element to reference the object later.
The ID must be unique for each object you create.

Attribute vs Element Style

For XML elements that contain only other XML Elements, there is a choice of using attributes or elements style.
The following is an example of attribute style:

Attribute style has the benefit of brevity, but is limited by: values can only be Strings; multivalued items can not contain ,; values may not be subject to property expansion or other elements that return values.
Thus, the more verbose element style is available and the following is semantically equivalent to the attribute style above:

Note that multivalued elements like Arg must be repeated and may not be comma-separated like they are when provided as attributes.
It is possible to use a mix of styles and the following example shows a moretypical example that uses property expansion as the reason for element style:

Attributes may not be expressed as elements when their parent element is one that contains data.
Thus Arg, Item, Set, Put and Get elements may not have their attributes expressed as elements.

<Configure>

This is the root element that specifies the class of object that is to be configured.
It is usually either the Server, in jetty.xml, or a WebAppContext in jetty-web.xml.

Attribute

Required

Description

id

no

A reference to the object that was created. If you define
multiple Configure elements with the same id,
they will be treated as one object, even if they’re in different files.
You can use this to break up configuration of an object (such as the
Server) across multiple files.

class

no

The fully qualified classname of the object to be
configured. Could be org.eclipse.jetty.server.Server,
org.eclipse.jetty.webapp.WebAppContext, a handler, etc.

Using id to break up configuration of one object across multiple files

<Configure id="Server" class="org.eclipse.jetty.server.Server">
<!-- assumes that you have the basic server configuration set up; this file only contains additional configuration for logging -->
</Configure>

Then run the combined configuration using:

java -jar start.jar etc/jetty.xml jetty-logging.xml

<Set>

A Set element maps to a call to a setter method or field on the current object.
It can contain text and/or elements such as Call, New, SystemProperty, etc., as values.
The name and optional type attributes are used to select the setter method.
If you do not specify a value type, white space is trimmed out of the value.
If it contains multiple elements as values, they are added as strings before being converted to any specified type.

Attribute

Required

Description

name

yes

the name of the setter method to call, or the field to set.
If the name given is xxx, then a setXxx method is used. If the setXxx
method cannot be found, then the xxx field is used.

type

no

the declared type of the argument. See also discussion of
type for Arg for how to define null and empty string values.

class

no

if present, then this Set is treated as a static set method
invocation

<Put>

A Put element maps to a call to a put method on the current object, which must implement the Map interface.
It can contain text and/or elements such as Call, New, SystemProperty, etc. as values.
If you do not specify a no value type, white space is trimmed out of the value.
If it contains multiple elements as values, they are added as strings before being converted to any specified type.

Attribute

Required

Description

name

yes

used as the put key

type

no

forces the type of the value. See also discussion of type for
Arg for how to define null and empty string values.

Example

<Call>

A Call element maps to an arbitrary call to a method on the current object.
It can contain a sequence of Arg elements followed by a sequence of configuration elements, such as Set, Put, Call.
The <Arg>s are passed as arguments to the method; the sequence of configuration elements act on the object returned by the original call.

Attribute

Required

Description

name

yes

the name of the arbitrary method to call. The method called
will use the exact name you provide it.

class

no

if present, then this Call is treated as a static method.

id

no

if present, you can use this id to refer to any object returned
by the call, for later use.

arg

no

comma separated list of arguments may be used for simple
string values rather than Arg elements

<Arg>

An Arg element can be an argument of either a method or a constructor.
Use it within ??? and ???.

It can contain text and/or elements, such as Call, New, SystemProperty, etc., as values.
The optional type attribute can force the type of the value.
If you don’t specify a type, white space is trimmed out of the value.
If it contains multiple elements as values, they are added as strings before being converted to any specified type.
Simple String arguments can also be specified as a string separated arg attribute on the parent element.

Attribute

Required

Description

type

no

force the type of the argument. If you do not provide a value
for the element, if you use type of "String", the value will be the
empty string (""), otherwise it is null.

<New>

Instantiates an object.
Equivalent to new in Java, and allows the creation of a new object.
A New element can contain a sequence of Arg element's, followed by a sequence of configuration elements (Set, Put, etc).
Arg element's are used to select a constructor for the object to be created.
The sequence of configuration elements then acts on the newly-created object.

Attribute

Required

Description

class

yes

fully qualified classname, which determines the type of the
new object that is instantiated.

id

no

gives a unique name to the object which can be referenced later
by Ref elements.

arg

no

comma separated list of arguments may be used for simple
string values rather than Arg elements

Instantiate with Multiple Arguments, Then Configuring Further

<Ref>

A Ref element allows a previously created object to be referenced by a unique id.
It can contain a sequence of elements, such as Set or Put which then act on the referenced object.
You can also use a Ref element as a value for other elements such as Set and Arg.

The Ref element provides convenience and eases readability.
You can usually achieve the effect of the Ref by nesting elements (method calls), but this can get complicated very easily.
The Ref element makes it possible to refer to the same object if you’re using it multiple times, or passing it into multiple methods.
It also makes it possible to split up configuration across multiple files.

<Entry>

Can Contain

<SystemProperty>

A SystemProperty element gets the value of a JVM system property.
It can be used within elements that accept values, such as Set, Put, Arg.

Attribute

Required

Description

name

yes

property name

default

no

a default value as a fallback

id

no

unique identifier which you can use to refer to the array
later.

Can Contain

Only attributes as Elements (Id, Name, Default).

Example

<SystemProperty name="jetty.http.port" default="8080"/>

That is equivalent to:

System.getProperty("jetty.http.port", "8080");

Both try to retrieve the value of jetty.http.port.
If jetty.http.port is not set, then 8080 is used.

<Property>

A Property element allows arbitrary properties to be retrieved by name.
It can contain a sequence of elements, such as Set, Put, Call that act on the retrieved object.

Attribute

Required

Description

name

yes

property name

default

no

a default value as a fallback

id

no

unique identifier which you can use to refer to the array
later.

The Name attribute may be a comma separated list of property names, with the first property name being the "official" name, and the others names being old, deprecated property names that are kept for backward compatibility.
A warning log is issued when deprecated property names are used.
The Default attribute contains the value to use in case none of the property names is found.

Can Contain

The attributes may be expressed as contained Elements (Id, Name, Default).