Skip to main content

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.

Jump to: navigation, search

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

Line 6: Line 6:
  
 
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):
 +
<!-- need:
 +
# Configure
 +
# Set
 +
# Get
 +
# Put
 +
# Call
 +
# Arg
 +
# New
 +
# Ref
 +
# Array
 +
# Map
 +
# Item
 +
# SystemProperty
 +
# Property
 +
-->
 
<source lang="xml">
 
<source lang="xml">
 
   <?xml version="1.0"?>
 
   <?xml version="1.0"?>
Line 73: Line 88:
  
 
=== Attributes ===
 
=== 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. 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 ===
+
=== Can Contain ===
−
[[#<Set>|<Set>]],[[#<Get>|<Get>]], [[#<Put>|<Put>]], [[#<Call>|<Call>]], [[#<New>|<New>]], [[#<Ref>|<Ref>]], [[#<Array>|<Array>]], [[#<Map>|<Map>]], [[#<Property>|<Property>]]
+
{{Jetty DTD Config}}
  
 
=== Examples ===
 
=== Examples ===
Line 101: Line 116:
 
</source>
 
</source>
  
−
<tt>(etc/jetty-rewrite.xml)</tt>
+
<tt>(etc/jetty-logging.xml)</tt>
 
<source lang="xml">
 
<source lang="xml">
 
<Configure id="Server" class="org.eclipse.jetty.server.Server">
 
<Configure id="Server" class="org.eclipse.jetty.server.Server">
−
   <!-- assumes that we have the basic server configuration set up; this files only contains configuration for the rewrite functionality -->
+
   <!-- assumes that we have the basic server configuration set up; this files only contains additional configuration for logging -->
 
</Configure>
 
</Configure>
 
</source>
 
</source>
  
 
Then run the combined configuration using:
 
Then run the combined configuration using:
−
  java -jar start.jar etc/jetty.xml jetty-rewrite.xml
+
  java -jar start.jar etc/jetty.xml jetty-logging.xml
  
 
== <Set> ==
 
== <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. 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.
  
 
=== Attributes ===
 
=== 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.
 
; 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 ===
+
=== Can Contain ===
−
value text, [[#<Get>|<Get>]], [[#<Put>|<Put>]], [[#<Call>|<Call>]], [[#<New>|<New>]], [[#<Ref>|<Ref>]], [[#<Array>|<Array>]], [[#<Map>|<Map>]], [[#<Property>|<Property>]]
+
{{Jetty DTD Value}}
  
 
=== Examples ===
 
=== Examples ===
 +
==== Simple example ====
 +
<source lang="xml">
 +
<Configure id="server" class="org.eclipse.jetty.server.Server">
 +
  <Set name="port">8080</Set>
 +
</Configure>
 +
</source>
 +
 +
==== Set via a system property ====
 +
<source lang="xml">
 +
<Configure id="server" class="org.eclipse.jetty.server.Server">
 +
  <Set name="port"><SystemProperty name="jetty.port" /></Set>
 +
</Configure>
 +
</source>
 +
 +
==== Create a new object and set it on the server ====
 +
<source lang="xml">
 +
<Configure id="server" class="org.eclipse.jetty.server.Server">
 +
  <Set name="threadPool">
 +
    <New class="org.eclipse.jetty.util.thread.QueuedThreadPool">
 +
      <Set name="minThreads">10</Set>
 +
      <Set name="maxThreads">1000</Set>
 +
    </New>
 +
  </Set>
 +
</Configure>
 +
</source>
 +
 +
This is equivalent to:
 +
<source lang="java">
 +
org.eclipse.jetty.server.Server server = new org.eclipse.jetty.server.Server();
 +
 +
org.eclipse.jetty.util.thread.QueuedThreadPool threadPool = new org.eclipse.jetty.util.thread.QueuedThreadPool();
 +
threadPool.setMinThreads(10);
 +
threadPool.setMaxThreads(1000);
 +
 +
server.setThreadPool(threadPool);
 +
</source>
 +
 +
==== Invoke a static setter ====
 +
<source lang="xml">
 +
<Configure id="server" class="org.eclipse.jetty.server.Server">
 +
  <Set class="org.eclipse.jetty.util.log.Log" name="logToParent">loggerName</Set>
 +
</Configure">
 +
</source>
  
 
== <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.
 +
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
; name : (required), the name of the getter method to call, or the field to get. If the name given is <var>xxx</var>, then a get<var>Xxx</var> method is used. If the get<var>Xxx</var> method cannot be found, then the <var>xxx</var> field is used.
 +
; class :  (optional), if present, then this Get is treated as a static getter or field.
 +
; id : (optional), if present, then you can use this id to refer to the returned object later on.
 +
 
 +
=== Can Contain ===
 +
{{Jetty DTD Config}}
 +
 
 
=== Examples ===
 
=== Examples ===
 +
==== Simple 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>.
 +
<source lang="xml">
 +
<Configure id="server" class="org.eclipse.jetty.server.Server">
 +
  <Get id="Logger" class="org.eclipse.jetty.util.log.Log" name="log"/>
 +
</Configure>
 +
</source>
 +
 +
==== Invoke a static getter and call methods on the returned object ====
 +
<source lang="xml">
 +
<Configure id="server" class="org.eclipse.jetty.server.Server">
 +
    <Get class="java.lang.System" name="out">
 +
      <Call name="println">
 +
        <Arg>Server version is: <Get class="org.eclipse.jetty.server.Server" name="version"/></Arg>
 +
      </Call>
 +
    </Get>
 +
</Configure>
 +
</source>
  
 
== <Put> ==
 
== <Put> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
  
 
== <Call> ==
 
== <Call> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
  
 
== <Arg> ==
 
== <Arg> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
  
 
== <New> ==
 
== <New> ==
 +
Instantiates an object. Equivalent to <code>new</code> in Java, and allows the creation of a new object as part of a value of a [[#<Configure>|Configure]], [[#<Set>|Set]], [[#<Put>|Put]] or [[#<Arg>|Arg]] element.
 +
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
; class : (required), fully qualified classname, which determines the type of the new object that is instantiated.
 +
; id : (optional), gives a unique name to the object which can be referenced later by [[#<Ref>|Ref]] elements.
 +
 
 +
=== Can Contain ===
 +
[[#<Arg>|<Arg>]], {{Jetty DTD Config}}
 +
 
 +
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
 +
 
 
=== Examples ===
 
=== Examples ===
 +
==== Simple example ====
 +
<source lang="xml">
 +
<New class="com.acme.Foo">
 +
  <Arg>bar</Arg>
 +
</New>
 +
</source>
 +
 +
which is equivalent to:
 +
<source lang="java">
 +
com.acme.Foo foo = new com.acme.Foo("bar");
 +
</source>
 +
 +
==== Instantiate with the default constructor ====
 +
<source lang="xml">
 +
<New class="com.acme.Foo" />
 +
</source>
 +
 +
which is equivalent to:
 +
<source lang="java">
 +
com.acme.Foo foo = new com.acme.Foo();
 +
</source>
 +
 +
==== Instantiate with multiple arguments, then further configure ====
 +
<source lang="xml">
 +
<New id="foo" class="com.acme.Foo">
 +
  <Arg>bar</Arg>
 +
  <Arg>baz</Arg>
 +
  <Set name="test">1, 2, 3</Set>
 +
</New>
 +
</source>
 +
 +
which is equivalent to:
 +
<source lang="java">
 +
Object foo = new com.acme.Foo("bar", "baz");
 +
foo.setTest("1, 2, 3");
 +
</source>
  
 
== <Ref> ==
 
== <Ref> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
−
 
  
 
== <Array> ==
 
== <Array> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
  
 
== <Map> ==
 
== <Map> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
  
 
== <Item> ==
 
== <Item> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 +
=== Examples ===
 +
 
 +
== <SystemProperty> ==
 +
=== Attributes ===
 +
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
  
 
== <Property> ==
 
== <Property> ==
 
=== Attributes ===
 
=== Attributes ===
−
=== Possible Child Elements ===
+
=== Can Contain ===
 
=== Examples ===
 
=== Examples ===
 
}}
 
}}

Revision as of 06:11, 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.

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

Retrieved from "https://wiki.eclipse.org/index.php?title=Jetty/Reference/jetty.xml_syntax&oldid=162360"

Back to the top