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:

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