| 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.
since:
Commons Collections 3.1
version:
$Revision: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $
author:
Stephen Colebourne | 