Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Jetty/Reference/jetty.xml syntax"
(New page: {{Jetty Reference |introduction = 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, sett...) |
|||
| 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 === | |
| − | == Quick Example == | + | |
Here is an example of a file which uses the Jetty XML syntax (the example is taken 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 taken from etc/jetty.xml, available from your distribution, so it may look familiar): | ||
| Line 31: | Line 30: | ||
</Configure> | </Configure> | ||
</source> | </source> | ||
| − | |||
| − | === DTD and Parsing === | + | === Overview === |
| + | |||
| + | ==== DTD and Parsing ==== | ||
The [http://www.eclipse.org/jetty/configure.dtd 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 [[Jetty/Reference|references]]. | The [http://www.eclipse.org/jetty/configure.dtd 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 [[Jetty/Reference|references]]. | ||
Jetty XML files are parsed by the org.eclipse.jetty.xml.XmlConfiguration class using the configure.dtd descriptor. | Jetty XML files are parsed by the org.eclipse.jetty.xml.XmlConfiguration class using the configure.dtd descriptor. | ||
| − | === Method Calls === | + | ==== Method Calls ==== |
Java objects are configured by a sequence of <code><New>, <Set>, <Put> and <Call></code> elements: | Java objects are configured by a sequence of <code><New>, <Set>, <Put> and <Call></code> elements: | ||
<div id="methods"> | <div id="methods"> | ||
| Line 51: | Line 51: | ||
</div> | </div> | ||
| − | === Coercing Arguments to a Type === | + | ==== 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 <tt>type</tt> attribute. Supported values for type are: | Values are coerced to match method arguments on a best effort approach, but explicit types may also be specified with the <tt>type</tt> attribute. Supported values for type are: | ||
| Line 60: | Line 60: | ||
For Java classes, you may use either the fully qualified class name, or just the class name. | For Java classes, you may use either the fully qualified class name, or just the class name. | ||
| − | === Referring to a Class === | + | ==== Referring to a Class ==== |
If you do not specify the classname, Jetty will assume you are calling the method on <code>this</code>. Otherwise, use the <tt>class</tt> 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.) | If you do not specify the classname, Jetty will assume you are calling the method on <code>this</code>. Otherwise, use the <tt>class</tt> 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 === | + | ==== Referring to an Object ==== |
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>]]</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>]]</code> tag to reference the object later on. The id must be unique for each object created. | ||
| − | = | + | |body = |
| − | + | ||
| − | + | ||
| − | + | == <Configure> == | |
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]]. | ||
| − | + | === Attributes === | |
; id : (optional), a reference to the object that was created. If you define multiple <code><Configure></code> tags with the same id, they will be treated as one object, even if they're in different files. Thus you can use this to break up configuration of an object (such as the Server) across multiple files. | ; id : (optional), a reference to the object that was created. If you define multiple <code><Configure></code> tags with the same id, they will be treated as one object, even if they're in different files. Thus you can use this to break up configuration of an object (such as the Server) across multiple files. | ||
; class : (optional), the fully qualified classname of the object to be configured. Could be <code>org.eclipse.jetty.server.Server</code>, <code>org.eclipse.jetty.webapp.WebAppContext</code>, a handler, etc. | ; class : (optional), the fully qualified classname of the object to be configured. Could be <code>org.eclipse.jetty.server.Server</code>, <code>org.eclipse.jetty.webapp.WebAppContext</code>, a handler, etc. | ||
| − | + | === Possible Child Elements === | |
[[#<Set>|<Set>]],[[#<Get>|<Get>]], [[#<Put>|<Put>]], [[#<Call>|<Call>]], [[#<New>|<New>]], [[#<Ref>|<Ref>]], [[#<Array>|<Array>]], [[#<Map>|<Map>]], [[#<Property>|<Property>]] | [[#<Set>|<Set>]],[[#<Get>|<Get>]], [[#<Put>|<Put>]], [[#<Call>|<Call>]], [[#<New>|<New>]], [[#<Ref>|<Ref>]], [[#<Array>|<Array>]], [[#<Map>|<Map>]], [[#<Property>|<Property>]] | ||
| − | + | === Examples === | |
| − | + | ==== Simple example ==== | |
<source lang="xml"> | <source lang="xml"> | ||
<Configure class="org.eclipse.jetty.server.Server"> | <Configure class="org.eclipse.jetty.server.Server"> | ||
| Line 95: | Line 93: | ||
</source> | </source> | ||
| − | + | ==== Using <tt>id</tt> to break up configuration of one object across multiple files ==== | |
<tt>(etc/jetty.xml)</tt> | <tt>(etc/jetty.xml)</tt> | ||
<source lang="xml"> | <source lang="xml"> | ||
| Line 113: | Line 111: | ||
java -jar start.jar etc/jetty.xml jetty-rewrite.xml | java -jar start.jar etc/jetty.xml jetty-rewrite.xml | ||
| − | + | == <Set> == | |
This element maps to a call to a setter method or field on the current object. The <tt>name</tt> and optional <tt>type</tt> attributes are used to select the setter method. | This element maps to a call to a setter method or field on the current object. The <tt>name</tt> and optional <tt>type</tt> attributes are used to select the setter method. | ||
| − | + | === Attributes === | |
; name : (required), the name of the setter method to call, or the field to set. If the name given is <var>xxx</var>, then a set<var>Xxx</var> method is used. If the set<var>Xxx</var> method cannot be found, then the <var>xxx</var> field is used. | ; name : (required), the name of the setter method to call, or the field to set. If the name given is <var>xxx</var>, then a set<var>Xxx</var> method is used. If the set<var>Xxx</var> method cannot be found, then the <var>xxx</var> field is used. | ||
; type : (optional), the declared type of the argument. A Set element can contain value text and/or the value objects returned by other elements such as Call, New, SystemProperty, etc. If no value type is specified, then white space is trimmed out of the value. If it contains multiple value elements they are added as strings before being converted to any specified type. | ; type : (optional), the declared type of the argument. A Set element can contain value text and/or the value objects returned by other elements such as Call, New, SystemProperty, etc. If no value type is specified, then white space is trimmed out of the value. If it contains multiple value elements they are added as strings before being converted to any specified type. | ||
; class : (optional), if present, then this Set is treated as a static set method invocation | ; class : (optional), if present, then this Set is treated as a static set method invocation | ||
| − | + | === Possible Child Elements === | |
value text, [[#<Get>|<Get>]], [[#<Put>|<Put>]], [[#<Call>|<Call>]], [[#<New>|<New>]], [[#<Ref>|<Ref>]], [[#<Array>|<Array>]], [[#<Map>|<Map>]], [[#<Property>|<Property>]] | value text, [[#<Get>|<Get>]], [[#<Put>|<Put>]], [[#<Call>|<Call>]], [[#<New>|<New>]], [[#<Ref>|<Ref>]], [[#<Array>|<Array>]], [[#<Map>|<Map>]], [[#<Property>|<Property>]] | ||
| − | + | === Examples === | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | == <Get> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
| − | + | == <Put> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
| − | + | == <Call> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
| − | + | == <Arg> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
| − | + | == <New> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
| + | == <Ref> == | ||
| + | === Attributes === | ||
| + | === Possible Child Elements === | ||
| + | === Examples === | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | == <Array> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
| − | + | == <Map> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
| + | == <Item> == | ||
| + | === Attributes === | ||
| + | === Possible Child Elements === | ||
| + | === Examples === | ||
| − | + | == <Property> == | |
| − | + | === Attributes === | |
| − | + | === Possible Child Elements === | |
| − | + | === Examples === | |
}} | }} | ||
Revision as of 03:43, 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.
Contents
Quick Example
Here is an example of a file which uses the Jetty XML syntax (the example is taken 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