org.gicentre.utils.io

Class DOMProcessor

java.lang.Object

org.gicentre.utils.io.DOMProcessor

public class DOMProcessor
extends java.lang.Object

Handles DOM processing allowing the reading and writing of hierarchical structures as XML files. Uses the Document Object Model (DOM) to store the tree of nodes, therefore not suitable for very large structures. For reading very large structures represented as XML, use SAX processing instead.

Version:

3.4, 5th February, 2016.

Author:

Jo Wood, giCentre, City University London.

Constructor Summary

Constructors

Constructor and Description
DOMProcessor() Creates a new empty DOM ready for processing.
DOMProcessor(org.w3c.dom.Document dom) Wraps the given DOM in this processor allowing it to be written as an XML file, or appended with new nodes.
DOMProcessor(java.io.InputStream inStream) Reads XML from the given input stream and constructs a DOM from it.
DOMProcessor(java.lang.String fileName) Reads and the given XML file and constructs a DOM from it.

Method Summary

Modifier and Type	Method and Description
static void	addAttribute(java.lang.String name, java.lang.String value, org.w3c.dom.Node node) Adds the given attribute to the given node.
void	addComment(java.lang.String comment) Adds the given comment to the root of the DOM.
void	addComment(java.lang.String comment, org.w3c.dom.Node node) Adds the given comment to the given node.
org.w3c.dom.Node	addElement(java.lang.String name) Adds a new element to the root of the DOM.
org.w3c.dom.Node	addElement(java.lang.String name, org.w3c.dom.Node existingElement) Adds a new element to the given one within the DOM.
org.w3c.dom.Node	addElement(java.lang.String name, java.lang.String text, org.w3c.dom.Node existingElement) Adds a new element to the given one within the DOM.
void	addText(java.lang.String text, org.w3c.dom.Node node) Adds text as the child of the given node.
java.lang.String[]	getAttributes(java.lang.String attributeName) Searches the entire DOM for a given attribute and returns the value associated with it.
java.lang.String[]	getAttributes(java.lang.String attributeName, org.w3c.dom.Node node) Searches the given node and its children for a given attribute and returns the value associated with it.
org.w3c.dom.Node[]	getElements(java.lang.String name) Returns a list of the DOM elements with the given name.
org.w3c.dom.Node[]	getElements(java.lang.String name, org.w3c.dom.Node node) Returns a list of the DOM elements with the given name that are nested within the given node.
static java.lang.String	getNodeAttribute(java.lang.String attributeName, org.w3c.dom.Node node) Searches the given node for a given attribute and returns the value associated with it.
static org.w3c.dom.Node	getNodeElement(java.lang.String name, org.w3c.dom.Node node) Returns a DOM element with the given name that is the child of the given node.
static org.w3c.dom.Node[]	getNodeElements(java.lang.String name, org.w3c.dom.Node node) Returns the DOM elements with the given name that are the children of the given node.
static java.lang.String	getNodeText(org.w3c.dom.Node node) Searches for a given node and returns text associated with it.
java.lang.String[]	getText(org.w3c.dom.Node node) Returns any text associated found in the given node or its children.
java.lang.String[]	getText(java.lang.String elementName) Searches the entire DOM for a given element and returns text associated with it.
java.lang.String[]	getText(java.lang.String elementName, org.w3c.dom.Node node) Searches for a given element and returns text associated with it.
boolean	isEmpty() Reports whether we have an empty DOM.
boolean	readXML(java.io.InputStream inStream) Reads the XML from the given input stream and converts it into a DOM.
boolean	readXML(java.lang.String fileName) Reads the given XML file and converts it into a DOM.
void	renameElement(org.w3c.dom.Node existingElement, java.lang.String newName) Renames the given element with the given new name.
boolean	writeXML() Displays the DOM stored within this class as an XML file with default document settings on standard output.
boolean	writeXML(java.io.OutputStream outStream) Converts the DOM stored within this class into an XML file with default document settings.
boolean	writeXML(java.io.OutputStream outStream, java.lang.String version, java.lang.String encoding, java.lang.Boolean standalone) Converts the DOM stored within this class into an XML file with the given document settings.
boolean	writeXML(java.lang.String fileName) Converts the DOM stored within this class into an XML file with default document settings.
boolean	writeXML(java.lang.String version, java.lang.String encoding, java.lang.Boolean standalone) Displays the DOM stored within this class as an XML file with the given document settings on standard output.
boolean	writeXML(java.lang.String fileName, java.lang.String version, java.lang.String encoding, java.lang.Boolean standalone) Converts the DOM stored within this class into an XML file with the given document settings.

