BACK | INDEX | EXIT | NEXT

# Jetty XML Syntax

Introduction
The Jetty XML syntax provides a very powerful way of configuring all aspects of Jetty. We have seen some examples already in the Jetty Server section in relation to web applications. Here we discuss the syntax in detail, and provide some further examples.
For a precise definition of the format, consult configure_1_2 DTD .
Jetty uses the class org.mortbay.xml.XmlConfiguration to read and interpret all configuration files conforming to the specified format eg

> `$JETTY_HOME/demo/webapps/jetty/WEB-INF/web-jetty.xml`
> `$JETTY_HOME/etc/demo.xml`.

The format provides the ability to express Java API calls declaratively. That is, one can specify in XML syntax the creation of Java objects and method calls upon them.
Syntax
Headers and the Configure Element
All files of this type must conform to this general layout:
`
`

    <?xml version="1.0"  encoding="ISO-8859-1"?>
    <!DOCTYPE Configure PUBLIC
     "-//Mort Bay Consulting//DTD Configure 1.1//EN"
     "http://jetty.mortbay.org/configure_1_2.dtd">

    <Configure class="packagename.classname">

        <!-- Configure clauses here -->

    </Configure>

Example: File format for Jetty XML

The three header lines must always be present in the file, however they are omitted from the examples in the ensuing sections for the sake of clarity.

The contents of the file is applied to an object, which must be an instance of the class named in the `Configure` element. In the case of Jetty, the file is applied to an instance of org.mortbay.jetty.Server (or org.mortbay.jetty.servlet.WebApplicationContext for `web-jetty.xml` ).

Set Element

An attribute set method call on an object is specified with a `Set` statement. The `name` element attribute identifies the object attribute to be set. The content of the element is used as the value to set. The name of the method call to perform is formed by converting the first letter of the object attribute name to uppercase, and prepending it with the word "set" :

    <Set name="attrName">value</Set>

<----
is eqivalent to
---->

    object
     .setAttrName(value);

Example: the Set Element in XML and Java
```
` A best effort attempt is made to convert the string value to the required type of the `Set`. Alternately, a type attribute may be specified:

> `<Set name="doubleAttrName" type="double">1.2</Set>`
> `` Example: using a type specifier

The types supported are:

- String
- Character
- Short
- Byte
- Integer
- Long, Boolean
- Float
- Double
- char
- short
- byte
- int
- long
- boolean
- float
- double
- URL
- InetAddress
- InetAddrPort

For types other than these, a `New` element should be used.

Call Element

A call to an arbitrary method of an object can be made with a `Call` element. The `name` element attribute identifies the method and the content of the element can be zero or more `Arg` elements that provide the arguments to the call:

    <Call name="methodName">
      <Arg type="int">1</Arg>
      <Arg type="String">value2</Arg>
    </Call>

<----
is eqivalent to
---->

    object.methodName(1,
                      "value2");

Example: the Call Element in XML and Java
The values of the `Arg` elements are treated as a `String` if no type is specified. Arbitrary argument types can be passed using a `New` element as the argument value.

If the method call returns an object, it becomes the subject of all further configuration within the bounds of the `Call` element. After the last `Arg` element, `Set`, `Call` and `Put` elements can be included to act on the returned object:

    <Call name="methodName">
      <Arg>value</Arg>
      <Set name="attr">value</Set>
      <Call name="method"/>
    </Call>

<----
is eqivalent to
---->

    Object tmp = object.methodName("value");
    tmp.setAttr("value");
    tmp.method();

Example: the Call Element can return an object
The `Call` elements may be nested to an arbitrary depth:

    <Call name="method1">
      <Call name="method2">
        <Call name="method3"/>
      </Call>
    </Call>

<----
is eqivalent to
---->

    object.method1()
          .method2()
          .method3();

`` Example: nested Call Elements

If a `Call` element has both a `name` and `class` attribute, it is treated as a call to a static method:

    <Call name="method1"
          class="package.classname1">
      <Call name="method2"/>
    </Call>

<----
is eqivalent to
---->

    package.classname1
           .method1()
           .method2();

Example: Making calls to a static method

New Element

To create an instance of a class, use the `New` element. This can only be done as the values for `Set` and `Arg` elements. For example:

    <Call name="methodName">
      <Arg>
        <New class="MyClass1"/>
      </Arg>
      <Set name="attr">
        <New class="MyClass2"/>
      </Set>
    </Call>

<----
is eqivalent to
---->

    object
     .methodName(new MyClass1())
     .setAttr(new MyClass2());

Example: the New Element
The `New` element may itself contain `Arg` elements to be passed to the new call and `Set`, `Call` and `Put` elements which act on the newly created object:
`
`

    <Set name="attr1">
      <New class="MyClass1">
        <Arg>value</Arg>
        <Set name="attr2">
          <New class="MyClass2"/>
        </Set>
      </New>
    </Set>

<----
is eqivalent to
---->

    Object tmp =
      new MyClass1("value");
    tmp.setAttr2(new MyClass2());
    object.setAttr1(tmp);

Example: the New element with arguments
`
`

SystemProperty Element

Java System Properties can be looked up and used as values in `Set` , `Arg` and `Put` elements. This can be used to parameterize configuration files as in:

`
`

> `<Set name="resourceBase">`
> `<SystemProperty name="jetty.home" default="."/>/docroot/`
> `</Set>`

Example: using the jetty.home system property in setting a value

Put Element

A call to a method witht the signature `Object put(Object name, Object value)` can be called with the `Put` element:

`<Put name="name">value</Put>` | <---- is eqivalent to ---->`` | ``object.put("name","value");``

Example: the Put element
Putting it all together
Here is a full Jetty XML configuration file demonstrating several of the most commonly used syntactic constructs described above:

    <?xml version="1.0"  encoding="ISO-8859-1"?>
    <!DOCTYPE Configure PUBLIC
     "-//Mort Bay Consulting//DTD Configure 1.2//EN"
     "http://jetty.mortbay.org/configure_1_2.dtd">

    <Configure class="org.mortbay.jetty.Server">
      <Call name="addListener">
        <Arg>
          <New class="org.mortbay.http.SocketListener">
            <Set name="Port">
              <SystemProperty name="jetty.port" default="8080"/>
            </Set>
            <Set name="MinThreads">5</Set>
            <Set name="MaxThreads">255</Set>
            <Set name="MaxIdleTimeMs">30000</Set>
            <Set name="MaxReadTimeMs">10000</Set>
            <Set name="MaxStopTimeMs">5000</Set>
            <Set name="LowResourcePersistTimeMs">5000</Set>
          </New>
        </Arg>
      </Call>

      <Call name="addWebApplications">
        <Arg></Arg>
        <Arg>
          <SystemProperty name="jetty.home" default="."/>/webapps/
        </Arg>
        <Set name="defaultsDescriptor">
          <SystemProperty name="jetty.home"
           default="."/>/etc/webdefault.xml
        </Set>
      </Call>

    </Configure>

XML Example: an entire Jetty XML configuration file

BACK | INDEX | EXIT | NEXT