net.wangs.xmlutil
Class XMLUtil

java.lang.Object
  net.wangs.xmlutil.XMLUtil

public class XMLUtil

extends java.lang.Object

 XMLUtil constructs from either an xml file or a node, and returns detail information of 
 node by directory style path into easy-to-use data formats, such as String, int, Hashtable 
 of String, etc. 

 Demonstration of the usage of XMLUtil:

          try {
                String path = "/AAA/BBB/CCC";

                // You can directly construct an XMLUtil object from XPath like below:
                // XMLUtil util = new XMLUtil("./config/sample.xml");
                // Vector nodes = util.getNodes(path); 

                // Or you can construct an XMLUtil object from a node (normally also from XMLUtil)
                Vector nodes = XMLUtil.getNodes(path);
                for(int i=0; i<nodes.size(); i++) {
                        Node node = (Node)nodes.elementAt(i);
                        XMLUtil xMLUtil = new XMLUtil(node);
                        String val = xMLUtil.getNodeValue("/BBB/CCC", 1);
                        Hashtable hash = xMLUtil.getChildNodeHashValues("/CCC");
                }
          } catch (Exception e) {
                e.printStackTrace();
          }
 

Author:

Yuqing Wang

Constructor Summary

XMLUtil(org.w3c.dom.Node node)
Constructor: constructing internal element from Node object.

XMLUtil(java.lang.String fileName)
Constructor: constructing internal element from XML file

Method Summary

java.util.Hashtable	getAttrValues(java.lang.String nodeName, int index) Given a node name (with path), returns all attributes of this node with name-value pairs.
java.util.Hashtable	getAttrValuesHashedByNamedAttr(java.lang.String nodeName, java.lang.String val_attrName, java.lang.String key_attrName) Given node name (with path) and two attribute's names, returns a Hashtable with key is one attribute's value and value is another attribute's value.
MultiKeyHashtable	getAttrValuesHashedByNamedAttrs(java.lang.String nodeName, java.lang.String val_attrName, java.lang.String[] key_attrName) Given node name (with path), an attribute name and an array of attribute names, returns a MultiKeyHashtable with keys from two or more attributes and value from another attribute.
java.util.Hashtable	getChildNodeHashValues(java.lang.String nodeName) Given a node name, return all child nodes' name-value pairs into a hashtable.
java.lang.String	getNamedAttrValue(java.lang.String nodeName, java.lang.String attrName, int index) Given a node name (with path) and atrribute name, returns attribute value.
org.w3c.dom.Node	getNode(java.lang.String nodeName, int index) Return node for given node name and index
org.w3c.dom.Node	getNodeByAttrValue(java.lang.String nodeName, java.lang.String attrName, java.lang.String attrValue) Return node for given node name and one given attribute values If there are multiple nodes satisfied this condition, the first one is returned.
int	getNodeCount(java.lang.String nodeName) Given a node name (with path), returns number of nodes with the same name under the same path.
java.util.Vector	getNodes(java.lang.String nodeName) Return all nodes for given node name with path.
java.util.Vector	getNodesByAttrValue(java.lang.String nodeName, java.lang.String attrName, java.lang.String attrValue) Return Vector of nodes for given node name and one given attribute values More complicated case is to give a hashtable of attribute name-value pairs, but we are not going to provide this since it's rarely used.
java.util.Hashtable	getNodesHashedByNamedAttr(java.lang.String nodeName, java.lang.String attrName) Given a node name (with path) and one attribute, returns Hashtable of all nodes with the same name in the same path.
MultiKeyHashtable	getNodesHashedByNamedAttrs(java.lang.String nodeName, java.lang.String[] attrNames) Given a node name (with path) and attributes array, returns MultiKeyHashtable of all nodes with the same name in the same path.
java.lang.String	getNodeValue(java.lang.String nodeName, int index) For a known node, get its value.
java.lang.String	getNodeValueByAttrValue(java.lang.String nodeName, java.lang.String attrName, java.lang.String attrValue) Return Vector of nodes for given node name and one given attribute values A common usage of this method is: to obtain a subset of nodes from a set of sibling nodes.
java.util.Vector	getNodeValues(java.lang.String nodeName) Return all node values for given node name with path.
java.util.Hashtable	getNodeValuesAsHashtable(java.lang.String nodeName) Return all node values in a Hashtable for given node name with path.
java.util.Hashtable	getNodeValuesHashedByNamedAttr(java.lang.String nodeName, java.lang.String attrName) Given a node name (with path) and one attribute, returns Hashtable of all nodes with the same name in the same path.
MultiKeyHashtable	getNodeValuesHashedByNamedAttrs(java.lang.String nodeName, java.lang.String[] attrNames) Given a node name (with path) and attributes array, returns all node values with the same name in the same path.

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLUtil

