<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
</head>
<body>
<br>
<table cellpadding="0" cellspacing="8" border="0" width="20%">
<tbody>
<tr>
<td valign="middle" bgcolor="#ccccff"><small><a
href="logging.html"> BACK</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a
href="index.html"> INDEX</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a
href=".."> EXIT</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a
href="other.html"> NEXT</a></small></td>
</tr>
</tbody>
</table>
<br>
<h1>Jetty XML Syntax</h1>
<big><big><b><a name="Introduction"></a>Introduction</b></big></big><br>
<br>
The Jetty XML syntax provides a very powerful way of configuring
all aspects of Jetty. We have seen some examples already in the <a
href="Server.html"> Jetty Server</a> section in relation to web applications.
Here we discuss the syntax in detail, and provide some further examples.<br>
<br>
For a precise definition of the format, consult <a
href="/configure_1_2.dtd"> configure_1_2 DTD</a> . <br>
<br>
Jetty uses the class <a
href="/javadoc/org/mortbay/xml/XmlConfiguration.html"> org.mortbay.xml.XmlConfiguration</a>
to read and interpret all configuration files conforming to the specified
format eg <br>
<blockquote><tt>$JETTY_HOME/demo/webapps/jetty/WEB-INF/web-jetty.xml</tt><br>
<tt>$JETTY_HOME/etc/demo.xml</tt>.<br>
</blockquote>
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.<br>
<br>
<br>
<big><big><b><a name="syntax"></a>Syntax</b></big></big><br>
<br>
<big><b><a name="header"></a>Headers and the Configure Element</b></big><br>
<br>
All files of this type must conform to this general layout: <br>
<tt><br>
<br>
</tt>
<table cellpadding="2" cellspacing="2" border="0" width="90%"
align="center">
<tbody>
<tr>
<td valign="top">
<pre><tt><?xml version="1.0" encoding="ISO-8859-1"?><br><!DOCTYPE Configure PUBLIC </tt><tt> <br> "-//Mort Bay Consulting//DTD Configure 1.1//EN"<br> "http://jetty.mortbay.org/configure_1_2.dtd"></tt></pre>
<pre><tt><Configure class="packagename.classname"> </tt></pre>
<pre><tt> <!-- Configure clauses here --></tt></pre>
<pre><tt></Configure></tt></pre>
<br>
</td>
</tr>
<tr>
<td valign="top"><b>Example: File format for Jetty XML</b><br>
</td>
</tr>
</tbody>
</table>
<br>
<br>
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.
<p> The contents of the file is applied to an object, which must be an instance
of the class named in the <code>Configure</code> element. In the case
of Jetty, the file is applied to an instance of <a
href="/javadoc/org/mortbay/jetty/Server.html"> org.mortbay.jetty.Server</a>
(or <a
href="/javadoc/org/mortbay/jetty/servlet/WebApplicationContext.html">
org.mortbay.jetty.servlet.WebApplicationContext</a> for <tt>web-jetty.xml</tt>
). </p>
<p> <font size="+1"><b><br>
<a name="set"></a>Set Element</b></font></p>
<p> An attribute set method call on an object is specified with a
<code> Set</code> statement. The <code>name</code> 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" : </p>
<table border="0" width="90%" cellpadding="4" cellspacing="2"
align="center">
<tbody>
<tr>
<td width="35%"><small> </small>
<pre><small><Set name="attrName">value</Set></small></pre>
<small> </small></td>
<td align="center" valign="middle" width="20%"><small><----
<i><br>
is eqivalent to</i> <br>
----></small> </td>
<td width="25%">
<pre>object<br> .setAttrName(value);</pre>
</td>
</tr>
</tbody>
</table>
<br>
<b>Example: the Set Element in XML
and Java<br>
</b>
<code></code><code><br>
</code>A best effort attempt is made to convert
the string value to the required type of the <tt>Set</tt>. Alternately,
a type attribute may be specified: <br>
<blockquote><tt><Set name="doubleAttrName" type="double">1.2</Set></tt><br>
<br>
<tt> </tt><b>Example: using a type specifier</b><br>
</blockquote>
<br>
The types supported are:<br>
<ul>
<li>String</li>
<li>Character</li>
<li>Short</li>
<li>Byte</li>
<li>Integer</li>
<li>Long, Boolean</li>
<li>Float</li>
<li>Double</li>
<li>char</li>
<li>short</li>
<li>byte</li>
<li>int</li>
<li>long</li>
<li>boolean</li>
<li>float</li>
<li>double</li>
<li>URL</li>
<li>InetAddress</li>
<li>InetAddrPort</li>
</ul>
<br>
For types other than these, a <a href="#new"><code>New</code>
element</a> should be used.
<p> <font size="+1"><b><br>
<a name="call"></a>Call Element</b></font></p>
<p> A call to an arbitrary method of an object can be made with a
<code> Call</code> element. The
<code>name</code> element attribute identifies the method and
the content of the element can be zero or more <code> Arg</code>
elements that provide the arguments to the call:</p>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="0" width="80%"
align="center">
<tbody>
<tr>
<td valign="middle"
width="35%">
<pre><small><tt><Call name="methodName"><br> <Arg type="int">1</Arg><br> <Arg type="String">value2</Arg><br></Call></tt></small></pre>
<small> </small></td>
<td valign="middle"
align="center"><small> <---- <br>
<i>is eqivalent to</i> <br>
----></small><br>
</td>
<td valign="middle"
width="40%">
<pre><code>object.methodName(1,<br> "value2");</code></pre>
</td>
</tr>
</tbody>
</table>
<br>
<div align="center"><b>Example: the Call Element in XML and Java</b><br>
</div>
<br>
The values of the <code>Arg</code> elements are treated as a <tt>String</tt>
if no type is specified. Arbitrary argument types can be passed using
a <a href="#new"><code> New</code> element</a> as the argument
value.
<p> If the method call returns an object, it becomes the subject of all
further configuration within the bounds of the <code>Call</code> element.
After the last <code>Arg</code> element, <code>Set</code>,
<code> Call</code> and <a href="#put"><code> Put</code></a> elements
can be included to act on the returned object:</p>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="0" width="90%"
align="center">
<tbody>
<tr>
<td
valign="top">
<pre><small><tt><Call name="methodName"><br> <Arg>value</Arg><br> <Set name="attr">value</Set><br> <Call name="method"/><br></Call></tt></small></pre>
</td>
<td
valign="middle" align="center"><small> <---- <i> <br>
is eqivalent to</i> <br>
----></small><br>
</td>
<td
valign="middle" align="left">
<pre><small><tt>Object tmp = object.methodName("value");<br>tmp.setAttr("value");<br>tmp.method();</tt></small></pre>
</td>
</tr>
</tbody>
</table>
<br>
<div align="center"><b>Example: the Call Element can return an object</b><br>
</div>
<br>
<br>
<br>
The <code>Call</code> elements may be nested to an arbitrary
depth: <br>
<br>
<table cellpadding="2" cellspacing="2" border="0" width="80%"
align="center">
<tbody>
<tr>
<td
valign="top">
<pre><tt><small><Call name="method1"><br> <Call name="method2"><br> <Call name="method3"/><br> </Call><br></Call></small><br></tt></pre>
</td>
<td
valign="middle" align="center"><small> <---- <i> <br>
is eqivalent to</i> <br>
----></small><br>
</td>
<td
valign="middle" align="left">
<pre><code>object.method1()<br> .method2()<br> .method3()</code>;</pre>
</td>
</tr>
</tbody>
</table>
<br>
<div align="center">
<code></code> <b>Example:
nested Call Elements</b></div>
<p> If a
<code> Call</code> element has both a <tt>name</tt> and <tt>class</tt>
attribute, it is treated as a call to a static method:</p>
<br>
<table cellpadding="2" cellspacing="2" border="0" width="90%"
align="center">
<tbody>
<tr>
<td valign="top" width="25%">
<pre><tt><Call name="method1" <br> class="package.classname1"><br> <Call name="method2"/><br></Call></tt></pre>
</td>
<td valign="middle" align="center" width="20%"><small> <----
<i><br>
is eqivalent to</i> <br>
----></small><br>
</td>
<td valign="middle" align="left" width="40%">
<pre><tt>package.classname1<br> .method1()<br> .method2();</tt></pre>
</td>
</tr>
</tbody>
</table>
<br>
<div align="center"><b> Example: Making calls to a static method</b><br>
</div>
<br>
<br>
<br>
<p> <font size="+1"><b><a name="new"></a>New Element</b></font></p>
<p> To create an instance of a class, use the <code>New</code>
element. This can only be done as the values for <code>Set</code> and
<code>Arg</code> elements. For example: </p>
<br>
<table cellpadding="2" cellspacing="2" border="0" width="80%"
align="center">
<tbody>
<tr>
<td valign="top" width="35%">
<pre><tt><Call name="methodName"><br> <Arg><br> <New class="MyClass1"/><br> </Arg><br> <Set name="attr"><br> <New class="MyClass2"/><br> </Set><br></Call></tt></pre>
</td>
<td valign="middle" align="center" width="20%"><small> <----
<br>
<i> is eqivalent to</i></small><br>
----><br>
</td>
<td valign="middle">
<pre><code>object<br> .methodName(new MyClass1())<br> .setAttr(new MyClass2())</code>;</pre>
</td>
</tr>
</tbody>
</table>
<br>
<div align="center"><b> Example: the New Element</b><br>
</div>
<br>
The <code>New</code> element may itself contain <code> Arg</code>
elements to be passed to the new call and <code>Set</code>, <code>
Call</code> and <a href="#put"><code>Put</code></a> elements which
act on the newly created object: <br>
<tt><br>
</tt>
<table cellpadding="4" cellspacing="2" border="0" width="80%"
align="center">
<tbody>
<tr>
<td valign="top">
<pre><tt><</tt><tt>Set name="attr1"><br> <New class="MyClass1"><br> <Arg>value</Arg><br> <Set name="attr2"><br> <New class="MyClass2"/><br> </Set><br> </New><br></Set></tt></pre>
</td>
<td valign="middle" align="center"
width="20%"><small> <---- <br>
<i>is eqivalent to</i></small> <br>
----><br>
</td>
<td valign="middle">
<pre><tt>Object tmp = <br> new MyClass1("value");<br>tmp.setAttr2(new MyClass2());<br>object.setAttr1(tmp);</tt></pre>
</td>
</tr>
</tbody>
</table>
<br>
<div align="center"><b> Example: the New element with arguments</b><br>
</div>
<tt><br>
<br>
</tt><br>
<p> <font size="+1"><b><a name="SystemProperty"></a>SystemProperty
Element</b></font></p>
<p> Java System Properties can be looked up and used as values
in <a href="#set"><code> Set</code></a> , <code>Arg</code> and <a
href="#put"><code>Put</code></a> elements. This can be used to parameterize
configuration files as in:</p>
<p> </p>
<tt><br>
</tt>
<blockquote><tt> <Set name="resourceBase"></tt><br>
<tt> <SystemProperty name="jetty.home" default="."/>/docroot/</tt><br>
<tt> </Set></tt><br>
</blockquote>
<br>
<div align="center"><b> Example: using the jetty.home system property
in setting a value</b><br>
</div>
<br>
<pre><tt><br></tt></pre>
<p><font size="+1"><b><a name="put"></a> Put Element</b></font></p>
<p> A call to a method witht the signature <code>Object put(Object
name, Object value)</code> can be called with the <code>Put</code> element:
</p>
<table cellpadding="2" cellspacing="2" border="0" width="90%"
align="center">
<tbody>
<tr>
<td valign="top"
width="30%"><tt> <Put name="name">value</Put><br>
</tt></td>
<td
valign="middle" align="center" width="20%"><small> <----
<br>
<i> is eqivalent to</i></small>
<br>
----><tt><br>
</tt></td>
<td valign="top"
width="30%"><tt><code> object.put("name","value");</code></tt><br>
</td>
</tr>
</tbody>
</table>
<div align="center"><b> Example: the Put element</b><br>
</div>
<br>
<br>
<big><big><b><a name="together"></a>Putting it all together</b></big></big><br>
<br>
Here is a full Jetty XML configuration file demonstrating several of
the most commonly used syntactic constructs described above:<br>
<table align="center" width="90%" cellspacing="2" cellpadding="0"
border="0">
<tbody>
<tr>
<td> <small>
<pre> <br><?xml version="1.0" encoding="ISO-8859-1"?><br><!DOCTYPE Configure PUBLIC <br> "-//Mort Bay Consulting//DTD Configure 1.2//EN"<br> "http://jetty.mortbay.org/configure_1_2.dtd"><br> <br><Configure class="org.mortbay.jetty.Server"><br> <Call name="addListener"><br> <Arg><br> <New class="org.mortbay.http.SocketListener"><br> <Set name="Port"><br> <SystemProperty name="jetty.port" default="8080"/><br> </Set><br> <Set name="MinThreads">5</Set><br> <Set name="MaxThreads">255</Set><br> <Set name="MaxIdleTimeMs">30000</Set><br> <Set name="MaxReadTimeMs">10000</Set><br> <Set name="MaxStopTimeMs">5000</Set><br> <Set name="LowResourcePersistTimeMs">5000</Set><br> </New><br> </Arg><br> </Call><br> <br> <Call name="addWebApplications"><br> <Arg></Arg><br> <Arg><br> <SystemProperty name="jetty.home" default="."/>/webapps/<br> </Arg><br> <Set name="defaultsDescriptor"><br> <SystemProperty name="jetty.home" <br> default="."/>/etc/webdefault.xml<br> </Set><br> </Call><br> <br></Configure><br></pre>
</small> <b> XML Example: an entire Jetty XML configuration file</b> </td>
</tr>
</tbody>
</table>
<br>
<br>
<table cellpadding="0" cellspacing="8" border="0" width="20%">
<tbody>
<tr>
<td valign="middle" bgcolor="#ccccff"><small><a
href="logging.html"> BACK</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a
href="index.html"> INDEX</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a
href=".."> EXIT</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a
href="other.html"> NEXT</a></small></td>
</tr>
</tbody>
</table>
<br>
</body>
</html>
