XMLNodesIterator

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

There are two ways to create the iterator:

• Getting the iteratorBy calling the XMLNode.iterator() method
• By creating directly a XMLNodesIterator with an XMLNode as argument

Getting the iterator through the XMLNode

Each XMLNode is iterable: you can get the iterator by calling the XMLNode.iterator() method. Iterating on a node will allow to navigate in the subtree beginning with this node an below. The iterator is an instance of the XMLNodesIterator class.

Using the next method

The XMLNodesIterator.next() method will iterator to the next node, beginning with the node which is at the root of the iterator.

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

Directly creating a XMLNodesIterator

It is possible to create the XMLNodesIterator directly, with the root of the iterator as the argument.

Using the nextNode method

The XMLNodesIterator.nextNode() method will iterator to the next node, beginning with the node which is the next node after the root of the iterator.

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 nextNode() method will return the first node
• The second nextNode() method will return the second node
• Further hasNext() methods will return false

Filtering nodes

It is possible to filter the nodes in the iterator, to:

• Know when a particular node name, possibly with specific attributes, is encountered
• Identify the ancestor node of a particular node, if it complies with a filter

Node filters

A NodeFilter allows to define a filter. This filter has:

• A filter name, which will allow to identify it when encountered in the iterator
• A node name (possibly including the node name prefix), which will define which node is looked for by the filter

A filter can also have a list of attributes with values which can be andatory for the node to be considered to be compatible with the filter.

For example, the following filter looks for nodes whose name is y:ProxyAutoBoundsNode:

   NodeFilter filter = new NodeFilter("MyFilter", "y:ProxyAutoBoundsNode");

The following nodes are compatible with the filter:

   <y:ProxyAutoBoundsNode/>
   <y:ProxyAutoBoundsNode name="myName"/>

The following filter looks for nodes whose name is y:ProxyAutoBoundsNode and the visible attribute is equal to "true":

   NodeFilter filter = new NodeFilter("MyFilter", "y:ProxyAutoBoundsNode");
   filter.addAttribute("visible", "true");

Ony the last node is compatible with the filter:

   <y:ProxyAutoBoundsNode/>
   <y:ProxyAutoBoundsNode name="myName"/>
   <y:ProxyAutoBoundsNode name="myName" visible="false"/>
   <y:ProxyAutoBoundsNode name="myName" visible="true"/>

Settings filters to the iterator

The XMLNodesIterator.setParentFilters(NodeFilter...) allows to set the filters to apply for the iterator.

Filtering algorithm

If after the next() or nextNode(), the current node is compatible with one of the filters:

• The XMLNodesIterator.hasCurrentFilterName() method returns true
• The XMLNodesIterator.getCurrentFilterName() method returns the name of the filter
• The XMLNodesIterator.getParentFilterStates() method returns the state

For all nodes:

• The XMLNodesIterator.getParentFilterStates() method returns the state for all of the filters for the current node. True for a filter means that this node is a child of an ancestor which is compatible with the filter
• The XMLNodesIterator.inParentFilter(String) method returns true if the current node has an ancestor which is compatible with the filter

Example

Suppose the following XML file:

<root name="theRoot">
  <filteredNode name="one" visible="true">
    <element name="two"/>
  </filteredNode>
  <filteredNode name="three">
    <element name="four"/>
  </filteredNode>
  <element name="five"/>
</root>

And the filter:

   NodeFilter filter = new NodeFilter("MyFilter", "filteredNode");
   filter.addAttribute("visible", "true");

If we create an iterator on the theRoot node:

• The first nextNode() method will return the one node. The getCurrentFilterName() must return "MyFilter". The inParentFilter("MyFilter") must return true
• The second nextNode() method will return the one node. The hasCurrentFilterName() must return false. The inParentFilter("MyFilter") must return true
• For all the remaining nextNode() method will return the three node, the hasCurrentFilterName() must return false, and the inParentFilter("MyFilter") must return false