com.toolsverse.util

Class XmlUtils

Object

com.toolsverse.util.XmlUtils

public final class XmlUtils
extends Object

XmlUtil - A wrapper to simplify basic XML functions. The goal is to provide an easy and clear set of routines for building, accessing, and moifying XML trees from a variety of sources (file, stream, etc). Sun's XML implimentation is very complex and provides a large set of features that are not really necessary in many applications. XmlUtil helps to narrow it down into a subset of basic, intuitive methods, hence stream- lining application development involving XML.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XmlUtils.NodeType The DOM NodeType.

Field Summary

Fields

Modifier and Type	Field and Description
protected org.w3c.dom.Document	masterXmlDoc The master xml doc.

Constructor Summary

Constructors

Constructor and Description
XmlUtils(File fileObject) Constructs an XmlUtil object from an XML file object.
XmlUtils(File fileObject, org.xml.sax.EntityResolver er) Constructs an XmlUtil object from an XML file object.
XmlUtils(File fileObject, org.xml.sax.EntityResolver er, boolean withLineNumbers) Constructs an XmlUtil object from an XML file object.
XmlUtils(InputStream inStream) Constructs an XmlUtil object to provide easy wrapping for XML operations.
XmlUtils(InputStream inStream, boolean withLineNumbers) Constructs an XmlUtil object to provide easy wrapping for XML operations.
XmlUtils(org.w3c.dom.Node node) Constructs an XmlUtil object from an Node object.
XmlUtils(String strtoParse) Instantiates a new xml utils.
XmlUtils(String strtoParse, boolean withLineNumbers) Instantiates a new xml utils.
XmlUtils(String rootName, String rootValue) Creates an empty tree with a root node of the specified name and value (a null can be substituted for value if none is desired - this is often preferrable).

Method Summary

