bill.util.xml
Class SimpleXML

java.lang.Object
  |
  +--bill.util.xml.SimpleXML

public class SimpleXML

extends Object

Class in charge of creating an XML document. This is a simplistic implementation, i.e. you will find no mention if DOM or SAX. It stores it's data primarily in Vectors, not Node or Document objects. Useful for creating XML documents in a reasonably straight forward manner and it can dump the XML out in a properly formed String format.

Inner Class Summary

class

SimpleXML.SimpleXMLBuilder This class is used to assist in the creation of a SimpleXML class instance from an XML string.

Constructor Summary

SimpleXML()
Default constructor.

SimpleXML(FileReader reader)
Constructor that uses a file as it's input source.

SimpleXML(SimpleXML xml)
A copy constructor.

SimpleXML(String xml)
Constructor that takes a valid XML document as input to create our internal XML representation structure.

Method Summary

static void	addChild(SimpleXMLObject target, SimpleXMLObject child) Adds the specified node as a child to the target node.
void	addChild(String target, SimpleXMLObject child) Adds the specified node as a child to the target XPath's node.
boolean	childHasAValue(String path) Checks if any of the children of the specified node have a value.
String	getElementValue(String path) Retrieves the value of the object at the specified XPath name in the XML document.
SimpleXMLObject	getObject(String path) Retrieves the object at the specified XPath name in the XML document.
SimpleXMLObjectList	getObjectList(String path) Retrieves the object list at the specified XPath name in the XML document.
SimpleXMLObject	getRoot() Returns the object that is the root node of the XML document.
boolean	isValidXPath(String path) Checks to see if the specified XPath has been defined in the XML structure.
static void	mergeChildren(SimpleXMLObject target, SimpleXMLObject source) Adds the children of the source node to the children of the target node.
void	mergeChildren(String target, SimpleXMLObject source) Adds the children of the source node to the children of the target node.
void	removePath(String path) Removes the specified XPath from the XML document.
void	removePath(String path, boolean allInstances) Removes the specified XPath from the XML document.
String	toXML() Dumps out the object in valid XML string representation.
SimpleXMLObject	updatePath(String path, String value) Updates (or adds if necessary) the specified path name in the XML document to assign it the indicated value.

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleXML

public SimpleXML()

Default constructor.

SimpleXML

public SimpleXML(String xml)

Constructor that takes a valid XML document as input to create our internal XML representation structure.

Parameters:

xml - The valid XML document to use.

SimpleXML

public SimpleXML(SimpleXML xml)

A copy constructor. Creates a new instance that is a deep copy of the specified instance.

Parameters:

xml - The instance to make a copy of.

SimpleXML

public SimpleXML(FileReader reader)

Constructor that uses a file as it's input source.

Parameters:

reader - Handle to the input file.

Method Detail

addChild

public static void addChild(SimpleXMLObject target,
                            SimpleXMLObject child)

Adds the specified node as a child to the target node. This always adds a new object structure, it does not update any existing objects by the same name. Note that this method does not make a 'deep' copy of the nodes being added, so changes to them after this merge will be reflected in the original node and the 'copied' node.

Parameters:

target - The node to add the child node to.

child - The node to be added as a child.

addChild

public void addChild(String target,
                     SimpleXMLObject child)

Adds the specified node as a child to the target XPath's node. This always adds a new object structure, it does not update any existing objects by the same name. Note that this method does not make a 'deep' copy of the nodes being added, so changes to them after this merge will be reflected in the original node and the 'copied' node. If the target XPath does not exist, it is created.

Parameters:

target - The XPath of the node to add the child node to.

child - The node to be added as a child.

mergeChildren

public static void mergeChildren(SimpleXMLObject target,
                                 SimpleXMLObject source)

Adds the children of the source node to the children of the target node. This always adds new objects to the XML, it does not update existing objects with the same name. Note that this method does not make a 'deep' copy of the nodes being added, so changes to them after this merge will be reflected in the original node and the 'copied' node.

Parameters:

target - The node to add the child nodes to.

source - The node to take the children out of.

mergeChildren

public void mergeChildren(String target,
                          SimpleXMLObject source)

Adds the children of the source node to the children of the target node. This always adds new objects to the XML, it does not update existing objects with the same name. Note that this method does not make a 'deep' copy of the nodes being added, so changes to them after this merge will be reflected in the original node and the 'copied' node. If the target XPath does not exist, it is created.

Parameters:

target - The XPath of the node to add the child nodes to.

source - The node to take the children out of.

removePath

public void removePath(String path)

Removes the specified XPath from the XML document. All the children of the XPath are removed as well.

Parameters:

path - The XPath to remove from the XML document.

removePath

public void removePath(String path,
                       boolean allInstances)

Removes the specified XPath from the XML document. All the children of the XPath are removed as well.

Parameters:

path - The XPath to remove from the XML document.

allInstances - Indicates if all instances of the leaf node of the XPath should be removed in cases where there are multiple occurrences of them and a specific instance is not specified.

updatePath

public SimpleXMLObject updatePath(String path,
                                  String value)

Updates (or adds if necessary) the specified path name in the XML document to assign it the indicated value. When a portion of the path does not exist, new "nodes" will be created to represent it. I.E. if a path of "/first/second/third" is passed in, and first does not yet exist, it is created, as are second and third underneath it. Note that if the update is not creating a new leaf node (i.e. the specified path already exists) and null is passed as the value, than nothing will happen.

Parameters:

path - The XPath of the node to be updated or created.

value - The value to assign to the node.

Returns:

Returns a reference to the object that was updated (or added).

getRoot

public SimpleXMLObject getRoot()

Returns the object that is the root node of the XML document.

Returns:

The root node object.

getObjectList

public SimpleXMLObjectList getObjectList(String path)

Retrieves the object list at the specified XPath name in the XML document. The list contains the Vector of all the SimpleXMLObjects that have that XPath specified. Note that if the last element in the XPath is indexed, the index is ignored.

Parameters:

path - The XPath of the list to be retrieved.

Returns:

The object list at the specified XPath, or null if the XPath does not exist.

getObject

public SimpleXMLObject getObject(String path)

Retrieves the object at the specified XPath name in the XML document.

Parameters:

path - The XPath of the node to be retrieved.

Returns:

The object at the specified XPath, or null if the XPath does not exist.

isValidXPath

public boolean isValidXPath(String path)

Checks to see if the specified XPath has been defined in the XML structure.

Parameters:

path - The XPath to check for.

Returns:

Returns true if the XPath has been defined in the XML structure (regardless of whether it has a value), otherwise returns false.

childHasAValue

public boolean childHasAValue(String path)

Checks if any of the children of the specified node have a value. Only checks child nodes, not grandchildren or more distant.

Parameters:

path - The XPath into the XML to check for children with values.

Returns:

Returns true if at least one child has a value, otherwise returns false.

getElementValue

public String getElementValue(String path)

Retrieves the value of the object at the specified XPath name in the XML document.

Parameters:

path - The XPath of the node to retrieve the value of.

Returns:

The value of the XPath element, or null if the XPath does not exist or has no value.

toXML

public String toXML()

Dumps out the object in valid XML string representation.

Returns:

The XML in string format.