XMLNodeUtilities2

The XMLNodeUtilities2 class contains various utilities concerning XML content.

It works on the XMLNode root of the 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

Customization of the underlying parser

It is possible to customize the way the XML content is parsed to create the tree:

• It is possible to preserve spaces such as for the xml.space="&reserve& XML declaration (by default spaces are not preserved)
• It is possible to keep the line numbers in the input XML file in the nodes in the result (by default the line numbers are removed)
• It is possible to be silent about the warnings during the parsing (by default warnings are not shown)
• It is possible to be silent about the errors during the parsing by default (by default exceptions are not shown)
• It is possible to keep the namespace informations during the parsing (by default the namespace informations are skipped)

Preserving spaces

The XMLNodeUtilities2.preserveSpaces(boolean) specifies if you want ot preserver the spaces when getting the root node from an URL, a File, a Reader, or a String. Some of these methods allow to preserve spaces in CDATA content. For example in this example here:

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

If you perform:

   XMLNodeUtilities2 utils = new XMLNodeUtilities2();
   utils.preserveSpaces(true);
   XMLRoot root = XMLNodeUtilities.getRootNode(<the XML file>);

The spaces in CDATA content will be preserved.

Keeping line numbers

The XMLNodeUtilities2.keepLineNumbers(boolean) method specifies if we want to keep the line numbers for the nodes. The resulting nodes NumberedNode.getLineNumber() method will return the associated line number in the XML file.

Keeping the namespace informations

The XMLNodeUtilities2.setNameSpaceAware(boolean) specifies if the namespace informations must be kept during the parsing.

Using an ErrorHandler for the parsing

It is possible to configure the XMLNodeUtilities2 class to set an ErrorHandler to be notified if a SAX exception is encountered when parsing the file, URL, or Stream.

The method is the method XMLNodeUtilities2.setErrorHandler(ErrorHandler) method.

Adding features or properties for the parsing

It is possible to configure the XMLNodeUtilities2 class to add SAX factory features or parser properties:

• The XMLNodeUtilities2.setFeature(String, boolean) method allow to set a feature for the factory on the underlying parser
• The XMLNodeUtilities2.setProperty(String, Object) method allow to set a property on the underlying parser

The method is XMLNodeUtilities2.setErrorHandler(ErrorHandler) method.

Creating an XML tree

Several methods allow to create an XMLNode tree, with an XMLRoot at the top of the tree. The most simple are:

• XMLNodeUtilities2.getRootNode(File) creates the root node of the tree from a File
• XMLNodeUtilities2.getRootNode(URL) creates the root node of the tree from an URL
• XMLNodeUtilities2.getRootNode(String) creates the root node of the tree from a String

This class makes use of the XMLTreeHandler class internally to parse the content.

Creating an XML tree with an XMLNode at the root of the tree

Several methods allow to create an XMLNode tree, with an XMLNode at the top of the tree. The most simple are:

• XMLNodeUtilities2.getNode(File) creates the root node of the tree from a File
• XMLNodeUtilities2.getNode(URL) creates the root node of the tree from an URL
• XMLNodeUtilities2.getNode(String) creates the root node of the tree from a String

Printing the content of an XML tree

Several methods allows to print the content of an XML tree, either in a File, URL, or String:

• The XMLNodeUtilities2.print(XMLNode, int) method allows to get the String content associated with the XML content under a root node
• The XMLNodeUtilities2.print(XMLNode, int, File) and method XMLNodeUtilities2.print(XMLNode, int, URL) methods allow to save the XML content under a root node in a File or URL

Searching for children elements

The XMLNodeUtilities2.search(XMLNode, String, boolean) method allows to search for the list of children nodes which have a specific name under a root node.

For example, suppose the following XML file:

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

If we apply:

   XMLRoot root = XMLNodeUtilities.getRootNode(<the XML file>);
   List<XMLNode> nodes = XMLNodeUtilities.search(root, "element1", false);

The nodes result will return only one element because the search only look for direct children of the node:

• The "first" node

If we apply:

   XMLRoot root = XMLNodeUtilities.getRootNode(<the XML file>);
   List<XMLNode> nodes = XMLNodeUtilities.search(root, "element1", true);

The nodes result will return two elements because the search look ercursively for all children:

• The "first" node
• The "third" node

Searching for children elements among several possible node names

It is also possible to search for several possible node names or qualified node names. For example:

• The XMLNodeUtilities.searchForNames(XMLNode, List, boolean) will search for a node which have one of the specified node names
• The XMLNodeUtilities.search(XMLNode, List, boolean) will search for a node which have one of the specified qualified node names

For example, suppose the following XML file:

<root desc="example">
   <element2 name="first"/>
   <element1 name="second"/>
   <element3 name="third"/>
</root>

If we apply:

   XMLRoot root = XMLNodeUtilities.getRootNode(<the XML file>);
   List<String> list = new ArrayList<>;
   list.add("element1");
   list.add("element3");
   List<XMLNode> nodes = XMLNodeUtilities.searchForNames(root, list, false);

The nodes result will return two elements:

• The "first" node
• The "third" node

Searching for the first child element

The XMLNodeUtilities2.searchFirst(XMLNode, String, boolean) method allows to search for the first child node which has a specific name under a root node.

For example, suppose the following XML file:

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

If we apply:

   XMLRoot root = XMLNodeUtilities.getRootNode(<the XML file>);
   XMLNode node = XMLNodeUtilities.searchFirst(root, "element1", false);

The node result will return:

• The "first" node