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.1, 1st September, 2003.

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(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[]	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(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.

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.

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.

node - Node from which to start search.

Returns:

Array of strings assoiated with all occurrences of the given element.

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.

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.

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.

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.

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.

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.