public XMLUtil(org.w3c.dom.Node node)
        throws XMLUtilException

Constructor: constructing internal element from Node object. This Node object must be either DOCUMENT_NODE or ELEMENT_NODE type

Since:

1.0

XMLUtil

public XMLUtil(java.lang.String fileName)
        throws XMLUtilException

Constructor: constructing internal element from XML file

Since:

1.0

Method Detail

getNodes

public java.util.Vector getNodes(java.lang.String nodeName)
                          throws XMLUtilException

Return all nodes for given node name with path.

Parameters:

nodeName -

Returns:

Vector of Node

Throws:

XMLUtilException

Since:

1.0

getNodeValues

public java.util.Vector getNodeValues(java.lang.String nodeName)
                               throws XMLUtilException

Return all node values for given node name with path.

Returns:

Vector of String

Throws:

XMLUtilException

Since:

1.0

getNodeValuesAsHashtable

public java.util.Hashtable getNodeValuesAsHashtable(java.lang.String nodeName)
                                             throws XMLUtilException

Return all node values in a Hashtable for given node name with path. The values are converted in their origin type.

Returns:

Hashtable of String for keys and Object for values

Throws:

XMLUtilException

Since:

1.1

getNode

public org.w3c.dom.Node getNode(java.lang.String nodeName,
                                int index)
                         throws XMLUtilException

Return node for given node name and index

Parameters:

index - - the index number of node that satisfies the nodeName, started from 1, top-down

Throws:

XMLUtilException

Since:

1.0

getNodesByAttrValue

public java.util.Vector getNodesByAttrValue(java.lang.String nodeName,
                                            java.lang.String attrName,
                                            java.lang.String attrValue)
                                     throws XMLUtilException

Return Vector of nodes for given node name and one given attribute values More complicated case is to give a hashtable of attribute name-value pairs, but we are not going to provide this since it's rarely used.

Parameters:

nodeName - - name of the node with full path

attrName - - name of attribute in the node

attrValue - - value of the given attribute

Throws:

XMLUtilException

Since:

1.0

getNodeByAttrValue

public org.w3c.dom.Node getNodeByAttrValue(java.lang.String nodeName,
                                           java.lang.String attrName,
                                           java.lang.String attrValue)
                                    throws XMLUtilException

Return node for given node name and one given attribute values

 If there are multiple nodes satisfied this condition, the first one is returned.
 A common usage of this method is: to obtain a particular node from a set of sibling nodes.
 All nodes have the same tag name and attribute names. The only way to differentiate one
 from them is the attribute value. For example,
       <service name="ServiceAAA">
               // data belongs to ServiceAAA
       </service>
       <service name="ServiceBBB">
               // data belongs to ServiceBBB
       </service>
       <service name="ServiceCCC">
               // data belongs to ServiceCCC
       </service>
 More complicated case is to give a hashtable of attribute name-value pairs, but
 we are not going to provide this since it's rarely used.
 

Parameters:

nodeName - - name of the node with full path

attrName - - name of attribute in the node

attrValue - - value of the given attribute

Throws:

XMLUtilException

Since:

1.0

getNodeValueByAttrValue

public java.lang.String getNodeValueByAttrValue(java.lang.String nodeName,
                                                java.lang.String attrName,
                                                java.lang.String attrValue)
                                         throws XMLUtilException

Return Vector of nodes for given node name and one given attribute values

 A common usage of this method is: to obtain a subset of nodes from a set of sibling nodes.
 All nodes have the same tag name and attribute names. The only way to differentiate desired 
 ones from them is the attribute value. For example,
       <service name="ServiceAAA">
               // data belongs to ServiceAAA
       </service>
       <service name="ServiceBBB">
               // data belongs to ServiceBBB
       </service>
       <service name="ServiceCCC">
               // data belongs to ServiceCCC
       </service>
 More complicated case is to give a hashtable of attribute name-value pairs, but
 we are not going to provide this since it's rarely used.
 

