Jump to: navigation, search

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

Line 3: Line 3:
 
The Jetty XML syntax is a straightforward mapping of XML elements to the [http://download.eclipse.org/jetty/stable-7/apidocs/ Java API]. Any getter, setter, or method can be invoked in the XML configuration files.  
 
The Jetty XML syntax is a straightforward mapping of XML elements to the [http://download.eclipse.org/jetty/stable-7/apidocs/ Java API]. Any getter, setter, or method can be invoked in the XML configuration files.  
  
=== Quick Example ===
+
=== Basic Example ===
  
 
Here is an example of a file which uses the Jetty XML syntax (the example is extracted from etc/jetty.xml, available from your distribution, so it may look familiar):
 
Here is an example of a file which uses the Jetty XML syntax (the example is extracted from etc/jetty.xml, available from your distribution, so it may look familiar):
Line 95: Line 95:
  
 
=== Examples ===
 
=== Examples ===
==== Simple example ====
+
==== Basic example ====
 
<source lang="xml">
 
<source lang="xml">
 
<Configure class="org.eclipse.jetty.server.Server">
 
<Configure class="org.eclipse.jetty.server.Server">
Line 127: Line 127:
  
 
== <Set> ==
 
== <Set> ==
This element maps to a call to a setter method or field on the current object. A Set element 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.
  
 
=== Attributes ===
 
=== Attributes ===
Line 138: Line 138:
  
 
=== Examples ===
 
=== Examples ===
==== Simple example ====
+
==== Basic example ====
 
<source lang="xml">
 
<source lang="xml">
 
<Configure id="server" class="org.eclipse.jetty.server.Server">
 
<Configure id="server" class="org.eclipse.jetty.server.Server">
Line 183: Line 183:
  
 
== <Get> ==
 
== <Get> ==
This element maps to a call to a getter method or field on the current object. A Get element 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.
  
 
=== Attributes ===
 
=== Attributes ===
Line 194: Line 194:
  
 
=== Examples ===
 
=== Examples ===
==== Simple example ====
+
==== Basic example ====
 
This simple example doesn't do much on its own. We'd normally use this in conjunction with a <code><[[#<Ref>|Ref]] id="Logger" /></code>.
 
This simple example doesn't do much on its own. We'd normally use this in conjunction with a <code><[[#<Ref>|Ref]] id="Logger" /></code>.
 
<source lang="xml">
 
<source lang="xml">
Line 215: Line 215:
 
== <Put> ==
 
== <Put> ==
  
This element maps to a call to a put method on the current object, which must implement the Map interface. A Put element 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.
  
 
=== Attributes ===
 
=== Attributes ===
Line 225: Line 225:
  
 
=== Examples ===
 
=== Examples ===
==== Simple example ====
+
==== Basic example ====
 
<source lang="xml">
 
<source lang="xml">
 
<Get name="someKindOfMap">
 
<Get name="someKindOfMap">
Line 233: Line 233:
  
 
== <Call> ==
 
== <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.
 +
 
=== Attributes ===
 
=== Attributes ===
 +
; name : the name of the arbitrary method to call. The method called will use the exact name you provide it.
 +
; class : if present, then this Call is treated as a static method.
 +
; id : if present, then you can use this id to refer to any object returned by the call, for later use
 +
 
=== Can Contain ===
 
=== Can Contain ===
 +
[[#<Arg>|Arg]], {{Jetty DTD Config}}
 +
 
=== Examples ===
 
=== Examples ===
 +
 +
==== Basic example ====
 +
<source lang="xml">
 +
<Call name="doFoo">
 +
  <Arg>bar</Arg>
 +
  <Set name="test">1, 2, 3</Set>
 +
</Call>
 +
</source>
 +
 +
This is equivalent to:
 +
<source lang="java">
 +
Object o2 = o1.doFoo("bar");
 +
o2.setTest("1, 2, 3");
 +
</source>
 +
 +
==== Invoke a static method ====
 +
<source lang="xml">
 +
<Call class="com.acme.Foo" name="setString">
 +
  <Arg>somestring</Arg>
 +
</Call>
 +
</source>
 +
 +
which is equivalent to:
 +
<source lang="java">
 +
com.acme.Foo.setString("somestring");
 +
</source>
 +
 +
==== Invoke the actual method instead of relying on getter/setter magic ====
 +
<source lang="xml">
 +
<Configure id="Server" class="org.eclipse.jetty.server.Server">
 +
  <Call name="getPort" id="port" />
 +
  <Call class="com.acme.Environment" name="setPort">
 +
    <Arg>
 +
      <Ref id="port"/>
 +
    </Arg>
 +
  </Call>
 +
</Configure>
 +
</source>
 +
 +
which is equivalent to:
 +
 +
<source lang="java">
 +
org.mortbay.jetty.Server server = new org.mortbay.jetty.Server();
 +
com.acme.Environment.setPort( server.getPort() );
 +
</source>
  
 
== <Arg> ==
 
== <Arg> ==
Line 243: Line 297:
  
 
== <New> ==
 
== <New> ==
Instantiates an object. Equivalent to <code>new</code> in Java, and allows the creation of a new object. The <code><New></code> 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
  
 
=== Attributes ===
 
=== Attributes ===
Line 253: Line 307:
  
 
=== Examples ===
 
=== Examples ===
==== Simple example ====
+
==== Basic example ====
 
<source lang="xml">
 
<source lang="xml">
 
<New class="com.acme.Foo">
 
<New class="com.acme.Foo">

Revision as of 06:32, 7 July 2009

{{Jetty Reference |introduction = The Jetty XML syntax is a straightforward mapping of XML elements to the Java API. Any getter, setter, or method can be invoked in the XML configuration files.

Basic Example

Here is an example of a file which uses the Jetty XML syntax (the example is extracted from etc/jetty.xml, available from your distribution, so it may look familiar):

  <?xml version="1.0"?>
  <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
  <!-- root element -->
  <Configure id="Server" class="org.eclipse.jetty.server.Server">
    <!-- using a setter on the server class -->
    <Set name="ThreadPool">
      <!-- creating a new object, and customizing it after creation -->
      <New class="org.eclipse.jetty.util.thread.QueuedThreadPool">
        <Set name="minThreads">10</Set>
      </New>
    </Set>
 
    <!-- calling a non-setter/non-getter class, with arguments -->
    <Call name="addConnector">
      <Arg>
          <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
            <Set name="host"><SystemProperty name="jetty.host" /></Set>
             ....
          </New>
      </Arg>
    </Call>
  </Configure>

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 may 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 may 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]


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