xml.tree

The tree package contains additional classes allowing to get directly a tree of XML element from an XML file or URL. It also allows to manipulate this tree.

XMLNode and XMLRoot

There are two node classes used by the 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

XMLNodeUtilities

The XMLNodeUtilities class contains various utilities concerning XML content. It allows to:

• Create a tree of XMLNode from a File, a URL, or a String
• Print the content of a XML tree
• Search for nodes in a XMLNodes tree, allowing to filter the search

However it is possible to keep all spaces and new lines in CDATA content by using the XMLTreeHandler.preserveSpace(boolean) method.

XMLNodeUtilities2

The XMLNodeUtilities2 class is similar to the
class, but contains instance methods.

Searching for children

The XMLNodeUtilities.search(XMLNode, String, boolean) method allows to search for the list of children nodes which have a specific name under a root node. It is possible to use a filter for the search.

XMLTreeHandler

The XMLTreeHandler class allows to get the tree of XML elements in an XML file. The result will be a XMLRoot, which maintains the structure of the XML content, including the parent-children nodes relationships.

Note that if there is a declared encoding in the XML file, then the XMLRoot element will have this encoding.

The XMLNodeUtilities class uses the handler internally to parse the XML content.

Preserving space

By default the XMLTreeHandler trim CDATA content in the XML file, and considers that the CDATA content is null if the trimmed CDATA content is empty. For example in this case all the nodes have a null CDATA content except the second which will have the "my content" CDATA content:

<root desc="example">
  <element name="first">
    <element name="second">my content</element>
    <element name="third"/>
  </element>
</root>

The XMLTreeHandler.preserveSpace(boolean) method allows to preserve the space characters in the CDATA content. For example in this example here:

<root desc="example">
  <element name="first">the first line
   the second line
  </element>
</root>

Keeping line numbers

By default the XMLTreeHandler will not keep the line numbers for the nodes. The resulting nodes NumberedNode.getLineNumber() method will return -1.

The XMLTreeHandler.setKeepLineNumbers(boolean) method allows to keep the line numbers. The resulting nodes NumberedNode.getLineNumber() method will return the associated line number in the XML file.

XMLNodesIterator

The XMLNodesIterator class is an Iterator on the content of a XMLNode tree.

Each XMLNode is iterable, and iterating on a node will allow to navigate in the subtree beginning with this node an below.

For example suppose the following XML file:

<root name="example">
  <element name="first">
    <element name="second"/>
  </element>
</root>

If we create an iterator on the root node:

• The first next() method will return the root node
• The second next() method will return the first node
• The third next() method will return the second node
• Further hasNext() methods will return false

XMLTreeReplacer

The XMLTreeReplacer class allows to replace attributes in an XML file or tree by other values.

• The XMLTreeReplacer.NodePath element represent one path in the XML tree
• The XMLTreeReplacer.Node element represent one element in the XML tree. A node can specify one or several attribute change for this element

Examples

Suppose the following XML file:

<root desc="example">
  <element name="first">
    <element name="second"/>
    <element name="third"/>
  </element>
</root>

And the NodePath:

   NodePath path = new NodePath();
   path.addNode("root");
   path.addNode("element");
   Node node = path.addNode("element", 1);
   node.setAttribute("name", "changed");

Then the result of the XMLTreeReplacer.replace(File, File, NodePath...) method with the NodePath will be:

<root desc="example">
  <element name="first">
    <element name="second"/>
    <element name="changed"/>
  </element>
</root>

Converting an XMLRoot to a Document

The XMLDocumentBuilderFactory allows to convert an XMLRoot to a Document. It can be used for example with xsl transforms.

For example:

   XMLDocumentBuilderFactory factory = XMLDocumentFactory.getInstance();
   Document document = factory.parse(root);