Parameters:

nodeName - - name of the node with full path

attrName - - name of attribute in the node

attrValue - - value of the given attribute

Throws:

XMLUtilException

Since:

1.0

getNodeValue

public java.lang.String getNodeValue(java.lang.String nodeName,
                                     int index)
                              throws XMLUtilException

For a known node, get its value. If more than one nodes with the same name under given path, the one in the index (start from "1" Top-Down) is retrieved.

Parameters:

index - - the index number of node that satisfies the nodeName

Returns:

String - string value of node

Throws:

XMLUtilException

Since:

1.0

getNodeCount

public int getNodeCount(java.lang.String nodeName)
                 throws XMLUtilException

Given a node name (with path), returns number of nodes with the same name under the same path.

Returns:

int

Throws:

XMLUtilException

Since:

1.0

getAttrValues

public java.util.Hashtable getAttrValues(java.lang.String nodeName,
                                         int index)
                                  throws XMLUtilException

Given a node name (with path), returns all attributes of this node with name-value pairs. If more than one nodes with the same name under given path, the one in the index (start from "1" Top-Down) is retrieved.

Parameters:

index - - the index number of node that satisfies the nodeName

Returns:

String - string value of node

Throws:

XMLUtilException

Since:

1.0

getNamedAttrValue

public java.lang.String getNamedAttrValue(java.lang.String nodeName,
                                          java.lang.String attrName,
                                          int index)
                                   throws XMLUtilException

Given a node name (with path) and atrribute name, returns attribute value. If more than one nodes with the same name under given path, the one in the index (start from "1" Top-Down) is retrieved.

Parameters:

attrName - - name of the attribute in this node

index - - the index number of node that satisfies the nodeName

Returns:

String - string value of node

Throws:

XMLUtilException

Since:

1.0

getNodesHashedByNamedAttrs

public MultiKeyHashtable getNodesHashedByNamedAttrs(java.lang.String nodeName,
                                                    java.lang.String[] attrNames)
                                             throws XMLUtilException

Given a node name (with path) and attributes array, returns MultiKeyHashtable of all nodes with the same name in the same path. The Hash Key is String array of all attributes values. For example, a node

       "/AAA/BBB/CCC"
 is defined as:
       ...
       <CCC>
               <DDD attrA="a1" attrB="b1">
                       <EEE>Value1 of EEE</EEE>
                       <FFF/>
               </DDD>
               <DDD attrA="a1" attrB="b2">
                       <EEE>Value2 of EEE</EEE>
                       <FFF/>
               </DDD>
               <DDD attrA="a2" attrB="b1">
                       <EEE>Value3 of EEE</EEE>
                       <FFF/>
               </DDD>
       </CCC>
       ...
 Then
       getNodeValuesHashedByNamedAttrs("/AAA/BBB/CCC", new String[] {"attrA", "attrB"})
 returns:
       Keys                                    Values
       --------------------------              -------------------------
       {"a1", "b1"}                            first node of DDD
       {"a1", "b2"}                            second node of DDD
       {"a2", "b1"}                            third node of DDD
 
 

Throws:

XMLUtilException

Since:

1.0

getNodeValuesHashedByNamedAttrs

public MultiKeyHashtable getNodeValuesHashedByNamedAttrs(java.lang.String nodeName,
                                                         java.lang.String[] attrNames)
                                                  throws XMLUtilException

Given a node name (with path) and attributes array, returns all node values with the same name in the same path. The Hash Key is String array of all attributes values. For example, a node

"/AAA/BBB/CCC"

is defined as:

    ...
    <CCC>
    <DDD attrA="a1" attrB="b1">v1</DDD>
    <DDD attrA="a2" attrB="b2">v2</DDD>
    <DDD attrA="a3" attrB="b3">v3</DDD>
    <DDD attrA="a4" attrB="b4">v4</DDD>
    <DDD attrA="a5" attrB="b5">v5</DDD>
    </CCC>
    ...
 

Then

getNodeValuesHashedByNamedAttrs("/AAA/BBB/CCC", new String[] {"attrA", "attrB"})

