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

Creating an XML tree

Several methods allow to create an XML tree, with an XMLRoot or an XMLNode at the top of the tree.

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)
• It is possible to allow internal readers creation in this parser instance (by default they are not allowed)

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

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

Several methods allow to create an XML tree, with an XMLRoot at the top of the tree.

The most simple are:

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

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

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

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

Configuring the parsing

Several properties allows to configure the parsing:

• Show the exceptions encountered during the parsing
• Show the warnings encountered during the parsing
• Preserve the space in the CDATA content
• Keep the line numbers
• Keep the namespace informations
• Allow internal readers creation in this parser instance

The most straightforward way to configure these properties is to add an int option to the methods, such as:

• XMLNodeUtilities.getNode(File, int) from a File
• XMLNodeUtilities.getNode(URL, int) from an URL
• XMLNodeUtilities.getNode(String, int) from a String

Note that the properties is an AND of the following values:

• XMLNodeUtilitiesOptions.PRESERVE_SPACE to specify that spaces will be preserved
• XMLNodeUtilitiesOptions.SHOW_EXCEPTIONS to specify that exceptions will be shown for the parsing
• XMLNodeUtilitiesOptions.SHOW_WARNINGS to specify that warnings will be shown for the parsing
• XMLNodeUtilitiesOptions.KEEP_LINE_NUMBERS to specify that line numbers will be kept
• XMLNodeUtilitiesOptions.NAMESPACE_AWARE to specify that namespace informations will be kept
• XMLNodeUtilitiesOptions.ALLOW_INTERNAL_READERS to specify that internal readers will be allowed

For example:

   XMLRoot root = XMLNodeUtilities.getNode(xmlURL, XMLNodeUtilitiesOptions.KEEP_LINE_NUMBERS & XMLNodeUtilitiesOptions.NAMESPACE_AWARE);

Preserving spaces

The XMLNodeUtilities class has methods which will preserve 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 XMLNodeUtilities.getRootNode(<the XML file>, false, false, true, false), the spaces in CDATA content will be preserved.

Keeping line numbers

The XMLNodeUtilities class has methods which will keep the line numbers for the nodes. The resulting nodes NumberedNode.getLineNumber() method will return the associated line number in the XML file.

If you perform XMLNodeUtilities.getRootNode(<the XML file>, false, false, false, true), the line numbers will be preserved.

Prevent the internal creation of readers

Contrary to the XMLSAXParser, by default this class will NOT try to create readers through theFiles.newBufferedReader(path, charset) method.

Configuration of the parser

It is possible to configure the parsing by using the XMLParserConfiguration configuration class through one of the following methods:

• XMLNodeUtilities.getRootNode(File, XMLParserConfiguration, boolean, boolean) creates the root node of the tree from a File
• XMLNodeUtilities.getRootNode(URL, XMLParserConfiguration, boolean, boolean) creates the root node of the tree from an URL
• XMLNodeUtilities.getRootNode(String, XMLParserConfiguration, boolean, boolean) creates the root node of the tree from a String

Keeping the namespace informations

It is possible to keep the namespace informations during the parsing.

Using an ErrorHandler for the parsing

It is possible to configure the XMLNodeUtilities 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 static method XMLNodeUtilities.setErrorHandler(ErrorHandler) method.

Adding features or properties for the parsing

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

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

The method is the static method XMLNodeUtilities.setErrorHandler(ErrorHandler) method.

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 XMLNodeUtilities.print(XMLNode, int) method allows to get the String content associated with the XML content under a root node
• The XMLNodeUtilities.print(XMLNode, int, File) and method XMLNodeUtilities.print(XMLNode, int, URL) methods allow to save the XML content under a root node in a File or URL

Searching for children elements

Several method allow to serarch for children elemetns which have a spzecified node name or qualified node name:

• 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
• The XMLNodeUtilities.search(XMLNode, QName, boolean) method allows to search for the list of children nodes which have a specific qualified 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 recursively 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 XMLNodeUtilities.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