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.