toolbox.allegato
Class XMLProperties

java.lang.Object
  toolbox.allegato.XMLProperties

public class XMLProperties
extends java.lang.Object

Provides access to XML configuration properties. Provides some convenience methods that provide easier access to XML elements and attributes.

Instances of this class may also make use of a pre-processor through the use of an XMLPreProcessor implementation. The pre-processor implementation can be specified with the following system property:
toolbox.allegato.XMLProperties.PreProcessor

The behaviour of the XML parser used by instances of this class can be altered with the following system properties:

• toolbox.allegato.XMLProperties.namespace.aware: Boolean property indicating whether instances will be namespace aware. False by default.
• toolbox.allegato.XMLProperties.validating: Boolean property indicating whether instances will perform XML validation. False by default.
• toolbox.allegato.XMLProperties.ignore.doctype: Boolean property indicating whether instances will ignore the DOCTYPE declaration in XML documents when parsing. This is useful for stopping XML parsers going over the network to obtain DTD's when no local catalog or copy is available. The XMLProperties class makes use of the EmptyEntityResolver of this package. If entities must be resolved make use of the Apache xml-commons Resolver integration discussed below. This property is true by default.
• toolbox.allegato.XMLProperties.catalog.config: Name of a Java properties file, available via the classpath, that can be consumed by the Apache xml-commons Resolver (http://xml.apache.org/commons/) CatalogManager class. This implies that the resolver.jar file is available on the classpath. This is useful for resolving the public and/or system id's of DOCTYPE declarations to local DTD instances.

  A properties file for use with the Toolbox framework is available at share/dtd/toolbox_catalogs.properties. The share/dtd directory of the framework must be configured as part of the classpath for this to work.

Constructor Summary

XMLProperties(java.io.InputStream is)
Constructs a new XMLProperties object from the given InputStream.

XMLProperties(java.io.InputStream is, boolean doProps)
Construct a new XMLProperties object from the given InputStream and convert the member Document instance to Java properties if required.

XMLProperties(java.lang.String fileName)
Constructs a new XMLProperties object from the given file name.

XMLProperties(java.lang.String fileName, boolean doProps)
Construct a new XMLProperties object from the given file name and convert the member Document instance to Java properties if required.

Method Summary

java.lang.String	getAttributeValue(org.w3c.dom.Element element, java.lang.String name) Returns the value of the named attribute within the given element.
org.w3c.dom.Document	getDocument() Returns the member document for this XMLProperties object.
org.w3c.dom.Element	getElement(org.w3c.dom.Element parent, java.lang.String name) Returns the named child element within the given parent element.
org.w3c.dom.Element	getElement(java.lang.String name) Returns the element with the given name.
org.w3c.dom.Element	getElement(java.lang.String parentName, java.lang.String name) Returns the element within the named parent element.
org.w3c.dom.Element	getElementByNameAttr(java.lang.String elementName, java.lang.String nameAttrVal) Returns the Element with the given name and "name attribute" with the given value.
org.w3c.dom.NodeList	getElements(org.w3c.dom.Element parent, java.lang.String name) Returns all the child nodes with the given name within the given parent element.
java.util.Properties	getProperties() Return the member properties for this XMLProperties object.
java.lang.String	getTextNodeValue(org.w3c.dom.Element parent, java.lang.String name) Returns the value of the named text node within the given parent element.
java.lang.String	getTextNodeValue(org.w3c.dom.Node textNode) Returns the value of the given text node.

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLProperties

public XMLProperties(java.io.InputStream is)
              throws ConfException

Constructs a new XMLProperties object from the given InputStream.

Parameters:

is - InputStream containing XML data.

Throws:

ConfException - if the InputStream cannot be parsed.

XMLProperties

public XMLProperties(java.lang.String fileName)
              throws ConfException,
                     java.io.IOException

Constructs a new XMLProperties object from the given file name.

Parameters:

fileName - Name of file containing XML data.

Throws:

ConfException - if an exception occurs while parsing the XML document.

java.io.IOException - if the file does not exist.

XMLProperties

public XMLProperties(java.io.InputStream is,
                     boolean doProps)
              throws ConfException

Construct a new XMLProperties object from the given InputStream and convert the member Document instance to Java properties if required.

Parameters:

is - InputStream containing XML data.

doProps - If true convert the Document instance into Java properties.

Throws:

ConfException - if the InputStream cannot be parsed.

XMLProperties

public XMLProperties(java.lang.String fileName,
                     boolean doProps)
              throws ConfException,
                     java.io.IOException

Construct a new XMLProperties object from the given file name and convert the member Document instance to Java properties if required.

Parameters:

fileName - Name of the file containing XML data.

doProps - If true convert the Document instance into Java properties.

Throws:

ConfException - if the file cannat be parsed.

java.io.IOException - if the file does not exist.

Method Detail

getElement

public org.w3c.dom.Element getElement(java.lang.String name)
                               throws ConfException

Returns the element with the given name.

Parameters:

name - Name of the XML element that must be returned.

Returns:

Element with the given name.

Throws:

ConfException - if the element cannot be found

getElementByNameAttr

public org.w3c.dom.Element getElementByNameAttr(java.lang.String elementName,
                                                java.lang.String nameAttrVal)
                                         throws ConfException

Returns the Element with the given name and "name attribute" with the given value.

Parameters:

elementName - Name of the element to return.

nameAttrVal - Value of the name attribute.

Returns:

Element

Throws:

ConfException - if the element could not be found.

getElement

public org.w3c.dom.Element getElement(java.lang.String parentName,
                                      java.lang.String name)
                               throws ConfException

Returns the element within the named parent element.

Parameters:

parentName - Name of the parent element.

name - Name of the element that must be returned.

Returns:

Element with the given name.

Throws:

ConfException - if the named elements does not exist.

getElement

public org.w3c.dom.Element getElement(org.w3c.dom.Element parent,
                                      java.lang.String name)
                               throws ConfException

Returns the named child element within the given parent element.

Parameters:

parent - Parent element.

name - Name of child element.

Returns:

Element with the given name.

Throws:

ConfException - if the parent does not contain the named child element.

getElements

public org.w3c.dom.NodeList getElements(org.w3c.dom.Element parent,
                                        java.lang.String name)
                                 throws ConfException

Returns all the child nodes with the given name within the given parent element.

Parameters:

parent - Parent element containing the named children.

name - Name of the child nodes to return. If null, returns all child nodes.

Returns:

NodeList containing the child nodes.

Throws:

ConfException - if the parent does not contain any children with the given name.

getTextNodeValue

public java.lang.String getTextNodeValue(org.w3c.dom.Node textNode)

Returns the value of the given text node.

Parameters:

textNode - The given text node.

Returns:

String containing the value of the text node. Null if the node has no value.

getTextNodeValue

public java.lang.String getTextNodeValue(org.w3c.dom.Element parent,
                                         java.lang.String name)
                                  throws ConfException

Returns the value of the named text node within the given parent element.

Parameters:

parent - Parent element.

name - Name of the text node.

Returns:

String containing the value of the named text node or null if the named node is not a text node.

Throws:

ConfException - if the named node does not exist

getAttributeValue

public java.lang.String getAttributeValue(org.w3c.dom.Element element,
                                          java.lang.String name)
                                   throws ConfException

Returns the value of the named attribute within the given element.

Parameters:

element - Given element.

name - Attribute name.

Returns:

String containing the value of the named attribute. Null if the attribute has no value.

Throws:

ConfException - if the attribute does not exist.

getProperties

public java.util.Properties getProperties()

Return the member properties for this XMLProperties object.

Returns:

Properties instance or null if the properties were not initialised.

getDocument

public org.w3c.dom.Document getDocument()

Returns the member document for this XMLProperties object.

Returns:

Document containing the XML configuration.