XMLNode and XMLRoot

There are two node classes used by the xml.tree package:

• XMLNode is the general class for all Nodes in an XML content
• XMLRoot is the class for root Nodes in an XML content. XMLRoot elements are Nodes which don't have a parent and have optionally a declared encoding

The XMLNode.toString() method uses the XMLNodeUtilities class under the hood to get the XML string content of the node.

Name and qualified name

It is possible to create an XMLNode or XMLRoot using an unqualified name or a qualified name. For example:

   XMLNode node = new XMLNode("element");
   XMLNode node1 = new XMLNode(new QName("http://org.test.names", "element", "p"));

The constructor will automatically create a name with a prefix without a namespace URI if the provided name contains a colon. For example:

   XMLNode node = new XMLNode("p:element");
   // is equivalent to:
   XMLNode node = new XMLNode(new QName(XMLConstants.NULL_NS_URI, "element", "p"));

All the classes working with XMLNode and XMLRoot elements support using unqualified or qualified names.

Node children

You can add a child to a node with the XMLNode.addChild(XMLNode) method. You can also directly create a child node with a specified name and add it to its parent by one of the following methods:

• The XMLNode.addChild(String) will create the child of a specified name and add it to the node
• The XMLNode.addChild(QName) will create the child of a specified qualified name and add it to the node

For example:

   XMLRoot root = new XMLRoot("root");
   XMLNode child = root.addChild("theChild");

The ordered list of direct children of a node can be retrieved with the XMLNode.getChildren() method. The XMLNode.getChild(int) allows to get the child at a particular index.

Getting the index of a Node in its parent

To get the index of a Node in its parent, you can use the XMLNode.getIndex(XMLNode) method which returns the index, giving the child Node. If the Node is not a child of the parent, the method will return -1.

The XMLNode.getIndexInParent() method returns the index of a Node in its parent. If the Node has no parent, the method will return -1.

For example:

   XMLNode child = parentNode.getChild(2);
   int index = parentNode.getIndex(child); // the value if index is 2
   int indexInParent = child.getIndexInParent();  // the value if indexInParent is 2

The XMLNode.getAllChildren(String) and XMLNode.getAllChildren(QName) methods allow to get all the children (direct and indirect) of a specified name or qualified name.

Node attributes

The atributes of a node can be retrieved with the XMLNode.getAttributes() method.

Adding a node will automatically create an attribute name without a namespace URI if the provided name contains a colon. For example:

   XMLNode node = new XMLNode("element");
   node.addAttribute("p:name", "the content");
   // is equivalent to:
   XMLNode node = new XMLNode("element");
   QName qname = new QName(XMLConstants.NULL_NS_URI,"name", "p");
   node.addAttribute(qname);

Iterating over the attributes

The XMLNode.attributesIterator() returns an iterator which iterates ocer the attributes of the node in alphabetical order.

The XMLNode.orderedAttributesIterator() returns an iterator which iterates ocer the attributes of the node in the order in which they have been added to their node.

Binding prefixes through the addAttribute method

If you add an attribute which has the xmnls:<prefix> name, then the API will bind a prefix to the associated URI value rather than add an attibute.

For example, doing:

   XMLNode node = new XMLNode("element");
   node.addAttribute("xmlns:xi", "http://www.w3.org/2001/XInclude");

is equivalent to:

   XMLNode node = new XMLNode("element");
   node.bindPrefix("xi", "http://www.w3.org/2001/XInclude");

Attribute value

Several methods allow to get the value of a specific attribute, as a String, a boolean, or any type of numeric value.

For example:

   XMLRoot root = XMLNodeUtilities.getRootNode(<the XML file>);
   int valueAsInt = root.getAttributeValueAsInt("theAttribute");

It is possible to specify a default value to rturn if the attribute can not be parsed as the specified numeric type, for example^[1]

If not specified, the default value will be 0 for a numeric value, and false for a boolean

:

   int valueAsInt = root.getAttributeValueAsInt("theAttribute", -1); //the default value will be -1

By default the method will only accept attributes which are of the specified numeric value. For example, with the following node:

    <element key="2.52"/>

Getting the value of the key attribute will return 0:

   int valueAsInt = node.getAttributeValueAsInt("key"); // result is 0

It is possible to allow to cast the value, for example in the same case the result will be 2:

   int valueAsInt = node.getAttributeValueAsInt("key", 0, false); // result is 2

Several methods also allow to check if an attribute can be parsed in a specified type. For example:

   int valueAsInt = node.attributeValueIsInt("key"); // result true if the attribute value can be parsed as an int

CDATA value

As for the attributes, several methods allow to get the value of the CDATA of the node, as a String, a boolean, or any numeric type. For example:

   int valueAsInt = node.getCDATAValueAsInt();

Several methods also allow to check if the CDATA can be parsed in a specified type. For example:

 int valueAsInt = node.CDATAValueIsInt("key"); // result true if the  value can be parsed as an int

Binding prefixes

The XMLNode.bindPrefix(String, String) method allows to bind prefixes to URIs for the node. For example the following code:

   XMLNode node = new XMLNode("element");
   node.bindPrefix("xi", "http://www.w3.org/2001/XInclude");

will create the following node:

   <element xmnls:xi="http://www.w3.org/2001/XInclude" />

Get the Node path

The XMLNode.getNodePath() method return the path of a node. The path is the ordered list of nodes, starting with the root node of the XML tree.