org.apache.commons.collections.iterators
Class ObjectGraphIterator
java.lang.Object
org.apache.commons.collections.iterators.ObjectGraphIterator
- Iterator
public class ObjectGraphIterator
extends java.lang.Object
implements Iterator
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.
$Revision: 1.3 $ $Date: 2004/05/03 11:50:30 $
ObjectGraphIterator(Iterator rootIterator) - Constructs a ObjectGraphIterator that will handle an iterator of iterators.
|
ObjectGraphIterator(Object root, Transformer transformer) - Constructs an ObjectGraphIterator using a root object and transformer.
|
protected void | findNext(Object value) - Finds the next object in the iteration given any start object.
|
protected void | findNextByIterator(Iterator iterator) - Finds the next object in the iteration given an iterator.
|
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 void | updateCurrentIterator() - Loops around the iterators to find the next value to return.
|
currentIterator
protected Iterator currentIterator
The current iterator
currentValue
protected Object currentValue
The current value
hasNext
protected boolean hasNext
Whether there is another element in the iteration
lastUsedIterator
protected Iterator lastUsedIterator
The last used iterator, needed for remove()
root
protected Object root
The root object in the tree
stack
protected final ArrayStack stack
The stack of iterators
transformer
protected Transformer transformer
The transformer to use
ObjectGraphIterator
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.
rootIterator
- the root iterator, null will result in an empty iterator
ObjectGraphIterator
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.
root
- the root object, null will result in an empty iteratortransformer
- the transformer to use, null will use a no effect transformer
findNext
protected void findNext(Object value)
Finds the next object in the iteration given any start object.
value
- the value to start from
findNextByIterator
protected void findNextByIterator(Iterator iterator)
Finds the next object in the iteration given an iterator.
iterator
- the iterator to start from
hasNext
public boolean hasNext()
Checks whether there are any more elements in the iteration to obtain.
- true if elements remain in the iteration
next
public Object next()
Gets the next element of the iteration.
- the next element from the iteration
remove
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.
updateCurrentIterator
protected void updateCurrentIterator()
Loops around the iterators to find the next value to return.
Copyright © 2001-2006 Apache Software Foundation. All Rights Reserved.