returns:

    Keys                              Values    
    --------------------------        -------------------------
    {"a1",  "b1"}                     v1
    {"a2",  "b2"}                     v2
    {"a3",  "b3"}                     v3
    {"a4",  "b4"}                     v4
    {"a5",  "b5"}                     v5
 

This method is a sub case of getNodesHashedByNamedAttrs(), in case the node is leaf.

Throws:

XMLUtilException

Since:

1.0

getNodesHashedByNamedAttr

public java.util.Hashtable getNodesHashedByNamedAttr(java.lang.String nodeName,
                                                     java.lang.String attrName)
                                              throws XMLUtilException

Given a node name (with path) and one attribute, returns Hashtable of all nodes with the same name in the same path. The Hash Key is String value of given attribute value. This method is a simplified version of getNodeValuesHashedByNamedAttrs(). It takes only one attribute, and returns Hashtable, instead of MultiKeyHashtable. For example, a node

       "/AAA/some-tag"
 is defined as:
       ...
       <some-tag>
               <some-node attrA="a1">
                       <sub-node>value1</sub-node>
               </some-node>
               <some-node attrA="a2">
                       <sub-node>value2</sub-node>
               </some-node>
               <some-node attrA="a3">
                       <sub-node>value3</sub-node>
               </some-node>
       </some-tag>
       ...
 Then
       getNodeValuesHashedByNamedAttr("/AAA/some-tag", "attrA")
 returns:
       Keys                          Values
       --------------------------    -------------------------
       a1                            first node of some-node
       a2                            second node of some-node
       a3                            third node of some-node
 
 

Throws:

XMLUtilException

Since:

1.0

getNodeValuesHashedByNamedAttr

public java.util.Hashtable getNodeValuesHashedByNamedAttr(java.lang.String nodeName,
                                                          java.lang.String attrName)
                                                   throws XMLUtilException

Given a node name (with path) and one attribute, returns Hashtable of all nodes with the same name in the same path. The Hash Key is String value of given attribute value. This method is a simplified version of getNodeValuesHashedByNamedAttrs(). It takes only one attribute, and returns Hashtable, instead of MultiKeyHashtable. For example, a node

       "/AAA/some-tag"
 is defined as:
       ...
       <some-tag>
               <some-node attrA="a1">
                       <sub-node>value1</sub-node>
               </some-node>
               <some-node attrA="a2">
                       <sub-node>value2</sub-node>
               </some-node>
               <some-node attrA="a3">
                       <sub-node>value3</sub-node>
               </some-node>
       </some-tag>
       ...
 Then
       getNodeValuesHashedByNamedAttr("/AAA/some-tag", "attrA")
 returns:
       Keys                                    Values
       --------------------------              -------------------------
       a1                                      value1 
       a2                                      value2 
       a3                                      value3 

 

Throws:

XMLUtilException

Since:

1.0

getAttrValuesHashedByNamedAttr

public java.util.Hashtable getAttrValuesHashedByNamedAttr(java.lang.String nodeName,
                                                          java.lang.String val_attrName,
                                                          java.lang.String key_attrName)
                                                   throws XMLUtilException

Given node name (with path) and two attribute's names, returns a Hashtable with key is one attribute's value and value is another attribute's value.

Returns:

Hashtable

Throws:

XMLUtilException

Since:

1.0

getAttrValuesHashedByNamedAttrs

public MultiKeyHashtable getAttrValuesHashedByNamedAttrs(java.lang.String nodeName,
                                                         java.lang.String val_attrName,
                                                         java.lang.String[] key_attrName)
                                                  throws XMLUtilException

Given node name (with path), an attribute name and an array of attribute names, returns a MultiKeyHashtable with keys from two or more attributes and value from another attribute.

Returns:

MultiKeyHashtable with results

Throws:

XMLUtilException

Since:

1.0.3

getChildNodeHashValues

public java.util.Hashtable getChildNodeHashValues(java.lang.String nodeName)
                                           throws XMLUtilException

Given a node name, return all child nodes' name-value pairs into a hashtable. Node names are hashkeys, node String values are hashvalues.

Returns:

Hashtable. Node names are hashkeys, node String values are hashvalues.

Throws:

XMLUtilException

Since:

1.0