jcs.xml
Class DomTree

java.lang.Object
  |
  +--jcs.xml.DomTree

public class DomTree
extends java.lang.Object

A uninstantiable class with miscellaneous utility methods to access a DOM tree from parsed XML.


Method Summary
static org.w3c.dom.Element appendChild(org.w3c.dom.Document doc, org.w3c.dom.Node parent, java.lang.String childName)
          Append a node with a given name as a child of a given parent node.
static org.w3c.dom.Element appendChild(org.w3c.dom.Document doc, org.w3c.dom.Node parent, java.lang.String childName, java.lang.String childText, boolean cData)
          Append a node with a given name and text as a child of a given parent node.
static org.w3c.dom.Document checker(org.w3c.dom.Document doc, java.lang.String rootName)
          Checks that the name of the root node of an XML document is a given name.
static java.lang.String doc2String(org.w3c.dom.Document doc)
          Return a String XML document from a Document.
static org.w3c.dom.Node findNode(org.w3c.dom.Node node, java.lang.String nodeName)
          A convenience shorthand for findNode(N, NN, 0)
static org.w3c.dom.Node findNode(org.w3c.dom.Node node, java.lang.String nodeName, int nodeNumber)
          Returns a subnode of a given XML node, given the sub-node name.
static java.lang.String getAttribute(org.w3c.dom.Node node, java.lang.String attributeName)
          Returns the value of an attribute for a given XML node and attributeName.
static java.lang.String getText(org.w3c.dom.Node node)
          Returns the text of a given XML node.
static org.w3c.dom.Node getTextNode(org.w3c.dom.Node node)
          Returns the child node containing text, for a given XML node.
static org.w3c.dom.Document newDocument(boolean validate)
          Return a new empty Document object.
static int nextGivenChild(org.w3c.dom.NodeList nl, int from, java.lang.String given)
          Returns the index (if any) of the next Node in Nodelist nl at or after the from index, whose node name is in the given string.
static int nextNonWhiteSpace(org.w3c.dom.NodeList nl, int from)
          Returns the index (if any) of the next Node in Nodelist nl, at or after the from index, that is not whitespace.
static void setAttribute(org.w3c.dom.Element node, java.lang.String attributeName, java.lang.String attributeValue)
          Sets the value of an attribute for a given XML node and attributeName.
static org.w3c.dom.Node setText(org.w3c.dom.Document doc, org.w3c.dom.Node targetNode, java.lang.String newValue)
          Sets the text of a given XML node.
static org.w3c.dom.Node topNode(org.w3c.dom.Document doc, java.lang.String rootName)
          Checks that the root node of an XML document has a given name, and returns that root node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAttribute

public static java.lang.String getAttribute(org.w3c.dom.Node node,
                                            java.lang.String attributeName)
Returns the value of an attribute for a given XML node and attributeName. For example, if the node is positioned on <column null=true>, a call of getAttribute(node, "null") returns the string "true".
Parameters:
node - a Node that is positioned on a node of a DOM tree
attributename - a string that is the name of an attribute of the node
Returns:
a String that is the value of the given attribute of the node, or null

setAttribute

public static void setAttribute(org.w3c.dom.Element node,
                                java.lang.String attributeName,
                                java.lang.String attributeValue)
Sets the value of an attribute for a given XML node and attributeName. For example, if the node is positioned on <column null=true>, a call of setAttribute(node, "null" "false") sets the the "null" attribute to "true" (or inserts a new "null" attribute).
Parameters:
node - a Node that is positioned on a node of a DOM tree
attributename - a string that is the name of an attribute of the node
attributeValue - a string that is the value of the attribute

findNode

public static org.w3c.dom.Node findNode(org.w3c.dom.Node node,
                                        java.lang.String nodeName,
                                        int nodeNumber)
Returns a subnode of a given XML node, given the sub-node name.

For example

Parameters:
node - a Node that is positioned on a node of a DOM tree
nodeName - a string that is the name of a child of the node
nodeNumber - a string that is the number of a child of the node
Returns:
the given node, or null

findNode

public static org.w3c.dom.Node findNode(org.w3c.dom.Node node,
                                        java.lang.String nodeName)
A convenience shorthand for findNode(N, NN, 0)
Parameters:
node - a Node that is positioned on a node of a DOM tree
nodeName - a string that is the name of a child of the node
nodeNumber - a string that is the number of a child of the node
Returns:
the given node, or null

getText

public static java.lang.String getText(org.w3c.dom.Node node)
Returns the text of a given XML node. For example, if "node" is positioned on <Column>123</column>, then getText(node) returns "123".
Parameters:
node - a Node that is positioned on a node of a DOM tree
Returns:
a string that is the text of the given node, or null

setText

