com.adaptris.util

Class XmlUtils

java.lang.Object

com.adaptris.util.XmlUtils

public class XmlUtils
extends java.lang.Object

Class which provides convenience methods for various aspects of XML usage.

Constructor Summary

Constructors

Constructor and Description
XmlUtils()
XmlUtils(org.xml.sax.EntityResolver er)
XmlUtils(org.xml.sax.EntityResolver er, javax.xml.namespace.NamespaceContext ctx, javax.xml.parsers.DocumentBuilderFactory dbf)
XmlUtils(org.xml.sax.EntityResolver er, javax.xml.transform.URIResolver ur) Deprecated. URIResolver does nothing so use XmlUtils(EntityResolver) instead.
XmlUtils(org.xml.sax.EntityResolver er, javax.xml.transform.URIResolver ur, javax.xml.namespace.NamespaceContext ctx) Deprecated. URIResolver does nothing so use XmlUtils(EntityResolver, NamespaceContext, DocumentBuilderFactory) instead.
XmlUtils(org.xml.sax.EntityResolver er, javax.xml.transform.URIResolver ur, javax.xml.namespace.NamespaceContext ctx, javax.xml.parsers.DocumentBuilderFactory dbf) Deprecated. URIResolver does nothing so use XmlUtils(EntityResolver, NamespaceContext, DocumentBuilderFactory) instead.
XmlUtils(javax.xml.namespace.NamespaceContext ctx) Deprecated.
XmlUtils(javax.xml.namespace.NamespaceContext ctx, javax.xml.parsers.DocumentBuilderFactory f)

Method Summary

Modifier and Type	Method and Description
void	appendNode(org.w3c.dom.Node newNode, org.w3c.dom.Node parent) Convenience method which appends a new Node to the children of a parent
<T> T	castOrFail(java.lang.Object o, java.lang.Class<T> type, java.lang.String exceptionMsg)
org.w3c.dom.Node	createNode(java.lang.String xp) Method which will create a Node path based on the supplied XPath
void	deleteAttribute(java.lang.String name, org.w3c.dom.Node n) Method which deletes an attribute from the specified Node, which must be of type org.w3c.dom.Element.
org.w3c.dom.Document	getCurrentDoc()
java.lang.String[]	getMultipleTextItems(java.lang.String xp) Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".
java.lang.String[]	getMultipleTextItems(java.lang.String xp, org.w3c.dom.Node documentNode) Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.
org.w3c.dom.NodeList	getNodeList(java.lang.String xp) Method which returns a NodeList extracted from the Node created by the setSource method based on the provided xpath String.
org.w3c.dom.NodeList	getNodeList(java.lang.String xp, org.w3c.dom.Node documentNode) Method which returns a NodeList extracted from the provided Node based on the provided xpath String.
java.lang.String	getParseMessage() Method which returns the success / fail message generated by the document parser.
org.w3c.dom.Node	getSingleNode(java.lang.String xp) Method which returns a Node by applying the provided, this Node can either be modified directly using the DOM api or by using the convenience methods in this class.
org.w3c.dom.Node	getSingleNode(java.lang.String xp, org.w3c.dom.Node n) Method which returns a Node by applying the provided relative to the specified root Node.
java.lang.String	getSingleTextItem(java.lang.String xp) Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".
java.lang.String	getSingleTextItem(java.lang.String xp, org.w3c.dom.Node documentNode) Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.
void	insertNodeBefore(org.w3c.dom.Node newNode, org.w3c.dom.Node existingNode, org.w3c.dom.Node parent) Convenience method which enables a new Node to be added to a parent at a specified position, by specifying the Node to insert before.
boolean	isDocumentValid() Method which indicates whether the file was valid
void	removeNode(org.w3c.dom.Node toBeRemoved, org.w3c.dom.Node parent) Convenience method which removes a Node from the children of a parent
void	reset() Re-initialises the XmlUtils object.
void	setAttribute(java.lang.String name, java.lang.String value, org.w3c.dom.Node n) Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element.
void	setAttribute(java.lang.String xp, java.lang.String name, java.lang.String value) Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element.
void	setNodeValue(java.lang.String value, org.w3c.dom.Node n) Method which updates the Text value of a specified Node
void	setNodeValue(java.lang.String xp, java.lang.String value) Method which modifies the value of the Node returned by the XPath query specified.
void	setNodeValue(java.lang.String xp, java.lang.String v, org.w3c.dom.Node root) Method which modifies the value of the Node returned by the XPath query specified, relative to the provided parent node.
void	setSchema(java.lang.String uri) Method added to specify the Schema to Validate against.
void	setSource(org.xml.sax.InputSource xml) Method which sets the source XML document for this class.
void	setSource(java.io.InputStream xml) Method which sets the source XML document for this class.
void	setSource(org.w3c.dom.Node node) Method which sets the source XML document for this class.
void	setSource(java.io.Reader xml) Method which sets the source XML document for this class.
void	writeDocument(org.w3c.dom.Node node, java.io.OutputStream output) Method which writes a Document Node to the specified Writer using ISO-8859-1 encoding
void	writeDocument(org.w3c.dom.Node node, java.io.OutputStream output, java.lang.String encoding) Method which writes a Document Node to the specified Writer using the specified encoding
void	writeDocument(org.w3c.dom.Node node, java.io.Writer writer) Method which writes a Document Node to the specified OutputStream using the specified encoding
void	writeDocument(org.w3c.dom.Node node, java.io.Writer writer, java.lang.String encoding) Write the node to the specified writer.
void	writeDocument(java.io.OutputStream output) Method which writes the document set by setSource to the specified OutputStream using ISO-8859-1 encoding
void	writeDocument(java.io.OutputStream output, java.lang.String encoding) Method which writes a Document Node to the specified OutputStream using the specified encoding
void	writeDocument(java.io.Writer output) Method which writes the document set by setSource to the specified Writer using ISO-8859-1 encoding
void	writeDocument(java.io.Writer output, java.lang.String encoding) Method which writes a Document Node to the specified Writer using the specified encoding

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlUtils

