public class

ObjectGraphIterator

extends Object
implements Iterator<E>
java.lang.Object
   ↳ org.apache.commons.collections.iterators.ObjectGraphIterator

Class Overview

An Iterator that can traverse multiple iterators down an object graph.

This iterator can extract multiple objects from a complex tree-like object graph. The iteration starts from a single root object. It uses a Transformer to extract the iterators and elements. Its main benefit is that no intermediate List is created.

For example, consider an object graph:

                 |- Branch -- Leaf
                 |         \- Leaf
         |- Tree |         /- Leaf
         |       |- Branch -- Leaf
  Forest |                 \- Leaf
         |       |- Branch -- Leaf
         |       |         \- Leaf
         |- Tree |         /- Leaf
                 |- Branch -- Leaf
                 |- Branch -- Leaf
The following Transformer, used in this class, will extract all the Leaf objects without creating a combined intermediate list:
 public Object transform(Object input) {
   if (input instanceof Forest) {
     return ((Forest) input).treeIterator();
   }
   if (input instanceof Tree) {
     return ((Tree) input).branchIterator();
   }
   if (input instanceof Branch) {
     return ((Branch) input).leafIterator();
   }
   if (input instanceof Leaf) {
     return input;
   }
   throw new ClassCastException();
 }

Internally, iteration starts from the root object. When next is called, the transformer is called to examine the object. The transformer will return either an iterator or an object. If the object is an Iterator, the next element from that iterator is obtained and the process repeats. If the element is an object it is returned.

Under many circumstances, linking Iterators together in this manner is more efficient (and convenient) than using nested for loops to extract a list.

Summary

Fields
protected Iterator currentIterator The current iterator
protected Object currentValue The current value
protected boolean hasNext Whether there is another element in the iteration
protected Iterator lastUsedIterator The last used iterator, needed for remove()
protected Object root The root object in the tree
protected final ArrayStack stack The stack of iterators
protected Transformer transformer The transformer to use
Public Constructors
ObjectGraphIterator(Object root, Transformer transformer)
Constructs an ObjectGraphIterator using a root object and transformer.
ObjectGraphIterator(Iterator rootIterator)
Constructs a ObjectGraphIterator that will handle an iterator of iterators.
Public Methods
boolean hasNext()
Checks whether there are any more elements in the iteration to obtain.
Object next()
Gets the next element of the iteration.
void remove()
Removes from the underlying collection the last element returned.
Protected Methods
void findNext(Object value)
Finds the next object in the iteration given any start object.
void findNextByIterator(Iterator iterator)
Finds the next object in the iteration given an iterator.
void updateCurrentIterator()
Loops around the iterators to find the next value to return.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.util.Iterator

Fields

protected Iterator currentIterator

The current iterator

protected Object currentValue

The current value

protected boolean hasNext

Whether there is another element in the iteration

protected Iterator lastUsedIterator

The last used iterator, needed for remove()

protected Object root

The root object in the tree

protected final ArrayStack stack

The stack of iterators

protected Transformer transformer

The transformer to use

Public Constructors

public ObjectGraphIterator (Object root, Transformer transformer)

Constructs an ObjectGraphIterator using a root object and transformer.

The root object can be an iterator, in which case it will be immediately looped around.

Parameters
root the root object, null will result in an empty iterator
transformer the transformer to use, null will use a no effect transformer

public ObjectGraphIterator (Iterator rootIterator)

Constructs a ObjectGraphIterator that will handle an iterator of iterators.

This constructor exists for convenience to emphasise that this class can be used to iterate over nested iterators. That is to say that the iterator passed in here contains other iterators, which may in turn contain further iterators.

Parameters
rootIterator the root iterator, null will result in an empty iterator

Public Methods

public boolean hasNext ()

Checks whether there are any more elements in the iteration to obtain.

Returns
  • true if elements remain in the iteration

public Object next ()

Gets the next element of the iteration.

Returns
  • the next element from the iteration
Throws
NoSuchElementException if all the Iterators are exhausted

public void remove ()

Removes from the underlying collection the last element returned.

This method calls remove() on the underlying Iterator and it may throw an UnsupportedOperationException if the underlying Iterator does not support this method.

Throws
UnsupportedOperationException if the remove operator is not supported by the underlying Iterator
IllegalStateException if the next method has not yet been called, or the remove method has already been called after the last call to the next method.

Protected Methods

protected void findNext (Object value)

Finds the next object in the iteration given any start object.

Parameters
value the value to start from

protected void findNextByIterator (Iterator iterator)

Finds the next object in the iteration given an iterator.

Parameters
iterator the iterator to start from

protected void updateCurrentIterator ()

Loops around the iterators to find the next value to return.