Jump to: navigation, search

Difference between revisions of "Jetty/Reference/jetty.xml syntax"

Line 90: Line 90:
 
You can use the <tt>id</tt> attribute to store a reference to this object when first creating or referring to this object. You can then use the <code>[[#<Ref>|<Ref>]]</code> tag to reference the object later on. The id must be unique for each object created.
 
You can use the <tt>id</tt> attribute to store a reference to this object when first creating or referring to this object. You can then use the <code>[[#<Ref>|<Ref>]]</code> tag to reference the object later on. The id must be unique for each object created.
  
== <Configure> ==
+
== &lt;Configure&gt; ==
  
 
This is the root element that specifies the class of object that is to be configured. It is usually either the Server, in [[Jetty/Reference/jetty.xml|jetty.xml ]], or a WebAppContext, in [[Jetty/Reference/jetty-web.xml|jetty-web.xml]].
 
This is the root element that specifies the class of object that is to be configured. It is usually either the Server, in [[Jetty/Reference/jetty.xml|jetty.xml ]], or a WebAppContext, in [[Jetty/Reference/jetty-web.xml|jetty-web.xml]].
Line 133: Line 133:
 
  java -jar start.jar etc/jetty.xml jetty-logging.xml
 
  java -jar start.jar etc/jetty.xml jetty-logging.xml
  
== <Set> ==
+
== &lt;Set&gt; ==
 
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 <tt>name</tt> and optional <tt>type</tt> attributes are used to select the setter method. If no value type is specified, then 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.
 
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 <tt>name</tt> and optional <tt>type</tt> attributes are used to select the setter method. If no value type is specified, then 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.
  
Line 189: Line 189:
 
</source>
 
</source>
  
== <Get> ==
+
== &lt;Get&gt; ==
 
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>|Set]], [[#<Put>|Put]], [[#<Call>|Call]], etc; these act on the object returned by the get call.
 
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>|Set]], [[#<Put>|Put]], [[#<Call>|Call]], etc; these act on the object returned by the get call.
  
Line 220: Line 220:
 
</source>
 
</source>
  
== <Put> ==
+
== &lt;Put&gt; ==
  
 
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 no value type is specified, then 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.
 
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 no value type is specified, then 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.
Line 238: Line 238:
 
</source>
 
</source>
  
== <Call> ==
+
== &lt;Call&gt; ==
  
 
A Call element maps to an arbitrary call to a method on the current object. It can contain a sequence of [[#<Arg>|Arg]] elements followed by a sequence of configuration elements, such as [[#<Set>|Set]], [[#<Put>|Put]], [[#<Call>|Call]]. The <code><Arg></code>s are passed as arguments to the method; the sequence of configuration elements act on the object returned by the original call.
 
A Call element maps to an arbitrary call to a method on the current object. It can contain a sequence of [[#<Arg>|Arg]] elements followed by a sequence of configuration elements, such as [[#<Set>|Set]], [[#<Put>|Put]], [[#<Call>|Call]]. The <code><Arg></code>s are passed as arguments to the method; the sequence of configuration elements act on the object returned by the original call.
Line 297: Line 297:
 
</source>
 
</source>
  
== <Arg> ==
+
== &lt;Arg&gt; ==
  
 
An Arg element can be an argument of either a method or a constructor. Use it within [[#<Call>|<Call>]] and [[#<New>|<New>]].  
 
An Arg element can be an argument of either a method or a constructor. Use it within [[#<Call>|<Call>]] and [[#<New>|<New>]].  
Line 360: Line 360:
 
</source>
 
</source>
  
== <New> ==
+
== &lt;New&gt; ==
 
Instantiates an object. Equivalent to <code>new</code> in Java, and allows the creation of a new object. A New element can contain a sequence of <code><Arg></code>s, followed by a sequence of configuration elements (Set, Put, etc). <code><Arg></code>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
 
Instantiates an object. Equivalent to <code>new</code> in Java, and allows the creation of a new object. A New element can contain a sequence of <code><Arg></code>s, followed by a sequence of configuration elements (Set, Put, etc). <code><Arg></code>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
  
Line 507: Line 507:
 
</source>
 
</source>
  
== <Array> ==
+
== &lt;Array&gt; ==
 
An Array element allows the creation of a new array.
 
An Array element allows the creation of a new array.
  
Line 529: Line 529:
 
</source>
 
</source>
  
== <Item> ==
+
== &lt;Item&gt; ==
 
An Item element defines an entry for [[#<Array>|Array]] and [[#<Map>|Map]] elements.
 
An Item element defines an entry for [[#<Array>|Array]] and [[#<Map>|Map]] elements.
  
Line 539: Line 539:
 
{{Jetty DTD Value}}
 
{{Jetty DTD Value}}
  
== <Map> ==
+
== &lt;Map&gt; ==
 
A Map element allows the creation of a new HashMap and to populate it with (key, value) pairs.
 
A Map element allows the creation of a new HashMap and to populate it with (key, value) pairs.
  
Line 564: Line 564:
 
</source>
 
</source>
  
== <Entry> ==
+
== &lt;Entry&gt; ==
 
An Entry element contains a key-value [[#<Item>|<Item>]] pair for a [[#<Map>|Map]].
 
An Entry element contains a key-value [[#<Item>|<Item>]] pair for a [[#<Map>|Map]].
  

Revision as of 09:26, 3 January 2011



Introduction

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 pre dates 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 the mechanism can also be used to configure arbitrary POJOs.

This page describes the basic syntax of Jetty XML configuration. See Jetty/Reference/jetty.xml usage for information on how Jetty XML can be used and combined. See Configuration Files for specific examples.

Basic Example

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

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="foo" class="com.acme.Foo">
  <Set name="name">demo</Set>
  <Set name="nested">
    <New id="bar" class="com.acme.Bar">
      <Arg>true</Arg>
      <Set name="wibble">10</Set>
      <Set name="wobble">xyz</Set>
      <Set name="parent"><Ref id="foo"/></Set>
      <Call name="init">
         <Arg>false</Arg>
      </Call>
    </New>
  </Set>
 
  <Ref id="bar">
    <Set name="wibble">20</Set>
    <Get name="parent">
      <Set name="name">demo2</Set>
    </Get>
  </Ref>
</Configure>

The XML above is equivalent to the following java code:

com.acme.Foo foo = new com.acme.Foo();
foo.setName("demo");
 
com.acme.Bar bar = new com.acme.Bar(true);
bar.setWibble(10);
bar.setWobble("xyz");
bar.setParent(foo);
bar.init(false);
 
foo.setNested(bar);
 
bar.setWibble(20);
bar.getParent().setName("demo2");


Overview

DTD and Parsing

The document type descriptor (DTD) describes all valid elements that can be used. The first two lines must reference the DTD, and you must substitute the appropriate class for the object you are trying to configure. See the appropriate jetty-*.xml references.

Jetty XML files are parsed by the org.eclipse.jetty.xml.XmlConfiguration class using the configure.dtd descriptor.

Method Calls

Java objects are configured by a sequence of <New>, <Set>, <Put> and <Call> elements:

<Set name="Test">value</Set>
obj.setTest("value");
<Put  name="Test">value</Put>
obj.put("Test","value");
<Call name="test"><Arg>value</Arg></Call>
obj.test("value");
<New class="com.acme.MyStuff"><Arg/></New>
new com.acme.MyStuff();

Coercing Arguments to a Type

Values are coerced to match method arguments on a best effort approach, but explicit types can also be specified 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

For Java classes, you can use either the fully qualified class name, or just the class name.

Referring to a Class

If you do not specify the classname, Jetty will assume you are calling the method on this. Otherwise, use the class attribute to specify the fully-qualified class name of an object to be configured. (You must always specify the class of the root Configure element.)

Referring to an Object

You can use the id attribute to store a reference to this object when first creating or referring to this object. You can then use the [[#[1] </source>

This is equivalent to:

foo = getXFoo();
foo.setTest("1, 2, 3");

Ref versus nested elements

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

<!-- using Ref in conjunction with Get -->
<Configure id="Server" class="org.eclipse.jetty.server.Server">
  <Get id="Logger" class="org.eclipse.jetty.util.log.Log" name="log"/>
  <Ref id="Logger">
    <Set name="debugEnabled">true</Set>
  </Ref>
</Configure>
<!-- calling the setter directly on the object returned by Get -->
<Configure id="Server" class="org.eclipse.jetty.server.Server">
  <Get class="org.eclipse.jetty.util.log.Log" name="log">
    <Set name="debugEnabled">true</Set>
  </Get>
</Configure>

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

<Set name="handler">
  <New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerCollection">
    <Set name="handlers">
      <Array type="org.eclipse.jetty.server.Handler">
        <Item>
          <!-- create a new instance of a ContextHandlerCollection named "Contexts" -->
          <New id="Contexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/>
        </Item>
        <Item>
          <New id="DefaultHandler" class="org.eclipse.jetty.server.handler.DefaultHandler"/>
        </Item>
        <Item>
          <!-- create a new instance of a RequestLogHandler named "RequestLog"--->
          <New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler"/>
        </Item>
      </Array>
    </Set>
  </New>
</Set>
 
<Call name="addBean">
  <Arg>
    <New class="org.eclipse.jetty.deploy.ContextDeployer">
      <!-- pass in the ContextHandlerCollection object ("Contexts") that was created earlier, as an argument -->
      <Set name="contexts"><Ref id="Contexts"/></Set>
    </New>
  </Arg>
</Call>
 
<!-- configure the RequestLogHandler object ("RequestLog") that we created earlier -->
<Ref id="RequestLog">
  ....
</Ref>

<Array>

An Array element allows the creation of a new array.

Attributes

type 
(optional), specify what types of items the array can contain
id 
(optional), unique identifier you can use to refer to the array later on

Can Contain

<Item>

Example

 <Array type="java.lang.String">
   <Item>value0</Item>
   <Item><New class="java.lang.String"><Arg>value1</Arg></New></Item>
 </Array>

This is equivalent to:

String[] a = new String[] { "value0", new String("value1") };

<Item>

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

Attributes

type 
(optional), force the types of value.
id 
(optional), unique identifier which can be used to refer to this item later on

Can Contain

value text, <Get>, <Call>, <New>, <Ref>, <Array>, <Map>, <SystemProperty>, <Property>

<Map>

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

Attributes

id 
(optional), unique identifier you can use to refer to the map later on

Can Contain

Entry

Example

<Map>
  <Entry>
    <Item>keyName</Item>
    <Item><New class="java.lang.String"><Arg>value1</Arg></New></Item>
  </Entry>
</Map>

This is equivalent to:

Map m = new HashMap();
m.put("keyName", new String("value1"));

<Entry>

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

Attributes

No attributes.

Can Contain

Item

<SystemProperty>

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

Attributes

name 
(required), property name
default 
(optional), a default value as a fallback
id 
(optional), unique identifier which can be used to refer to this system property later on

Can Contain

Cannot contain anything.

Example

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

That is equivalent to:

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

Both try to retrieve the value of jetty.port. If jetty.port is not set, then 8080 will be 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, etc, which act on the retrieved object.

Attributes

name 
(required), property name
default 
(optional), a default value as a fallback
id 
(optional), unique identifier which can be used to refer to this property later on

Can Contain

<Set>,<Get>, <Put>, <Call>, <New>, <Ref>, <Array>, <Map>, <Property>

Example

<Property name="Server">
  <Call id="jdbcIdMgr" name="getAttribute">
    <Arg>jdbcIdMgr</Arg>
  </Call>
</Property>

Additional Resources



Cite error: <ref> tags exist, but no <references/> tag was found