public XmlUtils()

XmlUtils

public XmlUtils(org.xml.sax.EntityResolver er)

XmlUtils

@Deprecated
public XmlUtils(javax.xml.namespace.NamespaceContext ctx)

Deprecated.

XmlUtils

public XmlUtils(javax.xml.namespace.NamespaceContext ctx,
                javax.xml.parsers.DocumentBuilderFactory f)

XmlUtils

@Deprecated
public XmlUtils(org.xml.sax.EntityResolver er,
                            javax.xml.transform.URIResolver ur)

Deprecated. URIResolver does nothing so use XmlUtils(EntityResolver) instead.

XmlUtils

@Deprecated
public XmlUtils(org.xml.sax.EntityResolver er,
                            javax.xml.transform.URIResolver ur,
                            javax.xml.namespace.NamespaceContext ctx)

Deprecated. URIResolver does nothing so use XmlUtils(EntityResolver, NamespaceContext, DocumentBuilderFactory) instead.

XmlUtils

@Deprecated
public XmlUtils(org.xml.sax.EntityResolver er,
                            javax.xml.transform.URIResolver ur,
                            javax.xml.namespace.NamespaceContext ctx,
                            javax.xml.parsers.DocumentBuilderFactory dbf)

Deprecated. URIResolver does nothing so use XmlUtils(EntityResolver, NamespaceContext, DocumentBuilderFactory) instead.

XmlUtils

public XmlUtils(org.xml.sax.EntityResolver er,
                javax.xml.namespace.NamespaceContext ctx,
                javax.xml.parsers.DocumentBuilderFactory dbf)

Method Detail

setSchema

public void setSchema(java.lang.String uri)
               throws java.lang.Exception

Method added to specify the Schema to Validate against. If not set, document will not be validated.

Parameters:

uri - the URI to validate against.

Throws:

java.lang.Exception - on error.

setSource

public void setSource(org.xml.sax.InputSource xml)

Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

This method not only receives the document, but it is immediately compiled into a DOM Object.

Parameters:

xml - the InputSource

setSource

public void setSource(java.io.Reader xml)

Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

This method not only receives the document, but it is immediately compiled into a DOM Object.

Parameters:

xml - the Reader

setSource

public void setSource(java.io.InputStream xml)

Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

This method not only receives the document, but it is immediately compiled into a DOM Object.

Parameters:

xml - the inputstream for the source

setSource

public void setSource(org.w3c.dom.Node node)

Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

Parameters:

node - a Node object of type Document

getSingleTextItem

public java.lang.String getSingleTextItem(java.lang.String xp,
                                          org.w3c.dom.Node documentNode)

Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.

Null will be returned if the provided XPath fails to retrieve a Node of the above types.

The provided String is compiled into an XPath and stored for future use.

Parameters:

xp - the Xpath query

documentNode - the Node to operate on.

Returns:

the text string returned by the Xpath

