Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Jetty/Reference/jetty.xml syntax
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).
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 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]
</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
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
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
<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>
| more =
- configure.dtd
- Jetty XML Usage
- jetty.xml, server configuration file
- jetty-web.xml, webapp configuration file
- jetty-env.xml, JNDI configuration file
}}
Cite error: <ref>
tags exist, but no <references/>
tag was found