public static org.w3c.dom.Node setText(org.w3c.dom.Document doc,
                                       org.w3c.dom.Node targetNode,
                                       java.lang.String newValue)
Sets the text of a given XML node. If the given node is null or doesn't exist, then no action and returns null. For example, if node is positioned on <Column>123</column>, and doc is the Document containing node, then setText(doc, node, "987") sets the value to 987 and returns the updated node.
Parameters:
node - a Node that is positioned on a node of a DOM tree
Returns:
the updated node, or null if no update was performed.

getTextNode

public static org.w3c.dom.Node getTextNode(org.w3c.dom.Node node)
Returns the child node containing text, for a given XML node. For example if "node" is positioned on <Column>123</column>, then getText(node) will return the node with "123". Use this method when you want to update the text node.
Parameters:
node - a Node that is positioned on a node of a DOM tree
Returns:
the #text or #cdatasection node that is a child of the node

nextGivenChild

public static int nextGivenChild(org.w3c.dom.NodeList nl,
                                 int from,
                                 java.lang.String given)
Returns the index (if any) of the next Node in Nodelist nl at or after the from index, whose node name is in the given string. Otherwise, returns -1. This is mainly handy for skipping over #text nodes with whitespace.
Parameters:
nl - a NodeList that is the child nodes of a DOM tree node
from - an int that is the index of the first child node in the NodeList to consider. For example, if you use this method to step through the child nodes, then the from value will be one more than the index of the last child node that you processed.
given - a string that is the name of the child node that is sought
Returns:
an int that is the index of the node with the given name in the NodeList, or is -1 if there are no (more) such nodes

nextNonWhiteSpace

public static int nextNonWhiteSpace(org.w3c.dom.NodeList nl,
                                    int from)
Returns the index (if any) of the next Node in Nodelist nl, at or after the from index, that is not whitespace. This is mainly handy for skipping over #text nodes with whitespace.
Parameters:
nl - a NodeList that is the child nodes of a DOM tree node
from - an int that is the index of the first child node in the NodeList to consider. For example, if you use this method to step through the child nodes, then the from value will be one more than the index of the last child node that you processed.

checker

public static org.w3c.dom.Document checker(org.w3c.dom.Document doc,
                                           java.lang.String rootName)
                                    throws java.lang.Exception
Checks that the name of the root node of an XML document is a given name.
Parameters:
Document - a parsed XML document
rootName - a string that is the expected name of the root node of the document
Returns:
an Document that is the parsed object
Throws:
java.lang.Exception - Any exceptions arising in the XML parse, or a root name that is not rootName

topNode

public static org.w3c.dom.Node topNode(org.w3c.dom.Document doc,
                                       java.lang.String rootName)
                                throws java.lang.Exception
Checks that the root node of an XML document has a given name, and returns that root node. This method is convenient when you only want to read the parsed document, i.e. you don't want to modify it.
Parameters:
doc - a parsed XML document
rootName - a string that is the expected name of the root node of the document
Returns:
an Document that is the parsed object.
Throws:
java.lang.Exception - Any exceptions arising in the XML parse, or a root name that is not rootName

appendChild

public static org.w3c.dom.Element appendChild(org.w3c.dom.Document doc,
                                              org.w3c.dom.Node parent,
                                              java.lang.String childName)
Append a node with a given name as a child of a given parent node. For example, if doc contains a node<ResultSetData> node, then the call appendChild(doc, node, "Row") will append a new <Row> node and return it.
Parameters:
doc - a parsed XML document
parent - a node of doc that will be the parent of the new node
childName - a string that will be the name of the new child node
Returns:
the new child node

appendChild

public static org.w3c.dom.Element appendChild(org.w3c.dom.Document doc,
                                              org.w3c.dom.Node parent,
                                              java.lang.String childName,
                                              java.lang.String childText,
                                              boolean cData)
Append a node with a given name and text as a child of a given parent node. For example, if doc contains a node<Row> node, then the call appendChild(doc, node, "Column", "Apples", false) will append a new <Column>Apples</Column> node and return it.
Parameters:
doc - a parsed XML document
parent - a node of doc that will be the parent of the new node
childName - a string that will be the name of the new child node
childText - the text of the new child node
cData - a boolean true iff the text should be a CDATA section
Returns:
the new child node

newDocument

public static org.w3c.dom.Document newDocument(boolean validate)
                                        throws java.lang.Exception
Return a new empty Document object.
Parameters:
validate - a boolean indication of whether (true) or not (false) the new Document should validate.
Returns:
the new Document object.

doc2String

public static java.lang.String doc2String(org.w3c.dom.Document doc)
                                   throws java.lang.Exception
Return a String XML document from a Document.
Parameters:
doc - a Document
Returns:
a String containing the text of the doc.