getSingleTextItem

public java.lang.String getSingleTextItem(java.lang.String xp)

Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".

Null will be returned if the provided XPath fails to retrieve a Node of the above types.

The provided String is compiled into an XPath and stored for future use.

Parameters:

xp - the Xpath

Returns:

the string representing the text item returned by the query

getMultipleTextItems

public java.lang.String[] getMultipleTextItems(java.lang.String xp,
                                               org.w3c.dom.Node documentNode)

Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.

Null will be returned if the provided XPath fails to retrieve any Nodes of the above types.

The provided String is compiled into an XPath and stored for future use.

Parameters:

xp - the xpath

documentNode - the starting node.

Returns:

an array of String objects that were returned by the query.

getMultipleTextItems

public java.lang.String[] getMultipleTextItems(java.lang.String xp)

Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".

Null will be returned if the provided XPath fails to retrieve any Nodes of the above types.

The provided String is compiled into an XPath and stored for future use.

Parameters:

xp - the Xpath query.

Returns:

an array of String objects returned by the query.

getNodeList

public org.w3c.dom.NodeList getNodeList(java.lang.String xp,
                                        org.w3c.dom.Node documentNode)

Method which returns a NodeList extracted from the provided Node based on the provided xpath String. An example of the functionality of this would be to extract multiple documents from within an envelope structure and then to use the extracted Nodes to perform more granular queries on the extracted data.

Parameters:

xp - the Xpath query

documentNode - the Node to search on.

Returns:

the NodeList returned by the query.

getNodeList

public org.w3c.dom.NodeList getNodeList(java.lang.String xp)

Method which returns a NodeList extracted from the Node created by the setSource method based on the provided xpath String. An example of the functionality of this would be to extract multiple documents from within an envelope structure and then to use the extracted Nodes to perform more granular queries on the extracted data.

Parameters:

xp - the Xpath query

Returns:

the NodeList returned by the query.

getSingleNode

public org.w3c.dom.Node getSingleNode(java.lang.String xp)

Method which returns a Node by applying the provided, this Node can either be modified directly using the DOM api or by using the convenience methods in this class.

Parameters:

xp - the XPath which will return the Node

Returns:

the Node.

getSingleNode

public org.w3c.dom.Node getSingleNode(java.lang.String xp,
                                      org.w3c.dom.Node n)

Method which returns a Node by applying the provided relative to the specified root Node. This Nodecan either be modified directly using the DOM api or by using the convenience methods in this class.

Parameters:

xp - the XPath which will return the Node

n - the root node to apply the XPath to

Returns:

The Node.

reset

public void reset()
           throws java.lang.Exception

Re-initialises the XmlUtils object. Clears down parsed XML message and compiled XPaths

Throws:

java.lang.Exception - on any error.

isDocumentValid

public boolean isDocumentValid()

Method which indicates whether the file was valid

Returns:

true if the document is valid

getParseMessage

public java.lang.String getParseMessage()

Method which returns the success / fail message generated by the document parser.

Returns:

the error message.

createNode

public org.w3c.dom.Node createNode(java.lang.String xp)
                            throws java.lang.Exception

Method which will create a Node path based on the supplied XPath

Parameters:

xp - the xpath.

Returns:

the Node that was constructed from the xpath.

Throws:

java.lang.Exception - on error.

setNodeValue

public void setNodeValue(java.lang.String xp,
                         java.lang.String value)
                  throws java.lang.Exception

Method which modifies the value of the Node returned by the XPath query specified.

Parameters:

xp - the XPath which will return the Node to be updated

value - the new value to set the node to

Throws:

java.lang.Exception - on error.

setNodeValue

public void setNodeValue(java.lang.String xp,
                         java.lang.String v,
                         org.w3c.dom.Node root)
                  throws java.lang.Exception

Method which modifies the value of the Node returned by the XPath query specified, relative to the provided parent node.

Parameters:

xp - the XPath which will return the Node to be updated

v - the new value to set the node to

root - the root node to apply the XPath to

Throws:

java.lang.Exception - on error.

setNodeValue

public void setNodeValue(java.lang.String value,
                         org.w3c.dom.Node n)
                  throws java.lang.Exception

Method which updates the Text value of a specified Node

Parameters:

value - the new Text value

n - the node to be modified

Throws:

java.lang.Exception - on error.

setAttribute

public void setAttribute(java.lang.String xp,
                         java.lang.String name,
                         java.lang.String value)
                  throws java.lang.Exception

Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element. If the attribute already exists, it will be updated with the new value.

