com.hyfinity.utils.xml

Class DOMUtils

java.lang.Object

com.hyfinity.utils.xml.DOMUtils

public final class DOMUtils
extends java.lang.Object

Static convenience methods to make Document Object Model programming easier.

Author:

Rafel Bordas, Gerard Smyth

Method Summary

Methods

Modifier and Type	Method and Description
static boolean	createXPathElements(org.w3c.dom.Node node, java.lang.String xpathStr, XPathFactory xpf) Attempts to create the needed elements under the provided node so that the given XPath will match an element when evaluated against the node.
static org.w3c.dom.Node	getElement(org.w3c.dom.Node node) Returns the corresponding element.
static org.w3c.dom.Document	getOwnerDocument(org.w3c.dom.Node node) Gets the owner Document of a Node.
static DOMSerializer	getSerializer() Gets the shared serializer instance.
static DOMSerializer	getSpecificSerializer() Gets a specific serializer instance.
static DOMSerializer	getSpecificSerializer(java.lang.String className) Gets a specific serializer instance, using the specified implementiona This should be used whenever you need to change the serilaizer settings, or need to always use a specific implementation regardless of the platform configuration.
static java.lang.String	getText(org.w3c.dom.Node node) Returns the textual contents of a Node.
static javax.xml.transform.Templates	getXSLTemplates(java.lang.String filename) Attempts to load a Templates object for the XSL stylesheet at the given filename.
static javax.xml.transform.Templates	getXSLTemplates(java.lang.String filename, javax.xml.transform.ErrorListener listener) Attempts to load a Templates object for the XSL stylesheet at the given filename.
static javax.xml.transform.Transformer	getXSLTransformer(java.lang.String filename) Attempts to load a Transformer object for the XSL stylesheet at the given filename.
static javax.xml.transform.Transformer	getXSLTransformer(java.lang.String filename, javax.xml.transform.ErrorListener listener) Attempts to load a Transformer object for the XSL stylesheet at the given filename.
static javax.xml.transform.Transformer	getXSLTransformer(javax.xml.transform.Templates templates) Attempts to create a Transformer object from a given XSL Templates.
static javax.xml.transform.Transformer	getXSLTransformer(javax.xml.transform.Templates templates, javax.xml.transform.ErrorListener listener) Attempts to create a Transformer object from a given XSL Templates, attaching the given ErrorListener to the returned Transformer for reporting transform errors.
static boolean	hasNonTextChildNodes(org.w3c.dom.Node node) Checks whether the provided DOM Node contains any child nodes that are not text nodes.
static org.w3c.dom.Document	newDocument() Returns a new empty DOM Document.
static org.w3c.dom.Document	newDocument(java.io.InputStream is) Returns a new DOM Document containing the XML read from the supplied InputStream.
static org.w3c.dom.Document	newDocument(java.lang.String xmlString) Returns a new DOM Document containing the XML in the supplied string.
static void	setText(org.w3c.dom.Node targetNode, java.lang.String text) Sets the contents of the provided node to the given text.

Methods inherited from class java.lang.Object

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

Method Detail

getOwnerDocument

public static org.w3c.dom.Document getOwnerDocument(org.w3c.dom.Node node)

Gets the owner Document of a Node. Returns the owner Document of a Node or the Node itself if it is a Document. This differs from the standard getOwnerDocument method in that it does not return null if the Node argument is a Document.

Parameters:

node - The node whose owner Document is required.

Returns:

The owner Document.

getElement

public static org.w3c.dom.Node getElement(org.w3c.dom.Node node)

Returns the corresponding element. If the supplied Node is a Document then this will return the document element, otherwise it will return the supplied Node.

Parameters:

node - The node to find an element for.

Returns:

The node itself or the Document element.

getText

public static java.lang.String getText(org.w3c.dom.Node node)

Returns the textual contents of a Node. Concatenates the contents of all the text nodes who are immediate children of the argument node and returns the result.

Parameters:

node - The node whose child text is required.

Returns:

A concatenated string of the contents of all child text nodes.

setText

public static void setText(org.w3c.dom.Node targetNode,
           java.lang.String text)

Sets the contents of the provided node to the given text. Any existing child nodes of the targetNode will be removed, and a single text node added containing the provided text.

Parameters:

targetNode - target node

text - text

hasNonTextChildNodes

public static boolean hasNonTextChildNodes(org.w3c.dom.Node node)

Checks whether the provided DOM Node contains any child nodes that are not text nodes. This differs from the standard hasChildNodes() method, as if the node only contains text node children, this will return false, where as hasChildNodes would return true.

Parameters:

node - The DOM node to check the children of.

Returns:

boolean true or false depending on whether the node has non text node children.

newDocument

public static org.w3c.dom.Document newDocument()

Returns a new empty DOM Document.

Returns:

the created Document.

newDocument

public static org.w3c.dom.Document newDocument(java.lang.String xmlString)

Returns a new DOM Document containing the XML in the supplied string.

Parameters:

xmlString - The String containing the XML content to parse into the new Document

Returns:

the created Document.

newDocument

public static org.w3c.dom.Document newDocument(java.io.InputStream is)

Returns a new DOM Document containing the XML read from the supplied InputStream.

Parameters:

is - The InputStream to read the XML content from.

Returns:

the created Document.

getSerializer

public static DOMSerializer getSerializer()

Gets the shared serializer instance. This serializer is set to escape the standard entities. You should not make any chanegs to the settings of this serializer. The returned Serializer is thread safe.

Returns:

the DOMSerializer object.

getSpecificSerializer

public static DOMSerializer getSpecificSerializer()