Modifier and Type	Method and Description
org.w3c.dom.Attr	addAttribute(org.w3c.dom.Node node, String attributeName, String attributeValue) Adds an attribute to a specified Node.
org.w3c.dom.Node	addCDataFieldUnder(org.w3c.dom.Node parentNode, String fieldName, String fieldValue) Adds a new Node beneath a specified parent Node.
org.w3c.dom.Node	addFieldUnder(org.w3c.dom.Node parentNode, String fieldName) Adds a new Node beneath a specified parent Node, but does NOT assign it a value (the value is set to null).
org.w3c.dom.Node	addFieldUnder(org.w3c.dom.Node parentNode, String fieldName, String fieldValue) Adds a new Node beneath a specified parent Node.
org.w3c.dom.Node	addRootField(String fieldName) Adds a new Node directly beneath the XML tree's root.
org.w3c.dom.Node	addRootField(String fieldName, String fieldValue) Adds a new Node directly beneath the XML tree's root.
void	changeFieldValue(org.w3c.dom.Node aNode, String newValue) Allows updates to the first child node of a field (called "#text" that is the actual location of a field's value).
void	changeFieldValue(String nodeName, String newValue) Allows updates to the first child node of a field (called "#text" that is the actual location of a field's value).
org.w3c.dom.Comment	createComment(String comment) Creates the xml comment.
void	deleteNode(org.w3c.dom.Node aNode) Deletes passed in Node and all of that Node's children.
int	deleteNodesIn(List<org.w3c.dom.Node> manyNodes) Deletes all the Nodes contained in a Node Vector.
int	deleteNodesNamed(String nodeName) Deletes all the Nodes in an XML tree named nodeName.
void	dumpTo(OutputStream outStream, String encoding) Dumps the contents of the XML tree in raw form to the passed in OutputStream.
void	dumpTo(OutputStream outStream, String encoding, org.w3c.dom.Node rootNode) Dumps the contents of the XML tree in raw form to the passed in OutputStream.
org.w3c.dom.Node	getAttribute(org.w3c.dom.Node node, String attrName) Gets the attribute.
Map<String,String>	getAttributes(org.w3c.dom.Node node) Gets the attributes.
Map<String,String>	getAttributes(org.w3c.dom.Node parent, String name) Gets the attributes.
Boolean	getBooleanAttribute(org.w3c.dom.Node node, String attrName) Gets the boolean attribute.
Boolean	getBooleanAttribute(org.w3c.dom.Node node, String attrName, boolean def) Gets the boolean attribute.
List<org.w3c.dom.Node>	getChildNodes(org.w3c.dom.Node rootNode) Gets a Vector of Nodes of all the children of a particular Node.
List<String>	getChildValues(org.w3c.dom.Node rootNode) Gets a Vector of Strings of all the values contained by the children of a particular Node.
org.w3c.dom.Document	getDoc() Gets the doc.
org.w3c.dom.Node	getFirstNodeContaining(String searchString) Searches the XML tree for a field that contains searchString and returns the address of that Node.
org.w3c.dom.Node	getFirstNodeNamed(org.w3c.dom.Node rootNode, String nodeName) Searches ONLY THE FIRST LEVEL CHILDREN of specified rootNode and returns the first instance of a Node named nodeName.
org.w3c.dom.Node	getFirstNodeNamed(String searchString) Searches the entire XML tree for a Node of specified String searchString and returns the address of that Node.
List<org.w3c.dom.Node>	getNodesContaining(String searchString) Searches the XML tree for Nodes contaning String searchString and returns the addresses of those Nodes in a Vector.
List<org.w3c.dom.Node>	getNodesNamed(String searchString) Searches the XML tree for Nodes named String searchString and returns their addresses in a vector.
static XmlUtils.NodeType	getNodeType(org.w3c.dom.Node node, boolean checkAttrs, boolean supportsMulti) Gets the node type.
static XmlUtils.NodeType	getNodeType(org.w3c.dom.Node node, boolean checkAttrs, boolean supportsMulti, boolean ignoreAttrsInValueAttrNode, boolean ignoreValuesInValueAttrNode) Gets the node type.
String	getNodeValue(org.w3c.dom.Node rootNode, String name) Gets the node value.
Number	getNumberAttribute(org.w3c.dom.Node node, String attrName) Gets the number attribute.
Number	getNumberAttribute(org.w3c.dom.Node node, String attrName, Number defaultValue) Gets the number attribute.
org.w3c.dom.Node	getRootNode() Returns a live instance of the tree's root node that children can be accessed, modified, added, and deleted from.
String	getStringAttribute(org.w3c.dom.Node node, String attrName) Gets the string attribute.
String	getValueOf(org.w3c.dom.Node aNode) Looks at the first child node of aNode for the value of the field.
String	getValueOf(String nodeName) Searches the XML tree for a node called NodeName and then returns a String of it's value (the first child of the Node).
static String	getValueOfNode(org.w3c.dom.Node aNode) Looks at the first child node of aNode for the value of the field.
boolean	hasChildNodes(org.w3c.dom.Node node) Returns whether this node has any children.
static boolean	hasChildren(org.w3c.dom.Node node, boolean checkAttrs) Checks if node has any real children of any sort.
static boolean	hasChildren(org.w3c.dom.Node node, boolean checkAttrs, boolean ignoreAttrsInValueAttrNode, boolean ignoreValuesInValueAttrNode) Checks if node has any real children of any sort.
static String	removeXmlHeader(String xml) Removes the xml header.
void	setDoc(org.w3c.dom.Document d) Sets the doc.
void	writeToFile(File fileObject, String encoding) Dumps the contents of the XML tree into an XML formatted file as specified by the File fileObject.
void	writeToFile(String fileName, String encoding) Dumps the contents of the XML tree into an XML formatted file specified in the path String fileNameString.
String	xmlToString(String encoding) Dumps the contents of the XML tree in raw form to the String.
String	xmlToString(String encoding, org.w3c.dom.Node rootNode) Dumps the contents of the XML tree in raw form to the String.

Methods inherited from class Object

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

Field Detail

masterXmlDoc

protected org.w3c.dom.Document masterXmlDoc

The master xml doc.

Constructor Detail

XmlUtils

public XmlUtils(File fileObject)
         throws Exception

Constructs an XmlUtil object from an XML file object.

Parameters:

fileObject - An object of a valid XMl file. The file object's path will be made absolute to ensure sanity.

Throws:

Exception - the exception

XmlUtils

public XmlUtils(File fileObject,
                org.xml.sax.EntityResolver er)
         throws Exception

Constructs an XmlUtil object from an XML file object.

Parameters:

fileObject - An object of a valid XMl file. The file object's path will be made absolute to ensure sanity.

er - the entity resolver

Throws:

Exception - the exception

XmlUtils

public XmlUtils(File fileObject,
                org.xml.sax.EntityResolver er,
                boolean withLineNumbers)
         throws Exception

Constructs an XmlUtil object from an XML file object.

Parameters:

fileObject - An object of a valid XMl file. The file object's path will be made absolute to ensure sanity.

er - the entity resolver

withLineNumbers - if true add location information

Throws:

Exception - the exception

XmlUtils

public XmlUtils(InputStream inStream)
         throws Exception

Constructs an XmlUtil object to provide easy wrapping for XML operations. Creates a tree from XML structured data in stream form.

Parameters:

inStream - A data stream that is parsed by the docBuilder for better performance over file objects. Requested by Michael "Wang" Mandel.

Throws:

Exception - the exception

XmlUtils

public XmlUtils(InputStream inStream,
                boolean withLineNumbers)
         throws Exception

Constructs an XmlUtil object to provide easy wrapping for XML operations. Creates a tree from XML structured data in stream form.

Parameters:

inStream - A data stream that is parsed by the docBuilder for better performance over file objects.

withLineNumbers - if true add location information

Throws:

Exception - the exception

XmlUtils

public XmlUtils(org.w3c.dom.Node node)
         throws Exception

Constructs an XmlUtil object from an Node object.

Parameters:

node - the node

Throws:

Exception - the exception

XmlUtils

public XmlUtils(String strtoParse)
         throws Exception

Instantiates a new xml utils.

Parameters:

strtoParse - the strto parse

Throws:

Exception - the exception

XmlUtils

public XmlUtils(String strtoParse,
                boolean withLineNumbers)
         throws Exception

Instantiates a new xml utils.

Parameters:

strtoParse - the string to parse

withLineNumbers - if true add location information

Throws:

Exception - the exception

XmlUtils

public XmlUtils(String rootName,
                String rootValue)
         throws Exception

Creates an empty tree with a root node of the specified name and value (a null can be substituted for value if none is desired - this is often preferrable).

Parameters:

rootName - The name you want to give to the tree's root node.

rootValue - A value, if any, that you want the #text field of the root node to contain. May be null.

Throws:

Exception - the exception

Method Detail

getNodeType

public static XmlUtils.NodeType getNodeType(org.w3c.dom.Node node,
                                            boolean checkAttrs,
                                            boolean supportsMulti,
                                            boolean ignoreAttrsInValueAttrNode,
                                            boolean ignoreValuesInValueAttrNode)

Gets the node type.

Parameters:

node - the node

checkAttrs - if true check attributes as well

supportsMulti - if true parser supports multi data sets

ignoreAttrsInValueAttrNode - the ignore attrs in value attr node

ignoreValuesInValueAttrNode - the ignore values in value attr node

Returns:

the node type

getNodeType

public static XmlUtils.NodeType getNodeType(org.w3c.dom.Node node,
                                            boolean checkAttrs,
                                            boolean supportsMulti)

Gets the node type.

Parameters:

node - the node

checkAttrs - if true check attributes as well

supportsMulti - if true parser supports multi data sets

Returns:

the node type

hasChildren

public static boolean hasChildren(org.w3c.dom.Node node,
                                  boolean checkAttrs)

Checks if node has any real children of any sort.

Parameters:

node - the node

checkAttrs - if true check attributes

Returns:

true, if successful

hasChildren

public static boolean hasChildren(org.w3c.dom.Node node,
                                  boolean checkAttrs,
                                  boolean ignoreAttrsInValueAttrNode,
                                  boolean ignoreValuesInValueAttrNode)

Checks if node has any real children of any sort.

Parameters:

node - the node

checkAttrs - if true check attributes

ignoreAttrsInValueAttrNode - the ignore attrs in value attr node

ignoreValuesInValueAttrNode - the ignore values in value attr node

Returns:

true, if successful

addAttribute

public org.w3c.dom.Attr addAttribute(org.w3c.dom.Node node,
                                     String attributeName,
                                     String attributeValue)

Adds an attribute to a specified Node.

Parameters:

node - A pre-existing Node on the XML tree under which the new Node should be placed as a child. The node must implement the Element interface, or a ClassCastException will occur.

attributeName - The name of the attribute to be created.

attributeValue - The value of the attribute to be created.

Returns:

The memory address of the newly created attribute.

addCDataFieldUnder

public org.w3c.dom.Node addCDataFieldUnder(org.w3c.dom.Node parentNode,
                                           String fieldName,
                                           String fieldValue)

Adds a new Node beneath a specified parent Node.

Parameters:

parentNode - A pre-existing Node on the XML tree under which the new Node should be placed as a child. Not tested for specification of a Node not already on the tree.

fieldName - The name of the field to be created.

fieldValue - What should be placed in the #text child of the new field.

Returns:

The memory address of the newly created Node.

addFieldUnder

public org.w3c.dom.Node addFieldUnder(org.w3c.dom.Node parentNode,
                                      String fieldName)

Adds a new Node beneath a specified parent Node, but does NOT assign it a value (the value is set to null).

Parameters:

parentNode - A pre-existing Node on the XML tree under which the new Node should be placed as a child. Not tested for specification of a Node not already on the tree.

fieldName - The name of the field to be created.

Returns:

The memory address of the newly created Node.

addFieldUnder

public org.w3c.dom.Node addFieldUnder(org.w3c.dom.Node parentNode,
                                      String fieldName,
                                      String fieldValue)

Adds a new Node beneath a specified parent Node.

Parameters:

parentNode - A pre-existing Node on the XML tree under which the new Node should be placed as a child. Not tested for specification of a Node not already on the tree.

fieldName - The name of the field to be created.

fieldValue - What should be placed in the #text child of the new field.

Returns:

The memory address of the newly created Node.

addRootField

public org.w3c.dom.Node addRootField(String fieldName)

Adds a new Node directly beneath the XML tree's root. This eliminates the need to pass the actual root node into either of the addFieldUnder methods.

Parameters:

fieldName - The name of the field to be created.

Returns:

the node

addRootField

public org.w3c.dom.Node addRootField(String fieldName,
                                     String fieldValue)

Adds a new Node directly beneath the XML tree's root. This eliminates the need to pass the actual root node into either of the addFieldUnder methods.

Parameters:

fieldName - The name of the field to be created.

fieldValue - What should be placed in the #text child of the new field.

Returns:

the node

changeFieldValue

public void changeFieldValue(org.w3c.dom.Node aNode,
                             String newValue)

Allows updates to the first child node of a field (called "#text" that is the actual location of a field's value). Streamlines this process.

Parameters:

aNode - The actual Node object that you want to update.

newValue - A String to replace the current #text field with.

changeFieldValue

public void changeFieldValue(String nodeName,
                             String newValue)

Allows updates to the first child node of a field (called "#text" that is the actual location of a field's value). Streamlines this process.

Parameters:

nodeName - A String for the name of a node. Searches the XML tree for the first Node of this name.

newValue - A String to replace the current #text field with.

createComment

public org.w3c.dom.Comment createComment(String comment)

Creates the xml comment.

Parameters:

comment - the comment

Returns:

the comment

deleteNode

public void deleteNode(org.w3c.dom.Node aNode)

Deletes passed in Node and all of that Node's children.

Parameters:

aNode - The Node to remove.

deleteNodesIn

public int deleteNodesIn(List<org.w3c.dom.Node> manyNodes)

Deletes all the Nodes contained in a Node Vector.

Parameters:

manyNodes - A Vector of Nodes to remove.

Returns:

Returns the number of Nodes deleted.

deleteNodesNamed

public int deleteNodesNamed(String nodeName)

Deletes all the Nodes in an XML tree named nodeName.

Parameters:

nodeName - Search name of Nodes to be deleted.

Returns:

Reutnrs the number of Nodes deleted.

dumpTo

public void dumpTo(OutputStream outStream,
                   String encoding,
                   org.w3c.dom.Node rootNode)
            throws Exception

Dumps the contents of the XML tree in raw form to the passed in OutputStream.

Parameters:

outStream - Stream object to write XmlTree to.

encoding - the encoding

rootNode - the root node

Throws:

Exception - the exception

dumpTo

public void dumpTo(OutputStream outStream,
                   String encoding)
            throws Exception

Dumps the contents of the XML tree in raw form to the passed in OutputStream.

Parameters:

outStream - Stream object to write XmlTree to.

encoding - the encoding

Throws:

Exception - the exception

getAttribute

public org.w3c.dom.Node getAttribute(org.w3c.dom.Node node,
                                     String attrName)

Gets the attribute.

Parameters:

node - the node

attrName - the attr name

Returns:

the attribute

getAttributes

public Map<String,String> getAttributes(org.w3c.dom.Node node)

Gets the attributes.

Parameters:

node - the node

Returns:

the attributes

getAttributes

public Map<String,String> getAttributes(org.w3c.dom.Node parent,
                                        String name)

Gets the attributes.

Parameters:

parent - the parent

name - the name

Returns:

the attributes

getBooleanAttribute

public Boolean getBooleanAttribute(org.w3c.dom.Node node,
                                   String attrName)

Gets the boolean attribute.

Parameters:

node - the node

attrName - the attr name

Returns:

the boolean attribute

getBooleanAttribute

public Boolean getBooleanAttribute(org.w3c.dom.Node node,
                                   String attrName,
                                   boolean def)

Gets the boolean attribute.

Parameters:

node - the node

attrName - the attr name

def - the default value

Returns:

the boolean attribute

getChildNodes

public List<org.w3c.dom.Node> getChildNodes(org.w3c.dom.Node rootNode)

Gets a Vector of Nodes of all the children of a particular Node. Superior for uses with XmlUtil insofar as it returns ONLY child Nodes of rootNode, rather than Nodes *and* child #text fields.

Parameters:

rootNode - The parent Node from which we'll get the child Nodes.

Returns:

the child nodes

getChildValues

public List<String> getChildValues(org.w3c.dom.Node rootNode)

Gets a Vector of Strings of all the values contained by the children of a particular Node.

Parameters:

rootNode - The parent Node from which we'll get the values of the children.

Returns:

the child values

getDoc

public org.w3c.dom.Document getDoc()

Gets the doc.

Returns:

the doc

getFirstNodeContaining

public org.w3c.dom.Node getFirstNodeContaining(String searchString)

Searches the XML tree for a field that contains searchString and returns the address of that Node.

Parameters:

searchString - the value to search for.

Returns:

The address of the Node containing searchString. If it was not found, the method returns null.

getFirstNodeNamed

public org.w3c.dom.Node getFirstNodeNamed(org.w3c.dom.Node rootNode,
                                          String nodeName)

Searches ONLY THE FIRST LEVEL CHILDREN of specified rootNode and returns the first instance of a Node named nodeName. This routine does NOT transverse multiple levels (this is intentional). It is meant for mainly for getting data from reoccurring packetized blocks of fields.

Parameters:

rootNode - The Node whose children we'll search for a Node called nodeName.

nodeName - The name of the Node we're looking for.

Returns:

The Node we're looking for, or null if it does not exist. (Make sure that you check for null condition properly when using this. This routine is used frequently in cases where we're not sure what the child Nodes of rootNode are. The return value will have no properties if no match is found.)

getFirstNodeNamed

public org.w3c.dom.Node getFirstNodeNamed(String searchString)

Searches the entire XML tree for a Node of specified String searchString and returns the address of that Node.

Parameters:

searchString - A field to search for.

Returns:

The address of the Node named searchString. If it was not found, the method returns null.

getNodesContaining

public List<org.w3c.dom.Node> getNodesContaining(String searchString)

Searches the XML tree for Nodes contaning String searchString and returns the addresses of those Nodes in a Vector.

Parameters:

searchString - A field value to search for.

Returns:

A list of all nodes containing searchString.

getNodesNamed

public List<org.w3c.dom.Node> getNodesNamed(String searchString)

Searches the XML tree for Nodes named String searchString and returns their addresses in a vector.

Parameters:

searchString - A field name to search for.

Returns:

A list of all nodes matching the name searchString.

getNodeValue

public String getNodeValue(org.w3c.dom.Node rootNode,
                           String name)

Gets the node value.

Parameters:

rootNode - the root node

name - the name

Returns:

the node value

getNumberAttribute

public Number getNumberAttribute(org.w3c.dom.Node node,
                                 String attrName)

Gets the number attribute.

Parameters:

node - the node

attrName - the attr name

Returns:

the number attribute

getNumberAttribute

public Number getNumberAttribute(org.w3c.dom.Node node,
                                 String attrName,
                                 Number defaultValue)

Gets the number attribute.

Parameters:

node - the node

attrName - the attr name

Returns:

the number attribute

getRootNode

public org.w3c.dom.Node getRootNode()

Returns a live instance of the tree's root node that children can be accessed, modified, added, and deleted from. Useful for adding first-level tree branches.

Returns:

A live instance of the tree's root node.

getStringAttribute

public String getStringAttribute(org.w3c.dom.Node node,
                                 String attrName)

Gets the string attribute.

Parameters:

node - the node

attrName - the attr name

Returns:

the string attribute

getValueOf

public String getValueOf(org.w3c.dom.Node aNode)

Looks at the first child node of aNode for the value of the field.

Parameters:

aNode - A Node object to fetch the value from.

Returns:

The value stored in the field.

getValueOfNode

public static String getValueOfNode(org.w3c.dom.Node aNode)

Looks at the first child node of aNode for the value of the field.

Parameters:

aNode - A Node object to fetch the value from.

Returns:

The value stored in the field.

getValueOf

public String getValueOf(String nodeName)

Searches the XML tree for a node called NodeName and then returns a String of it's value (the first child of the Node). Gets the first instance of the Node.

Parameters:

nodeName - String of the node to search for.

Returns:

The value stored in the field, null if nodeName was not found.

hasChildNodes

public boolean hasChildNodes(org.w3c.dom.Node node)

Returns whether this node has any children. Ignores text nodes and comments.

Parameters:

node - the node

Returns:

Returns true if this node has any children, false otherwise.

setDoc

public void setDoc(org.w3c.dom.Document d)

Sets the doc.

Parameters:

d - the new doc

writeToFile

public void writeToFile(File fileObject,
                        String encoding)
                 throws Exception

Dumps the contents of the XML tree into an XML formatted file as specified by the File fileObject.

Parameters:

fileObject - The pre-created File object to dump the tree into.

encoding - the encoding

Throws:

Exception - the exception

writeToFile

public void writeToFile(String fileName,
                        String encoding)
                 throws Exception

Dumps the contents of the XML tree into an XML formatted file specified in the path String fileNameString.

Parameters:

fileName - The filename to dump the tree into.

encoding - the encoding

Throws:

Exception - the exception

xmlToString

public String xmlToString(String encoding)
                   throws Exception

Dumps the contents of the XML tree in raw form to the String.

Parameters:

encoding - the encoding

Returns:

the string

Throws:

Exception - the exception

xmlToString

public String xmlToString(String encoding,
                          org.w3c.dom.Node rootNode)
                   throws Exception

Dumps the contents of the XML tree in raw form to the String.

Parameters:

encoding - the encoding

rootNode - the root node

Returns:

the string

Throws:

Exception - the exception

removeXmlHeader

public static String removeXmlHeader(String xml)

Removes the xml header.

Parameters:

xml - the xml

Returns:

the xml string without header