Parameters:

xp - to retrieve the node to be modified

name - the attribute name

value - the new value

Throws:

java.lang.Exception - on error.

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.String value,
                         org.w3c.dom.Node n)
                  throws java.lang.Exception

Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element. If the attribute already exists, it will be updated with the new value.

Parameters:

name - the attribute name

value - the new value

n - the node to be modified

Throws:

java.lang.Exception - on error.

deleteAttribute

public void deleteAttribute(java.lang.String name,
                            org.w3c.dom.Node n)
                     throws java.lang.Exception

Method which deletes an attribute from the specified Node, which must be of type org.w3c.dom.Element.

Parameters:

name - the attribute name

n - the node to be modified

Throws:

java.lang.Exception - on error.

insertNodeBefore

public void insertNodeBefore(org.w3c.dom.Node newNode,
                             org.w3c.dom.Node existingNode,
                             org.w3c.dom.Node parent)
                      throws java.lang.Exception

Convenience method which enables a new Node to be added to a parent at a specified position, by specifying the Node to insert before. Here is a sample of how to use:

   

   // Example of how to insert a Node as the 3rd child of a parent
   Node p  = xmlUtils.getSingleNode("/mydoc/parent");
   Node c   = xmlUtils.getSingleNode("/mydoc/parent/child[4]");
   Node n = // Node creation code here;
   xmlUtils.insertNodeBefore(newNode, child, parent);

 
 

Parameters:

newNode - the Node to be added

existingNode - the Node to insert before

parent - the parent Node

Throws:

java.lang.Exception - on error.

appendNode

public void appendNode(org.w3c.dom.Node newNode,
                       org.w3c.dom.Node parent)
                throws java.lang.Exception

Convenience method which appends a new Node to the children of a parent

Parameters:

newNode - the Node to be added

parent - the parent Node

Throws:

java.lang.Exception - on error.

removeNode

public void removeNode(org.w3c.dom.Node toBeRemoved,
                       org.w3c.dom.Node parent)
                throws java.lang.Exception

Convenience method which removes a Node from the children of a parent

Parameters:

toBeRemoved - the Node to be Removed

parent - the parent Node

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(java.io.OutputStream output)
                   throws java.lang.Exception

Method which writes the document set by setSource to the specified OutputStream using ISO-8859-1 encoding

Parameters:

output - the Outputstream

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(java.io.Writer output)
                   throws java.lang.Exception

Method which writes the document set by setSource to the specified Writer using ISO-8859-1 encoding

Parameters:

output - the Outputstream

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(java.io.OutputStream output,
                          java.lang.String encoding)
                   throws java.lang.Exception

Method which writes a Document Node to the specified OutputStream using the specified encoding

Parameters:

encoding - the encoding type.

output - the Outputstream

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(java.io.Writer output,
                          java.lang.String encoding)
                   throws java.lang.Exception

Method which writes a Document Node to the specified Writer using the specified encoding

Parameters:

encoding - the encoding type.

output - the Outputstream

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(org.w3c.dom.Node node,
                          java.io.OutputStream output)
                   throws java.lang.Exception

Method which writes a Document Node to the specified Writer using ISO-8859-1 encoding

Parameters:

node - the Node to write.

output - the Outputstream to use.

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(org.w3c.dom.Node node,
                          java.io.Writer writer)
                   throws java.lang.Exception

Method which writes a Document Node to the specified OutputStream using the specified encoding

Parameters:

node - the node to write.

writer - the Writer

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(org.w3c.dom.Node node,
                          java.io.OutputStream output,
                          java.lang.String encoding)
                   throws java.lang.Exception

Method which writes a Document Node to the specified Writer using the specified encoding

Parameters:

node - the Node to write.

output - the Outputstream to use.

encoding - the Encoding.

Throws:

java.lang.Exception - on error.

writeDocument

public void writeDocument(org.w3c.dom.Node node,
                          java.io.Writer writer,
                          java.lang.String encoding)
                   throws java.lang.Exception

Write the node to the specified writer.

Parameters:

node - a Document object

writer - the writer to use.

encoding - the encoding format.

Throws:

java.lang.Exception - on error.

getCurrentDoc

public org.w3c.dom.Document getCurrentDoc()

castOrFail

public <T> T castOrFail(java.lang.Object o,
                        java.lang.Class<T> type,
                        java.lang.String exceptionMsg)
                 throws java.lang.Exception

Throws:

java.lang.Exception