Package org.eclipse.jetty.xml

Class XmlConfiguration

java.lang.Object

org.eclipse.jetty.xml.XmlConfiguration

public class XmlConfiguration
extends Object

Configures objects from XML.

This class reads an XML file conforming to the configure.dtd DTD and uses it to configure and object by calling set, put or other methods on the object.

The actual XML file format may be changed (eg to spring XML) by implementing the ConfigurationProcessorFactory interface to be found by the ServiceLoader by using the DTD and first tag element in the file. Note that DTD will be null if validation is off.

The configuration can be parameterised with properties that are looked up via the Property XML element and set on the configuration via the map returned from getProperties()

The configuration can create and lookup beans by ID. If multiple configurations are used, then it is good practise to copy the entries from the getIdMap() of a configuration to the next configuration so that they can share an ID space for beans.

Field Summary

Fields

Modifier and Type	Field	Description
static final Comparator<Executable>	EXECUTABLE_COMPARATOR

Constructor Summary

Constructors

Constructor	Description
XmlConfiguration(Resource resource)	Reads and parses the XML configuration file.

Method Summary

Modifier and Type	Method	Description
Object	configure()	Applies the XML configuration script.
Object	configure(Object obj)	Applies the XML configuration script to the given object.
Map<String,Object>	getIdMap()	Get the map of ID String to Objects that is used to hold and lookup any objects by ID.
Map<String,String>	getProperties()	Get the map of properties used by the Property XML element to parametrize configuration.
XmlParser	getXmlParser()
void	initializeDefaults(Object object)	Initialize a new Object defaults.
static void	main(String... args)	Runs the XML configurations as a main application.
static String	normalizeURI(String uri)
static String	resolvePath(String dir, String destPath)	Utility method to resolve a provided path against a directory.
void	setJettyStandardIdsAndProperties(Object server, Resource webapp)	Set the standard IDs and properties expected in a jetty XML file: RefId Server Property jetty.home Property jetty.home.uri Property jetty.base Property jetty.base.uri Property jetty.webapps Property jetty.webapps.uri
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

EXECUTABLE_COMPARATOR

public static final Comparator<Executable> EXECUTABLE_COMPARATOR

Constructor Details

XmlConfiguration

public XmlConfiguration(Resource resource)
                 throws SAXException,
IOException

Reads and parses the XML configuration file.

Parameters:

resource - the Resource to the XML configuration

Throws:

IOException - if the configuration could not be read

SAXException - if the configuration could not be parsed

Method Details

setJettyStandardIdsAndProperties

public void setJettyStandardIdsAndProperties(Object server,
 Resource webapp)

Set the standard IDs and properties expected in a jetty XML file:

• RefId Server
• Property jetty.home
• Property jetty.home.uri
• Property jetty.base
• Property jetty.base.uri
• Property jetty.webapps
• Property jetty.webapps.uri

Parameters:

server - The Server object to set

webapp - The webapps Resource

normalizeURI

public static String normalizeURI(String uri)

getXmlParser

public XmlParser getXmlParser()

toString

public String toString()

Overrides:

toString in class Object

getIdMap

public Map<String,Object> getIdMap()

Get the map of ID String to Objects that is used to hold and lookup any objects by ID.

A New, Get or Call XML element may have an id attribute which will cause the resulting object to be placed into this map. A Ref XML element will lookup an object from this map.

When chaining configuration files, it is good practise to copy the ID entries from the ID map to the map of the next configuration, so that they may share an ID space

Returns:

A modifiable map of ID strings to Objects

getProperties

public Map<String,String> getProperties()

Get the map of properties used by the Property XML element to parametrize configuration.

Returns:

A modifiable map of properties.

configure

public Object configure(Object obj)
                 throws Exception

Applies the XML configuration script to the given object.

Parameters:

obj - The object to be configured, which must be of a type or super type of the class attribute of the <Configure> element.

Returns:

the configured object

Throws:

Exception - if the configuration fails

configure

public Object configure()
                 throws Exception

Applies the XML configuration script. If the root element of the configuration has an ID, an object is looked up by ID and its type checked against the root element's type. Otherwise a new object of the type specified by the root element is created.

Returns:

The newly created configured object.

Throws:

Exception - if the configuration fails

initializeDefaults

public void initializeDefaults(Object object)

Initialize a new Object defaults.

This method must be called by any ConfigurationProcessor when it creates a new instance of an object before configuring it, so that a derived XmlConfiguration class may inject default values.

Parameters:

object - the object to initialize defaults on

resolvePath

public static String resolvePath(String dir,
 String destPath)

Utility method to resolve a provided path against a directory.

Parameters:

dir - the directory (should be a directory reference, does not have to exist)

destPath - the destination path (can be relative or absolute, syntax depends on OS + FileSystem in use, and does not need to exist)

Returns:

String to resolved and normalized path, or null if dir or destPath is empty.

main

public static void main(String... args)
                 throws Exception

Runs the XML configurations as a main application. The command line is used to obtain properties files (must be named '*.properties') and XmlConfiguration files.

Any property file on the command line is added to a combined Property instance that is passed to each configuration file via getProperties().

Each configuration file on the command line is used to create a new XmlConfiguration instance and the configure() method is used to create the configured object. If the resulting object is an instance of LifeCycle, then it is started.

Any IDs created in a configuration are passed to the next configuration file on the command line using getIdMap(). This allows objects with IDs created in one config file to be referenced in subsequent config files on the command line.

Parameters:

args - array of property and xml configuration filenames or Resources.

Throws:

Exception - if the XML configurations cannot be run