uk.ac.sheffield.jast.xml

Class XMLIterator

java.lang.Object

uk.ac.sheffield.jast.xml.XMLIterator

All Implemented Interfaces:

java.util.Iterator<Content>

public class XMLIterator
extends java.lang.Object
implements java.util.Iterator<Content>

XMLIterator is an iterator for traversing an XML tree in document order. XMLIterator implements the Iterator<Content> interface and supports the hasNext(), next() and remove() methods. XMLIterator performs a pre-order traversal of the Document tree, that is, it visits each parent node, then the contents of the parent, in the order that the contents were added. This is also known as visiting the tree in document order.

XMLIterator may be supplied with a Filter upon creation, in which case the next() method will only visit those nodes that are accepted by the Filter, although all nodes in the tree will be traversed, while searching for acceptable nodes. After each call to next(), it is legal to remove the current node from the tree, which will also remove any dependent contents. Removing a node does not affect the traversal of the tree; in particular, the descendants of any removed nodes will still be traversed.

If created with the notRoot flag set, iteration will commence with the successors of the starting node. This allows client programs to iterate over the descendants of a node, excluding the node itself. If both the notRoot flag and a Filter are supplied, traversal will commence with the successors of the starting node, but only nodes satisfying the Filter will actually be visited.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private Content	current The currently visited node.
private Filter	filter The Filter used to select which Content nodes to visit, while traversing the XML tree.
private java.util.List<Content>	open The open list of future nodes to traverse.

Constructor Summary

Constructors

Constructor and Description
XMLIterator(Content node) Creates a XMLIterator to traverse an XML tree.
XMLIterator(Content node, boolean notRoot) Creates a XMLIterator to traverse all of the descendants of a node.
XMLIterator(Content node, Filter filter) Creates a XMLIterator to traverse an XML tree using a Filter.
XMLIterator(Content node, Filter filter, boolean notRoot) Creates a XMLIterator to traverse the descendants of a node using a Filter.

Method Summary

Modifier and Type	Method and Description
boolean	hasNext() Reports whether this XMLIterator has further nodes to visit.
Content	next() Advances this XMLIterator to the next node and returns this node.
void	remove() Removes the current node.
private void	seek() Secret method to seek the next Content node that is accepted by a Filter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator

forEachRemaining

Field Detail

current

private Content current

The currently visited node. This is initially null and only valid after a call to next() has selected the node and updated the open list of future nodes to traverse.

filter

private Filter filter

The Filter used to select which Content nodes to visit, while traversing the XML tree.

open

private java.util.List<Content> open

The open list of future nodes to traverse. This behaves like a stack, from which the top node is removed and made the current node, then the children of the current node are pushed back onto the front of the stack.

Constructor Detail

XMLIterator

public XMLIterator(Content node)

Creates a XMLIterator to traverse an XML tree. Works whether the Content node is a Document, an Element or some leaf-node. This node and all of its descendants will be traversed in document order, that is, a pre-order traversal of the XML tree will be performed. This constructor is called by Content's iterator() method.

Parameters:

node - the root of the XML tree.

XMLIterator

public XMLIterator(Content node,
                   boolean notRoot)

Creates a XMLIterator to traverse all of the descendants of a node. Excluding the starting node, all of this node's descendants will be traversed in document order. This constructor is called by Content's descendants() method. It is used during XPath searching.

Parameters:

node - the root of the XML tree.

notRoot - a flag indicating that the root is not included.

XMLIterator

public XMLIterator(Content node,
                   Filter filter)

Creates a XMLIterator to traverse an XML tree using a Filter. The Filter determines which nodes are eventually visited; other nodes will be skipped during the traversal. Nodes will be visited or skipped in document order, that is, a pre-order traversal of the XML tree will be performed. This constructor is called by Content's iterator(Filter) method.

Parameters:

node - the root of the XML tree.

filter - a Filter to apply.

XMLIterator

public XMLIterator(Content node,
                   Filter filter,
                   boolean notRoot)

Creates a XMLIterator to traverse the descendants of a node using a Filter. Excluding the starting node, all of this node's descendants will be traversed in document order, but only those nodes satisfying the Filter will actually be visited. This constructor is called by Content's descendants(Filter) method.

Parameters:

node - the root of an XML tree.

filter - a Filter to apply.

notRoot - a flag indicating that the root is not included.

Method Detail

seek

private void seek()

Secret method to seek the next Content node that is accepted by a Filter. Only invoked if this XMLIterator has a Filter, this method is called after construction, and after each call to next(), to seek the next acceptable node. It repeatedly expands the first node on the open list until that node, or one of its children, siblings, etc. is accepted by the Filter, or the open list is empty.

hasNext

public boolean hasNext()

Reports whether this XMLIterator has further nodes to visit. If at least one node remains to be visited, returns true, otherwise false.

Specified by:

hasNext in interface java.util.Iterator<Content>

Returns:

true, if there are more nodes to visit.

next

public Content next()

Advances this XMLIterator to the next node and returns this node. The traversal algorithm is a pre-order exploration of the XML tree. If the open list of nodes to explore is not empty, selects the first node from this list and makes this the current node. Removes the current node from the open list, and pushes the immediate children of this node onto the front of the list. If nodes are being filtered, the open list is processed repeatedly until an acceptable node advances to the front of this list, or the list becomes empty.

Specified by:

next in interface java.util.Iterator<Content>

Returns:

the current node, or null.

remove

public void remove()
            throws java.lang.IllegalStateException

Removes the current node. This is the only safe way to delete the contents of an XML tree while traversing the tree. The current node may only be deleted once, after a call to next(). If remove() is called before the first node is visited using next(), or if remove() is called more than once without an intervening next(), this method throws an IllegalStateException.

Specified by:

remove in interface java.util.Iterator<Content>

Throws:

java.lang.IllegalStateException - if there is no current node.