Gets a specific serializer instance. This should be used whenever you need to change the serilaizer settings. Wherever possible, the shared serializer should be used instead.

Returns:

the DOMSerializer object.

getSpecificSerializer

public static DOMSerializer getSpecificSerializer(java.lang.String className)

Gets a specific serializer instance, using the specified implementiona This should be used whenever you need to change the serilaizer settings, or need to always use a specific implementation regardless of the platform configuration. Wherever possible, the shared serializer should be used instead.

Parameters:

className - The name of the serializer implementation to use.

Returns:

the DOMSerializer object.

createXPathElements

public static boolean createXPathElements(org.w3c.dom.Node node,
                          java.lang.String xpathStr,
                          XPathFactory xpf)

Attempts to create the needed elements under the provided node so that the given XPath will match an element when evaluated against the node. This will only handle simple location steps in the XPath. It will not work if there is any use of functions or predicates etc.

Parameters:

node - The DOM node that the XPath should be evalauted from.

xpathStr - The XPath string to try and make match.

xpf - The XPathFactory that has the namespace context etc that should be used.

Returns:

boolean, true if the XPath will now match, false if the correct elements could not be created.

getXSLTemplates

public static javax.xml.transform.Templates getXSLTemplates(java.lang.String filename)
                                                     throws javax.xml.transform.TransformerFactoryConfigurationError,
                                                            javax.xml.transform.TransformerConfigurationException

Attempts to load a Templates object for the XSL stylesheet at the given filename. This option uses a standard ErrorListener that ignores all except fatal errors, in which case an exception will be thrown.

Parameters:

filename - The absolute path of the XSL file to load.

Returns:

a Templates object that can be used to create Transformers later using the getXSLTransformer method.

Throws:

javax.xml.transform.TransformerFactoryConfigurationError - if error initialising the TransformerFactory or XMLReader

javax.xml.transform.TransformerConfigurationException - if error creating Templates

getXSLTransformer

public static javax.xml.transform.Transformer getXSLTransformer(javax.xml.transform.Templates templates)
                                                         throws javax.xml.transform.TransformerConfigurationException

Attempts to create a Transformer object from a given XSL Templates. This option uses a standard ErrorListener that ignores all except fatal errors, in which case a exception will be thrown.

Parameters:

templates - The Templates to create the transformer from.

Returns:

The created Transformer object for performing a transform.

Throws:

javax.xml.transform.TransformerConfigurationException - if error creating Transformer

getXSLTransformer

public static javax.xml.transform.Transformer getXSLTransformer(java.lang.String filename)
                                                         throws javax.xml.transform.TransformerFactoryConfigurationError,
                                                                javax.xml.transform.TransformerConfigurationException

Attempts to load a Transformer object for the XSL stylesheet at the given filename. This is a wrapper around using both getXSLTemplates and then getXSLTransformer with that Templates object. This option uses a standard ErrorListener that ignores all except fatal errors, in which case an exception will be thrown.

Parameters:

filename - The absolute path of the XSL file to load.

Returns:

The created Transformer object for performing a transform.

Throws:

javax.xml.transform.TransformerFactoryConfigurationError - if error initialising the TransformerFactory or XMLReader

javax.xml.transform.TransformerConfigurationException - if error creating Templates or Transformer

getXSLTemplates

public static javax.xml.transform.Templates getXSLTemplates(java.lang.String filename,
                                            javax.xml.transform.ErrorListener listener)
                                                     throws javax.xml.transform.TransformerFactoryConfigurationError,
                                                            javax.xml.transform.TransformerConfigurationException

Attempts to load a Templates object for the XSL stylesheet at the given filename. This option attaches the provided ErrorListener to the TransformerFactory to handle XSL parsing errors. As with creating DOM documents, a DefaultHandler is used for handling errors from parsing the XSL file.

Parameters:

filename - The absolute path of the XSL file to load.

listener - The ErrorListener to use.

Returns:

a Templates object that can be used to create Transformers later using the getXSLTransformer method.

Throws:

javax.xml.transform.TransformerFactoryConfigurationError - if error initialising the TransformerFactory or XMLReader

javax.xml.transform.TransformerConfigurationException - if error creating Templates

getXSLTransformer

public static javax.xml.transform.Transformer getXSLTransformer(javax.xml.transform.Templates templates,
                                                javax.xml.transform.ErrorListener listener)
                                                         throws javax.xml.transform.TransformerConfigurationException

Attempts to create a Transformer object from a given XSL Templates, attaching the given ErrorListener to the returned Transformer for reporting transform errors.

Parameters:

templates - The Templates to create the transformer from.

listener - The ErrorListener to use.

Returns:

The created Transformer object for performing a transform.

Throws:

javax.xml.transform.TransformerConfigurationException - if error creating Transformer

getXSLTransformer

public static javax.xml.transform.Transformer getXSLTransformer(java.lang.String filename,
                                                javax.xml.transform.ErrorListener listener)
                                                         throws javax.xml.transform.TransformerFactoryConfigurationError,
                                                                javax.xml.transform.TransformerConfigurationException

Attempts to load a Transformer object for the XSL stylesheet at the given filename. This is a wrapper around using both getXSLTemplates and then getXSLTransformer with that Templates object.

Parameters:

filename - The absolute path of the XSL file to load.

listener - The ErrorListener to use.

Returns:

The created Transformer object for performing a transform.

Throws:

javax.xml.transform.TransformerFactoryConfigurationError - if error initialising the TransformerFactory or XMLReader

javax.xml.transform.TransformerConfigurationException - if error creating Templates or Transformer