Methods inherited from class java.lang.Object

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

Constructor Detail

DOMProcessor

public DOMProcessor()

Creates a new empty DOM ready for processing.

DOMProcessor

public DOMProcessor(org.w3c.dom.Document dom)

Wraps the given DOM in this processor allowing it to be written as an XML file, or appended with new nodes.

Parameters:

dom - Document Object Model to use in processor.

DOMProcessor

public DOMProcessor(java.lang.String fileName)

Reads and the given XML file and constructs a DOM from it.

Parameters:

fileName - Name of XML file to read.

DOMProcessor

public DOMProcessor(java.io.InputStream inStream)

Reads XML from the given input stream and constructs a DOM from it.

Parameters:

inStream - Stream from which to read XML.

Method Detail

isEmpty

public boolean isEmpty()

Reports whether we have an empty DOM.

Returns:

True if DOM is empty.

addElement

public org.w3c.dom.Node addElement(java.lang.String name)

Adds a new element to the root of the DOM.

Parameters:

name - Name of the new element

Returns:

New element in the DOM.

addElement

public org.w3c.dom.Node addElement(java.lang.String name,
                                   org.w3c.dom.Node existingElement)

Adds a new element to the given one within the DOM.

Parameters:

name - Name of the new element

existingElement - Element onto which the new element should be attached.

Returns:

New element in the DOM.

addElement

public org.w3c.dom.Node addElement(java.lang.String name,
                                   java.lang.String text,
                                   org.w3c.dom.Node existingElement)

Adds a new element to the given one within the DOM.

Parameters:

name - Name of the new element

text - Text to attach to element or null if none required.

existingElement - Element onto which the new element should be attached.

Returns:

New element in the DOM.

renameElement

public void renameElement(org.w3c.dom.Node existingElement,
                          java.lang.String newName)

Renames the given element with the given new name.

Parameters:

existingElement - Element to rename.

newName - New name to give element.

addAttribute

public static void addAttribute(java.lang.String name,
                                java.lang.String value,
                                org.w3c.dom.Node node)

Adds the given attribute to the given node.

Parameters:

name - Attribute name.

value - Attribute value.

node - Element to attach attribute.

addComment

public void addComment(java.lang.String comment)

Adds the given comment to the root of the DOM. Note that this method should only be called once a root node has been created in the DOM.

Parameters:

comment - Comment text.

addComment

public void addComment(java.lang.String comment,
                       org.w3c.dom.Node node)

Adds the given comment to the given node.

Parameters:

comment - Comment text.

node - Element to attach comment.

addText

public void addText(java.lang.String text,
                    org.w3c.dom.Node node)

Adds text as the child of the given node.

Parameters:

text - Text to add to node.

node - Element to attach text.

getText

public java.lang.String[] getText(java.lang.String elementName)

Searches the entire DOM for a given element and returns text associated with it. If more than one element with the given name exists, multiple text values are returned.

Parameters:

elementName - Element to search for.

Returns:

Array of strings associated with all occurrences of the given element. Array will be 0 length if none found.

getText

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

Returns any text associated found in the given node or its children. This is equivalent to calling getText(null,node). If more than one element containing text exists, multiple text values are returned.

Parameters:

node - Node from which to start search.

Returns:

Array of strings associated with all occurrences of text in the node or its children. Array will be 0 length if none found.

getText

public java.lang.String[] getText(java.lang.String elementName,
                                  org.w3c.dom.Node node)

Searches for a given element and returns text associated with it. If more than one element with the given name exists, multiple text values are returned.

Parameters:

elementName - Element to search for. If elementName is null, search will be for all text contained within the given node.

node - Node from which to start search.

Returns:

Array of strings associated with all occurrences of the given element. Array will be 0 length if none found.

getNodeText

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

Searches for a given node and returns text associated with it. This version does not recurse to the node's children.

Parameters:

node - Node to search.

Returns:

Text associated with the node, or null if none found.

getAttributes

public java.lang.String[] getAttributes(java.lang.String attributeName)

Searches the entire DOM for a given attribute and returns the value associated with it. If there is more than one occurrence of the attribute, multiple text values are returned.

Parameters:

attributeName - Attribute to search for.

Returns:

Array of strings associated with all occurrences of the given attribute. Array will be 0 length if none found.

getAttributes

public java.lang.String[] getAttributes(java.lang.String attributeName,
                                        org.w3c.dom.Node node)

Searches the given node and its children for a given attribute and returns the value associated with it. If there is more than one occurrence of the attribute, multiple text values are returned.

