jwo.utils.xml
Class DOMProcessor

java.lang.Object
  jwo.utils.xml.DOMProcessor

public class DOMProcessor

extends 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 SAXProcessor instead.

Version:

2.2, 10th December, 2004.

Author:

Jo Wood.

Constructor Summary

DOMProcessor()
Creates a new empty DOM ready for processing.

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

DOMProcessor(InputStream inStream)
Reads XML from the given input stream and constructs a DOM from it.

DOMProcessor(String fileName)
Reads and the given XML file and constructs a DOM from it.

Method Summary

void	addAttribute(String name, String value, Node node) Adds the given attribute to the given node.
void	addComment(String comment) Adds the given comment to the root of the DOM.
void	addComment(String comment, Node node) Adds the given comment to the given node.
Node	addElement(String name) Adds a new element to the root of the DOM.
Node	addElement(String name, Node existingElement) Adds a new element to the given one within the DOM.
Node	addElement(String name, String text, Node existingElement) Adds a new element to the given one within the DOM.
String[]	getAttributes(String attributeName) Searches the entire DOM for a given attribute and returns the value associated with it.
String[]	getAttributes(String attributeName, Node node) Searches the given node and its children for a given attribute and returns the value associated with it.
Node[]	getElements(String name) Returns a list of the DOM elements with the given name.
Node[]	getElements(String name, Node node) Returns a list of the DOM elements with the given name that are nested within the given node.
String	getNodeAttribute(String attributeName, Node node) Searches the given node for a given attribute and returns the value associated with it.
Node	getNodeElement(String name, Node node) Returns a DOM element with the given name that is the child of the given node.
String	getNodeText(Node node) Searches for a given node and returns text associated with it.
String[]	getText(Node node) Returns any text associated found in the given node or its children.
String[]	getText(String elementName) Searches the entire DOM for a given element and returns text associated with it.
String[]	getText(String elementName, Node node) Searches for a given element and returns text associated with it.
boolean	isEmpty() Reports whether we have an empty DOM.
boolean	readXML(InputStream inStream) Reads the XML from the given input stream and converts it into a DOM.
boolean	readXML(String fileName) Reads the given XML file and converts it into a DOM.
boolean	writeXML() Displays the DOM stored within this class as an XML file on standard output.
boolean	writeXML(String fileName) Converts the DOM stored within this class into an XML file.

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(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(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(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 Node addElement(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 Node addElement(String name,
                       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 Node addElement(String name,
                       String text,
                       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.

addAttribute

public void addAttribute(String name,
                         String value,
                         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(String comment)

Adds the given comment to the root of the DOM.

Parameters:

comment - Comment text.

addComment

public void addComment(String comment,
                       Node node)

Adds the given comment to the given node.

Parameters:

comment - Comment text.

node - Element to attach comment.

getText

public String[] getText(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 assoiated with all occurrences of the given element. Array will be 0 length if none found.

getText

public String[] getText(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 assoiated with all occurrences of text in the node or its children. Array will be 0 length if none found.

getText

public String[] getText(String elementName,
                        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 assoiated with all occurrences of the given element. Array will be 0 length if none found.

getNodeText

public String getNodeText(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 String[] getAttributes(String attributeName)

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

Parameters:

attributeName - Attribute to search for.

Returns:

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

getAttributes

public String[] getAttributes(String attributeName,
                              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 occurance 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 assoiated with all occurrences of the given attribute. Array will be 0 length if none found.

getNodeAttribute

public String getNodeAttribute(String attributeName,
                               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 Node[] getElements(String name)

Returns a list of the DOM elements with the given name. This can be used to provde 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 Node[] getElements(String name,
                          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 provde the base of sub-trees for searches within nested elements.

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 Node getNodeElement(String name,
                           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.

Parameters:

name - Element name to search for.

node - Node from which to examine children.

Returns:

Child node or null if none found.

readXML

public boolean readXML(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(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 on standard output.

Returns:

Always true.

writeXML

public boolean writeXML(String fileName)

Converts the DOM stored within this class into an XML file.

Parameters:

fileName - Name of file to contain the XML.

Returns:

true if successful XML generation.