Jetty Logo
Version: 9.2.3.v20140905
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 35. Reference Section

Table of Contents

Jetty XML Syntax
Jetty XML Usage
jetty.xml
jetty-web.xml
jetty-env.xml
webdefault.xml
Jetty override-web.xml

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:

The XML above is equivalent to the following Java code:

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

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

AttributeRequiredDescription
idno

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.

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

Examples

Basic Example

This is equivalent to:

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

(etc/jetty.xml)

(etc/jetty-logging.xml)

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.

AttributeRequiredDescription
nameyesthe 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.
typenothe declared type of the argument. See also discussion of type for Arg for how to define null and empty string values.
classnoif present, then this Set is treated as a static set method invocation

Examples

Basic Example
Set via a System Property
Creating a NewObject and Setting It on the Server

This is equivalent to:

Invoking a Static Setter

<Get>

A Get element maps to a call to a getter method or field on the current object. It can contain nested elements such as Set, Put, Call, etc.; these act on the object returned by the Get call.

AttributeRequiredDescription
nameyesthe name of the getter method to call, or the field to get. If the name given is xxx, then a getXxx method is used. If the getXxx method cannot be found, then the xxx field is used.
classnof present, then this Get is treated as a static getter or field.
idnoif present, then you can use this id to refer to the returned object later.

Examples

Basic Example

This simple example doesn't do much on its own. You would normally use this in conjunction with a <Ref id="Logger" />.

Invoking a Static Getter and Call Methods on the Returned Object

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

AttributeRequiredDescription
nameyesused as the put key
typenoforces 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.

AttributeRequiredDescription
nameyesthe name of the arbitrary method to call. The method called will use the exact name you provide it.
classnoif present, then this Call is treated as a static method.
idnoif present, you can use this id to refer to any object returned by the call, for later use.

Examples

Basic example

This is equivalent to:

Invoking a static method

which is equivalent to:

Invoking the Actual MethodInstead of Relying on Getter/Setter Magic

which is equivalent to:

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

AttributeRequiredDescription
typenoforce 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.

Examples

Basic examples
Coercing Type

This explicitly coerces the type to a boolean:

As a Parameter

Here are a couple of examples of Arg element being used as a parameter to methods and to constructors:

This is equivalent to:

This is equivalent to:

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

AttributeRequiredDescription
classyesfully qualified classname, which determines the type of the new object that is instantiated.
idnogives a unique name to the object which can be referenced later by Ref elements.

Examples

Basic example

which is equivalent to:

Instantiate with the Default Constructor

which is equivalent to:

Instantiate with Multiple Arguments, Then Configuring Further

which is equivalent to:

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

AttributeRequiredDescription
refidyesthe unique identifier used to name a previously created object.

Examples

Basic example

Use the referenced object as an argument to a method call or constructor:

This is equivalent to:

Manipulating the Object Returned by Ref

This is equivalent to:

Ref vs. Nested Elements

Here is an example of the difference in syntax between using the Ref element, and nesting method calls. They are exactly equivalent:

Here is a more practical example, taken from the handler configuration section in etc/jetty.xml:

<Array>

An Array element allows the creation of a new array.

AttributeRequiredDescription
typenospecify what types of items the array can contain.
idnounique identifier you can use to refer to the array later.

Can Contain

Item element

Example

This is equivalent to:

<Item>

An Item element defines an entry for Array and Map elements.

AttributeRequiredDescription
typenoforce the types of value.
idnounique identifier that you can use to refer to the array later.

<Map>

A Map element allows the creation of a new HashMap and to populate it with (key, value) pairs.

AttributeRequiredDescription
idnounique identifier you can use to refer to the map later.

Can Contain

Entry element

Example

This is equivalent to:

<Entry>

An Entry element contains a key-value Item element pair for a Map.

Can Contain

Item element

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

AttributeRequiredDescription
nameyesproperty name
defaultnoa default value as a fallback
idnounique identifier which you can use to refer to the array later.

Can Contain

Cannot contain anything.

Example

That is equivalent to:

Both try to retrieve the value of jetty.port. If jetty.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.

AttributeRequiredDescription
nameyesproperty name
defaultnoa default value as a fallback
idnounique identifier which you can use to refer to the array later.

Example

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-11-23T01:00:37-08:00)