Parameters:

attributeName - Attribute to search for.

node - Node from which to start search.

Returns:

Array of strings associated with all occurrences of the given attribute. Array will be 0 length if none found.

getNodeAttribute

public static java.lang.String getNodeAttribute(java.lang.String attributeName,
                                                org.w3c.dom.Node node)

Searches the given node for a given attribute and returns the value associated with it. This version does not recurse to children of the given node.

Parameters:

attributeName - Attribute to search for.

node - Node from which to start search.

Returns:

Value associated with the attribute, or null if not found.

getElements

public org.w3c.dom.Node[] getElements(java.lang.String name)

Returns a list of the DOM elements with the given name. This can be used to provide the base of sub-trees for searches within nested elements.

Parameters:

name - Element name to search for.

Returns:

Array of elements with the given name. Array will be 0 length if none found.

getElements

public org.w3c.dom.Node[] getElements(java.lang.String name,
                                      org.w3c.dom.Node node)

Returns a list of the DOM elements with the given name that are nested within the given node. This can be used to provide the base of sub-trees for searches within nested elements. The order of matched elements is depth-first. For breadth-first searches, use getNodeElements and recursively search for children of returned nodes.

Parameters:

name - Element name to search for.

node - Node from which to start search.

Returns:

Array of elements with the given name. Array will be 0 length if none found.

getNodeElement

public static org.w3c.dom.Node getNodeElement(java.lang.String name,
                                              org.w3c.dom.Node node)

Returns a DOM element with the given name that is the child of the given node. This is a non-recursive method that only looks for immediate children. Note that unlike getNodeElements() this method only returns the first matched child of the given node.

Parameters:

name - Element name to search for.

node - Node from which to examine children.

Returns:

Child node or null if none found.

getNodeElements

public static org.w3c.dom.Node[] getNodeElements(java.lang.String name,
                                                 org.w3c.dom.Node node)

Returns the DOM elements with the given name that are the children of the given node. This is a non-recursive method that only looks for immediate children. Array will be 0 length if none found.

Parameters:

name - Element name to search for.

node - Node from which to examine children.

Returns:

Child nodes or empty Node array if none found.

readXML

public boolean readXML(java.lang.String fileName)

Reads the given XML file and converts it into a DOM.

Parameters:

fileName - Name of XML file to convert.

Returns:

True if converted successfully.

readXML

public boolean readXML(java.io.InputStream inStream)

Reads the XML from the given input stream and converts it into a DOM.

Parameters:

inStream - Input stream containing XML to convert.

Returns:

True if converted successfully.

writeXML

public boolean writeXML()

Displays the DOM stored within this class as an XML file with default document settings on standard output.

Returns:

Always true.

writeXML

public boolean writeXML(java.lang.String version,
                        java.lang.String encoding,
                        java.lang.Boolean standalone)

Displays the DOM stored within this class as an XML file with the given document settings on standard output.

Parameters:

version - XML version, or null if default ('1.0') is to be used.

encoding - XML encoding, or null if encoding is not to be specified.

standalone - XML stand-alone status of XML file or null if not to be specified.

Returns:

Always true.

writeXML

public boolean writeXML(java.lang.String fileName)

Converts the DOM stored within this class into an XML file with default document settings.

Parameters:

fileName - Name of file to contain the XML.

Returns:

true if successful XML generation.

writeXML

public boolean writeXML(java.io.OutputStream outStream)

Converts the DOM stored within this class into an XML file with default document settings.

Parameters:

outStream - Output stream representing file to contain the XML.

Returns:

true if successful XML generation.

writeXML

public boolean writeXML(java.lang.String fileName,
                        java.lang.String version,
                        java.lang.String encoding,
                        java.lang.Boolean standalone)

Converts the DOM stored within this class into an XML file with the given document settings.

Parameters:

fileName - Name of file to contain the XML.

version - XML version, or null if default ('1.0') is to be used.

encoding - XML encoding, or null if encoding is not to be specified.

standalone - XML stand-alone status of XML file or null if not to be specified.

Returns:

true if successful XML generation.

writeXML

public boolean writeXML(java.io.OutputStream outStream,
                        java.lang.String version,
                        java.lang.String encoding,
                        java.lang.Boolean standalone)

Converts the DOM stored within this class into an XML file with the given document settings.

Parameters:

outStream - Output stream representing file to contain the XML.

version - XML version, or null if default ('1.0') is to be used.

encoding - XML encoding, or null if encoding is not to be specified.

standalone - XML stand-alone status of XML file or null if not to be specified.

Returns:

true if successful XML generation.