Skip to main content

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.

Jump to: navigation, search

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

Line 403: Line 403:
  
 
== <Ref> ==
 
== <Ref> ==
 +
A Ref element allows a previously created object to be referenced by a unique id. It can contain a sequence of elements, such as Set, Put, etc which then act on the referenced object. It can also be used used as a value for other elements such as Set and Arg.
 +
 +
The Ref element is provided for convenience and to ease readability. The effect of the Ref element may usually be achieved by nesting elements (method calls), but this can get complicated very easily. The Ref element makes it possible to refer to the same object if you're using it as multiple times, or passing it into multiple methods. It also makes it possible to split up configuration across multiple files.
 +
 
=== Attributes ===
 
=== Attributes ===
 +
; id : (required), the unique identifier used to name a previously created object.
 +
 
=== Can Contain ===
 
=== Can Contain ===
 +
{{Jetty DTD Config}}
 +
 
=== Examples ===
 
=== Examples ===
 +
==== Basic example ====
 +
Use the referenced object as an argument to a method call or constructor:
 +
<source lang="xml">
 +
<Get id="foo" name="xFoo" />
 +
<Set name="test"><Ref id="foo"/></Set>
 +
</source>
 +
 +
This is equivalent to:
 +
<source lang="java">
 +
foo = getXFoo();
 +
setSomeMethod(foo);
 +
</source>
 +
 +
==== Manipulate the object returned by Ref ====
 +
<source lang="xml">
 +
<Get id="foo" name="xFoo" />
 +
<Ref id="foo">
 +
  <Set name="test">1, 2, 3</Set>
 +
</Ref>
 +
</source>
 +
 +
This is equivalent to:
 +
<source lang="java">
 +
foo = getXFoo();
 +
foo.setTest("1, 2, 3");
 +
</source>
 +
 +
==== 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:
 +
 +
<source lang="xml">
 +
<!-- 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>
 +
</source>
 +
<source lang="xml">
 +
<!-- 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>
 +
</source>
 +
 +
Here is a more practical example, taken from the handler configuration section in <tt>etc/jetty.xml</tt>:
 +
 +
<source lang="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>
 +
</source>
 
== <Array> ==
 
== <Array> ==
 
=== Attributes ===
 
=== Attributes ===

Revision as of 01:48, 8 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] </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>

Attributes

Can Contain

Examples

<Map>

Attributes

Can Contain

Examples

<Item>

Attributes

Can Contain

Examples

<SystemProperty>

Attributes

Can Contain

Examples

<Property>

Attributes

Can Contain

Examples

| more =

}}



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=162674"

Back to the top