| // ======================================================================== |
| // Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd. |
| // ======================================================================== |
| // All rights reserved. This program and the accompanying materials |
| // are made available under the terms of the Eclipse Public License v1.0 |
| // and Apache License v2.0 which accompanies this distribution. |
| // |
| // The Eclipse Public License is available at |
| // http://www.eclipse.org/legal/epl-v10.html |
| // |
| // The Apache License v2.0 is available at |
| // http://www.opensource.org/licenses/apache2.0.php |
| // |
| // You may elect to redistribute this code under either of these licenses. |
| // ======================================================================== |
| |
| [[jetty-xml-syntax]] |
| === Jetty XML Syntax |
| |
| 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 predates all of them). |
| Typically Jetty XML is used by `jetty.xml` to configure a Jetty server or by a `context.xml` file to configure a ContextHandler or subclass, but you can also use the mechanism to configure arbitrary POJOs. |
| |
| This page describes the basic syntax of Jetty XML configuration. See xref:jetty-xml-usage[] for information on how you can use and combine Jetty XML. |
| See configuration files for specific examples. |
| |
| [[basic-xml-configuration-file-example]] |
| ==== Basic XML Configuration File Example |
| |
| The following XML configuration file creates some Java objects and sets some attributes: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <?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 refid="foo"/></Set> |
| <Call name="init"> |
| <Arg>false</Arg> |
| </Call> |
| </New> |
| </Set> |
| |
| <Ref refid="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: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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 |
| |
| ===== Understanding DTD and Parsing |
| |
| The document type descriptor |
| (link:{GITBROWSEURL}/jetty-xml/src/main/resources/org/eclipse/jetty/xml/configure_9_0.dtd?h=release-9[configure.dtd]) describes all valid elements in a Jetty XML configuration file using the Jetty IoC format. |
| The first two lines of an XML must reference the DTD to be used to validate the XML like: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> |
| ... |
| ---- |
| |
| Typcically a good XML editor will fetch the DTD from the URL and use it to give syntax highlighting and validation while a configuration file is being edited. |
| Some editors also allows DTD files to be locally cached. |
| The URL may point to configure.dtd if you want the latest current version, or to a specific version like configure_9_0.dtd if you want a particular validation feature set. |
| |
| Files that conform to the configure.dtd format are processed in Jetty by the `XmlConfiguration` class which may also validate the XML (using a version of the DTD from the classes jar file), but is by default run in a forgiving mode that tries to work around validation failures. |
| |
| ===== Jetty XML Configuration Scope |
| |
| The configuration of object instances with Jetty IoC XML is done on a scoped basis, so that for any given XML element there is a corresponding Object in scope and the nested XML elements apply to that. |
| The outer most scope is given by a Configure element and elements like Call, New and Get establish new scopes. |
| The following example uses the name fields to explain the scope. |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure class="com.example.Foo"> |
| <Set name="fieldOnFoo">value</Set> |
| <Set name="fieldOnFoo"> |
| <New class="com.example.Bar"> |
| <Set name=fieldOnBar>value</Set> |
| <Call name="methodOnBarWithNoArgs"/> |
| </New> |
| </Set> |
| |
| <Call name="methodOnFoo"> |
| <Arg>value for first arg of methodOnFoo</Arg> |
| <Arg><New class="com.example.Bar"/></Arg> |
| <Set name="fieldOnObjectReturnedByMethodOnFoo">value</Set> |
| <Call name="methodOnObjectReturnedByMethodOnFooWithNoArgs"/> |
| </Call> |
| </Configure> |
| ---- |
| |
| ===== Coercing Arguments to a Type |
| |
| When trying to match XML elements to java elements, Jetty `XmlConfiguration` may need to coerces values to match method arguments. |
| By default it does so on a best effort basis, but you can also specify explicit types 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`, and `void`. |
| |
| ===== Referring to a Class |
| |
| If you do not specify the classname, Jetty assumes you are calling the method on the object that is current in scope (eg the object of the surrounding `Configure`, `New` or `Get` clause). |
| If the class attribute is specified to a fully-qualified class name, then it is either used to create a new instance (`Configure` and `New` elements) or is used to access a static (`Call`, `Set` or `Get` elements). |
| |
| ===== Referring to an Object |
| |
| You can use the id attribute to store a reference to the current object when first creating or referring to this object. |
| You can then use the link:#jetty-xml-ref[Ref element] to reference the object later. |
| The ID must be unique for each object you create. |
| |
| ===== Attribute vs Element Style |
| |
| For XML elements that contain only other XML Elements, there is a choice of using attributes or elements style. |
| The following is an example of attribute style: |
| |
| .... |
| <Call id="result" class="org.example.SomeClass" name="someMethod" arg="value0,value1"/> |
| .... |
| |
| Attribute style has the benefit of brevity, but is limited by: values can only be Strings; multivalued items can not contain ','; values may not be subject to property expansion or other elements that return values. |
| Thus, the more verbose element style is available and the following is semantically equivalent to the attribute style above: |
| |
| .... |
| <Call> |
| <Id>result</Id> |
| <Class>org.example.SomeClass</Class> |
| <Name>someMethod</Name> |
| <Arg>value0</Arg> |
| <Arg>value1</Arg> |
| </Call> |
| .... |
| |
| Note that multivalued elements like `Arg` must be repeated and may not be comma-separated like they are when provided as attributes. |
| It is possible to use a mix of styles and the following example shows a moretypical example that uses property expansion as the reason for element style: |
| |
| .... |
| <Call id="result" name="someMethod"> |
| <Class><Property name="which.class"> |
| <Default><Property name="default.class" default="org.example.SomeClass"/> |
| </Property></Class> |
| <Arg>value0</Arg> |
| <Arg>value1</Arg> |
| </Call> |
| .... |
| |
| Attributes may not be expressed as elements when their parent element is one that contains data. |
| Thus `Arg`, `Item`, `Set`, `Put` and `Get` elements may not have their attributes expressed as elements. |
| |
| [[jetty-xml-configure]] |
| ==== <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.xml`, or a `WebAppContext` in `jetty-web.xml`. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |id |no |A reference to the object that was created. If you define |
| multiple link:#jetty-xml-configure[Configure element]s 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 |no |The fully qualified classname of the object to be |
| configured. Could be `org.eclipse.jetty.server.Server`, |
| `org.eclipse.jetty.webapp.WebAppContext`, a handler, etc. |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| link:#jetty-xml-set[Set element], link:#jetty-xml-get[Get element], |
| link:#jetty-xml-put[Put element], link:#jetty-xml-call[Call element], |
| link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref element], |
| link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map element], |
| link:#jetty-xml-property[Property element] |
| |
| ===== Examples |
| |
| ====== Basic Example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure class="org.eclipse.jetty.server.Server"> |
| <Set name="port">8080</Set> |
| </Configure> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| org.eclipse.jetty.server.Server server = new org.eclipse.jetty.server.Server(); |
| server.setPort(8080); |
| ---- |
| |
| ====== Using id to break up configuration of one object across multiple files |
| |
| In `etc/jetty.xml`: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure id="Server" class="org.eclipse.jetty.server.Server"> |
| <!-- basic configuration here --> |
| </Configure> |
| ---- |
| |
| In `etc/jetty-logging.xml`: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure id="Server" class="org.eclipse.jetty.server.Server"> |
| <!-- assumes that you have the basic server configuration set up; this file only contains additional configuration for logging --> |
| </Configure> |
| ---- |
| |
| Then run the combined configuration using: |
| |
| .... |
| java -jar start.jar etc/jetty.xml jetty-logging.xml |
| .... |
| |
| [[jetty-xml-set]] |
| ==== <Set> |
| |
| 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 name and optional type attributes are used to select the setter method. |
| If you do not specify a value type, 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. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |name |yes |the name of the setter method to call, or the field to set. |
| If the name given is xxx, then a setXxx method is used. If the setXxx |
| method cannot be found, then the xxx field is used. |
| |
| |type |no |the declared type of the argument. See also discussion of |
| type for Arg for how to define null and empty string values. |
| |
| |class |no |if present, then this Set is treated as a static set method |
| invocation |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| value text, link:#jetty-xml-get[Get element], link:#jetty-xml-call[Call |
| element], link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref |
| element], link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map |
| element], link:#jetty-xml-system-property[System Property element], |
| link:#jetty-xml-property[Property element] |
| |
| ===== Examples |
| |
| ====== Basic Example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure id="server" class="org.eclipse.jetty.server.Server"> |
| <Set name="port">8080</Set> |
| </Configure> |
| ---- |
| |
| ====== Set via a System Property |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure id="server" class="org.eclipse.jetty.server.Server"> |
| <Set name="port"><SystemProperty name="jetty.http.port" /></Set> |
| </Configure> |
| ---- |
| |
| ====== Creating a NewObject and Setting It on the Server |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <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> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| 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); |
| ---- |
| |
| ====== Invoking a Static Setter |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure id="server" class="org.eclipse.jetty.server.Server"> |
| <Set class="org.eclipse.jetty.util.log.Log" name="logToParent">loggerName</Set> |
| </Configure> |
| ---- |
| |
| [[jetty-xml-get]] |
| ==== <Get> |
| |
| 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`, `Put`, `Call`, etc.; these act on the object returned by the `Get` call. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |name |yes |the name of the getter method to call, or the field to get. |
| If the name given is xxx, then a getXxx method is used. If the getXxx |
| method cannot be found, then the xxx field is used. |
| |
| |class |no |f present, then this Get is treated as a static getter or |
| field. |
| |
| |id |no |if present, then you can use this id to refer to the returned |
| object later. |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| link:#jetty-xml-set[Set element], link:#jetty-xml-get[Get element], |
| link:#jetty-xml-put[Put element], link:#jetty-xml-call[Call element], |
| link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref element], |
| link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map element], |
| link:#jetty-xml-property[Property element] |
| |
| ===== Examples |
| |
| ====== Basic Example |
| |
| This simple example doesn't do much on its own. |
| You would normally use this in conjunction with a `<Ref id="Logger" />`. |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure id="server" class="org.eclipse.jetty.server.Server"> |
| <Get id="Logger" class="org.eclipse.jetty.util.log.Log" name="log"/> |
| </Configure> |
| ---- |
| |
| ====== Invoking a Static Getter and Call Methods on the Returned Object |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <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> |
| ---- |
| |
| [[jetty-xml-put]] |
| ==== <Put> |
| |
| 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 you do not specify a no value type, 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. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |name |yes |used as the put key |
| |
| |type |no |forces the type of the value. See also discussion of type for |
| Arg for how to define null and empty string values. |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| value text, link:#jetty-xml-get[Get element], link:#jetty-xml-call[Call |
| element], link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref |
| element], link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map |
| element], link:#jetty-xml-system-property[System Property element], |
| link:#jetty-xml-property[Property element] |
| |
| ===== Example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Get name="someKindOfMap"> |
| <Put name="keyName">objectValue</Put> |
| </Get> |
| ---- |
| |
| [[jetty-xml-call]] |
| ==== <Call> |
| |
| A `Call` element maps to an arbitrary call to a method on the current object. |
| It can contain a sequence of Arg elements followed by a sequence of configuration elements, such as Set, Put, Call. |
| The <Arg>s are passed as arguments to the method; the sequence of configuration elements act on the object returned by the original call. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |name |yes |the name of the arbitrary method to call. The method called |
| will use the exact name you provide it. |
| |
| |class |no |if present, then this Call is treated as a static method. |
| |
| |id |no |if present, you can use this id to refer to any object returned |
| by the call, for later use. |
| |
| |arg |no |comma separated list of arguments may be used for simple |
| string values rather than Arg elements |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| Attributes as elements (Id, Name, Class) plus link:#jetty-xml-arg[Arg |
| element], link:#jetty-xml-set[Set element], link:#jetty-xml-get[Get |
| element], link:#jetty-xml-put[Put element], link:#jetty-xml-call[Call |
| element], link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref |
| element], link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map |
| element], link:#jetty-xml-property[Property element] |
| |
| ===== Examples |
| |
| ====== Basic example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Call name="doFoo"> |
| <Arg>bar</Arg> |
| <Set name="test">1, 2, 3</Set> |
| </Call> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| Object o2 = o1.doFoo("bar"); |
| o2.setTest("1, 2, 3"); |
| ---- |
| |
| ====== Invoking a static method |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Call class="com.acme.Foo" name="setString"> |
| <Arg>somestring</Arg> |
| </Call> |
| ---- |
| |
| Which is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| com.acme.Foo.setString("somestring"); |
| ---- |
| |
| ====== Invoking the Actual MethodInstead of Relying on Getter/Setter Magic |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Configure id="Server" class="org.eclipse.jetty.server.Server"> |
| <Call name="getPort" id="port" /> |
| <Call class="com.acme.Environment" name="setPort"> |
| <Arg> |
| <Ref refid="port"/> |
| </Arg> |
| </Call> |
| </Configure> |
| ---- |
| |
| Which is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| org.mortbay.jetty.Server server = new org.mortbay.jetty.Server(); |
| com.acme.Environment.setPort( server.getPort() ); |
| ---- |
| |
| [[jetty-xml-arg]] |
| ==== <Arg> |
| |
| An Arg element can be an argument of either a method or a constructor. |
| Use it within xref:jetty-syntax-call[] and xref:jetty-syntax-new[]. |
| |
| It can contain text and/or elements, such as `Call`, `New`, `SystemProperty`, etc., as values. |
| The optional type attribute can force the type of the value. |
| If you don't specify a type, 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. |
| Simple `String` arguments can also be specified as a string separated arg attribute on the parent element. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |type |no |force the type of the argument. If you do not provide a value |
| for the element, if you use type of "String", the value will be the |
| empty string (""), otherwise it is null. |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| value text, link:#jetty-xml-get[Get element], link:#jetty-xml-call[Call |
| element], link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref |
| element], link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map |
| element], link:#jetty-xml-system-property[System Property element], |
| link:#jetty-xml-property[Property element] |
| |
| ===== Examples |
| |
| ====== Basic examples |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Arg>foo</Arg> <!-- String --> |
| <Arg>true</Arg> <!-- Boolean --> |
| <Arg>1</Arg> <!-- int, long, short, float, double --> |
| <Arg><Ref refid="foo" /></Arg> <!-- any object; reference a previously created object with id "foo", and pass it as a parameter --> |
| <Arg></Arg> <!-- null value --> |
| <Arg type="String"></Arg> <!-- empty string "" --> |
| ---- |
| |
| ====== Coercing Type |
| |
| This explicitly coerces the type to a boolean: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Arg type="boolean">False</Arg> |
| ---- |
| |
| ====== As a Parameter |
| |
| Here are a couple of examples of link:#jetty-xml-arg[Arg element] being used as a parameter to methods and to constructors: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Call class="com.acme.Environment" name="setFoo"> |
| <Arg> |
| <New class="com.acme.Foo"> |
| <Arg>bar</Arg> |
| </New> |
| </Arg> |
| </Call> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| com.acme.Environment.setFoo(new com.acme.Foo("bar")); |
| ---- |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <New class="com.acme.Baz"> |
| <Arg> |
| <Call id="bar" class="com.acme.MyStaticObjectFactory" name="createObject"> |
| <Arg>2</Arg> |
| </Call> |
| </Arg> |
| </New> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| new com.acme.Baz(com.acme.MyStaticObjectFactory.createObject(2)); |
| ---- |
| |
| [[jetty-xml-new]] |
| ==== <New> |
| |
| Instantiates an object. |
| Equivalent to `new` in Java, and allows the creation of a new object. |
| A `New` element can contain a sequence of link:#jetty-xml-arg[`Arg` element]'s, followed by a sequence of configuration elements (`Set`, `Put`, etc). |
| link:#jetty-xml-arg[`Arg` element]'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. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |class |yes |fully qualified classname, which determines the type of the |
| new object that is instantiated. |
| |
| |id |no |gives a unique name to the object which can be referenced later |
| by Ref elements. |
| |
| |arg |no |comma separated list of arguments may be used for simple |
| string values rather than Arg elements |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| Attributes as elements (Id, Class) plus link:#jetty-xml-arg[Arg |
| element], link:#jetty-xml-set[Set element], link:#jetty-xml-get[Get |
| element], link:#jetty-xml-put[Put element], link:#jetty-xml-call[Call |
| element], link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref |
| element], link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map |
| element], link:#jetty-xml-property[Property element] |
| |
| ===== Examples |
| |
| ====== Basic example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <New class="com.acme.Foo"> |
| <Arg>bar</Arg> |
| </New> |
| ---- |
| |
| Which is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| com.acme.Foo foo = new com.acme.Foo("bar"); |
| ---- |
| |
| ====== Instantiate with the Default Constructor |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <New class="com.acme.Foo" /> |
| ---- |
| |
| Which is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| com.acme.Foo foo = new com.acme.Foo(); |
| ---- |
| |
| ====== Instantiate with Multiple Arguments, Then Configuring Further |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <New id="foo" class="com.acme.Foo"> |
| <Arg>bar</Arg> |
| <Arg>baz</Arg> |
| <Set name="test">1, 2, 3</Set> |
| </New> |
| ---- |
| |
| Which is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| Object foo = new com.acme.Foo("bar", "baz"); |
| foo.setTest("1, 2, 3"); |
| ---- |
| |
| [[jetty-xml-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` or `Put` which then act on the referenced object. |
| You can also use a `Ref` element as a value for other elements such as `Set` and `Arg`. |
| |
| The `Ref` element provides convenience and eases readability. |
| You can usually achieve the effect of the `Ref` 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 multiple times, or passing it into multiple methods. |
| It also makes it possible to split up configuration across multiple files. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |refid |yes |the unique identifier used to name a previously created |
| object. |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| link:#jetty-xml-set[Set element], link:#jetty-xml-get[Get element], |
| link:#jetty-xml-put[Put element], link:#jetty-xml-call[Call element], |
| link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref element], |
| link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map element], |
| link:#jetty-xml-property[Property element] |
| |
| ===== Examples |
| |
| ====== Basic example |
| |
| Use the referenced object as an argument to a method call or constructor: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Get id="foo" name="xFoo" /> |
| <Set name="test"><Ref refid="foo"/></Set> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| foo = getXFoo(); |
| setSomeMethod(foo); |
| ---- |
| |
| ====== Manipulating the Object Returned by Ref |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Get id="foo" name="xFoo" /> |
| <Ref refid="foo"> |
| <Set name="test">1, 2, 3</Set> |
| </Ref> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| foo = getXFoo(); |
| foo.setTest("1, 2, 3"); |
| ---- |
| |
| ====== Ref vs. Nested Elements |
| |
| Here is an example of the difference in syntax between using the `Ref` element, and nesting method calls. |
| They are exactly equivalent: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <!-- 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 refid="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`: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <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 refid="Contexts"/></Set> |
| </New> |
| </Arg> |
| </Call> |
| |
| <!-- configure the RequestLogHandler object ("RequestLog") that we created earlier --> |
| <Ref refid="RequestLog"> |
| .... |
| </Ref> |
| ---- |
| |
| [[jetty-xml-array]] |
| ==== <Array> |
| |
| An `Array` element allows the creation of a new array. |
| |
| [cols=",,",options="header",] |
| |================================================================== |
| |Attribute |Required |Description |
| |type |no |specify what types of items the array can contain. |
| |id |no |unique identifier you can use to refer to the array later. |
| |================================================================== |
| |
| ===== Can Contain |
| |
| link:#jetty-xml-item[Item element] |
| |
| ===== Example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Array type="java.lang.String"> |
| <Item>value0</Item> |
| <Item><New class="java.lang.String"><Arg>value1</Arg></New></Item> |
| </Array> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| String[] a = new String[] { "value0", new String("value1") }; |
| ---- |
| |
| [[jetty-xml-item]] |
| ==== <Item> |
| |
| An `Item` element defines an entry for Array and Map elements. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |type |no |force the types of value. |
| |id |no |unique identifier that you can use to refer to the array later. |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| link:#jetty-xml-get[Get element], link:#jetty-xml-call[Call element], |
| link:#jetty-xml-new[New element], link:#jetty-xml-ref[Ref element], |
| link:#jetty-xml-array[Array element], link:#jetty-xml-map[Map element], |
| link:#jetty-xml-system-property[System Property element], |
| link:#jetty-xml-property[Property element] |
| |
| [[jetty-xml-map]] |
| ==== <Map> |
| |
| A `Map` element allows the creation of a new HashMap and to populate it with `(key, value)` pairs. |
| |
| [cols=",,",options="header",] |
| |================================================================ |
| |Attribute |Required |Description |
| |id |no |unique identifier you can use to refer to the map later. |
| |================================================================ |
| |
| ===== Can Contain |
| |
| link:#jetty-xml-entry[Entry element] |
| |
| ===== Example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Map> |
| <Entry> |
| <Item>keyName</Item> |
| <Item><New class="java.lang.String"><Arg>value1</Arg></New></Item> |
| </Entry> |
| </Map> |
| ---- |
| |
| This is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| Map m = new HashMap(); |
| m.put("keyName", new String("value1")); |
| ---- |
| |
| [[jetty-xml-entry]] |
| ==== <Entry> |
| |
| An `Entry` element contains a key-value link:#jetty-xml-item[Item element] pair for a `Map`. |
| |
| ===== Can Contain |
| |
| link:#jetty-xml-item[Item element] |
| |
| [[jetty-xml-system-property]] |
| ==== <SystemProperty> |
| |
| A `SystemProperty` element gets the value of a JVM system property. |
| It can be used within elements that accept values, such as `Set`, `Put`, `Arg`. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |name |yes |property name |
| |
| |default |no |a default value as a fallback |
| |
| |id |no |unique identifier which you can use to refer to the array |
| later. |
| |======================================================================= |
| |
| ===== Can Contain |
| |
| Only attributes as Elements (`Id`, `Name`, `Default`). |
| |
| ===== Example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <SystemProperty name="jetty.http.port" default="8080"/> |
| ---- |
| |
| That is equivalent to: |
| |
| [source, java, subs="{sub-order}"] |
| ---- |
| System.getProperty("jetty.http.port", "8080"); |
| ---- |
| |
| Both try to retrieve the value of `jetty.http.port`. |
| If `jetty.http.port` is not set, then 8080 is used. |
| |
| [[jetty-xml-property]] |
| ==== <Property> |
| |
| A `Property` element allows arbitrary properties to be retrieved by name. |
| It can contain a sequence of elements, such as `Set`, `Put`, `Call` that act on the retrieved object. |
| |
| [cols=",,",options="header",] |
| |======================================================================= |
| |Attribute |Required |Description |
| |name |yes |property name |
| |
| |default |no |a default value as a fallback |
| |
| |id |no |unique identifier which you can use to refer to the array |
| later. |
| |======================================================================= |
| |
| The `Name` attribute may be a comma separated list of property names, with the first property name being the "official" name, and the others names being old, deprecated property names that are kept for backward compatibility. |
| A warning log is issued when deprecated property names are used. |
| The `Default` attribute contains the value to use in case none of the property names is found. |
| |
| ===== Can Contain |
| |
| The attributes may be expressed as contained Elements (`Id`, `Name`, `Default`). |
| |
| ===== Example |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <Property name="Server"> |
| <Call id="jdbcIdMgr" name="getAttribute"> |
| <Arg>jdbcIdMgr</Arg> |
| </Call> |
| </Property> |
| ---- |