Java Doc for IteratorUtils.java in  » Library » Apache-common-Collections » org » apache » commons » collections » Java Source Code / Java DocumentationJava Source Code and Java Documentation

WARNING: Due to human error certain binary incompatabilities were introduced between Commons Collections 2.1 and 3.0. The class remained source and test compatible, so if you can recompile all your classes and dependencies everything is OK. Those methods which are binary incompatible are marked as such, together with alternate solutions that are binary compatible against versions 2.1.1 and 3.1.
since:
   Commons Collections 2.1
version:
   $Revision: 405920 $ $Date: 2006-05-12 23:48:04 +0100 (Fri, 12 May 2006) $
author:
   Stephen Colebourne
author:
   Phil Steitz

Given two ordered Iterator s A and B, the Iterator.next method will return the lesser of A.next() and B.next().

The comparator is optional.

Given two ordered Iterator s A and B, the Iterator.next method will return the lesser of A.next() and B.next() and so on.

The comparator is optional.

Given two ordered Iterator s A and B, the Iterator.next method will return the lesser of A.next() and B.next() and so on.

The comparator is optional.

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

 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.

As the wrapped Iterator is traversed, an ArrayList of its values is created.

As the wrapped Iterator is traversed, an ArrayList of its values is created.

As the wrapped Iterator is traversed, an ArrayList of its values is created.

As the wrapped Iterator is traversed, an ArrayList of its values is created.

WARNING: This constant is binary incompatible with Commons Collections 2.1 and 2.1.1. Use EmptyIterator.INSTANCE for compatability with Commons Collections 2.1.1.

WARNING: This constant is binary incompatible with Commons Collections 2.1 and 2.1.1. Use EmptyListIterator.INSTANCE for compatability with Commons Collections 2.1.1.

WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use new ArrayIterator(array) for compatability.
Parameters:
  array - the array over which to iterate an iterator over the array
throws:
  NullPointerException - if array is null

This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
Parameters:
  array - the array over which to iterate an iterator over the array
throws:
  IllegalArgumentException - if the array is not an array
throws:
  NullPointerException - if array is null

WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use new ArrayIterator(array,start) for compatability.
Parameters:
  array - the array over which to iterate
Parameters:
  start - the index to start iterating at an iterator over part of the array
throws:
  IndexOutOfBoundsException - if start is less than zero or greaterthan the length of the array
throws:
  NullPointerException - if array is null

This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
Parameters:
  array - the array over which to iterate
Parameters:
  start - the index to start iterating at an iterator over part of the array
throws:
  IllegalArgumentException - if the array is not an array
throws:
  IndexOutOfBoundsException - if start is less than zero or greaterthan the length of the array
throws:
  NullPointerException - if array is null

WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use new ArrayIterator(array,start,end) for compatability.
Parameters:
  array - the array over which to iterate
Parameters:
  start - the index to start iterating at
Parameters:
  end - the index to finish iterating at an iterator over part of the array
throws:
  IndexOutOfBoundsException - if array bounds are invalid
throws:
  IllegalArgumentException - if end is before start
throws:
  NullPointerException - if array is null

This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
Parameters:
  array - the array over which to iterate
Parameters:
  start - the index to start iterating at
Parameters:
  end - the index to finish iterating at an iterator over part of the array
throws:
  IllegalArgumentException - if the array is not an array
throws:
  IndexOutOfBoundsException - if array bounds are invalid
throws:
  IllegalArgumentException - if end is before start
throws:
  NullPointerException - if array is null

This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
Parameters:
  array - the array over which to iterate a list iterator over the array
throws:
  IllegalArgumentException - if the array is not an array
throws:
  NullPointerException - if array is null

This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
Parameters:
  array - the array over which to iterate
Parameters:
  start - the index to start iterating at a list iterator over part of the array
throws:
  IllegalArgumentException - if the array is not an array
throws:
  IndexOutOfBoundsException - if start is less than zero
throws:
  NullPointerException - if array is null

This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
Parameters:
  array - the array over which to iterate
Parameters:
  start - the index to start iterating at
Parameters:
  end - the index to finish iterating at a list iterator over part of the array
throws:
  IllegalArgumentException - if the array is not an array
throws:
  IndexOutOfBoundsException - if array bounds are invalid
throws:
  IllegalArgumentException - if end is before start
throws:
  NullPointerException - if array is null

Given two ordered Iterator s A and B, the Iterator.next method will return the lesser of A.next() and B.next().

The comparator is optional. If null is specified then natural order is used.
Parameters:
  comparator - the comparator to use, may be null for natural order
Parameters:
  iterator1 - the first iterators to use, not null
Parameters:
  iterator2 - the first iterators to use, not null a combination iterator over the iterators
throws:
  NullPointerException - if either iterator is null

Given two ordered Iterator s A and B, the Iterator.next method will return the lesser of A.next() and B.next() and so on.

The comparator is optional. If null is specified then natural order is used.
Parameters:
  comparator - the comparator to use, may be null for natural order
Parameters:
  iterators - the iterators to use, not null or empty or contain nulls a combination iterator over the iterators
throws:
  NullPointerException - if iterators array is null or contains a null

Given two ordered Iterator s A and B, the Iterator.next method will return the lesser of A.next() and B.next() and so on.

The comparator is optional. If null is specified then natural order is used.
Parameters:
  comparator - the comparator to use, may be null for natural order
Parameters:
  iterators - the iterators to use, not null or empty or contain nulls a combination iterator over the iterators
throws:
  NullPointerException - if iterators collection is null or contains a null
throws:
  ClassCastException - if the iterators collection contains the wrong object type

This iterator is a valid iterator object that will iterate over nothing.

WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use EmptyIterator.INSTANCE for compatability with Commons Collections 2.1.1. an iterator over nothing

This iterator is a valid list iterator object that will iterate over nothing.

WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use EmptyListIterator.INSTANCE for compatability with Commons Collections 2.1.1. a list iterator over nothing

This iterator is a valid map iterator object that will iterate over nothing. a map iterator over nothing

This iterator is a valid iterator object that will iterate over nothing. an ordered iterator over nothing

This iterator is a valid map iterator object that will iterate over nothing. a map iterator over nothing

The returned iterator will only return objects that match the specified filtering predicate.
Parameters:
  iterator - the iterator to use, not null
Parameters:
  predicate - the predicate to use as a filter, not null a new filtered iterator
throws:
  NullPointerException - if either parameter is null

The returned iterator will only return objects that match the specified filtering predicate.
Parameters:
  listIterator - the list iterator to use, not null
Parameters:
  predicate - the predicate to use as a filter, not null a new filtered iterator
throws:
  NullPointerException - if either parameter is null

This method can handles objects as follows

• null - empty iterator
• Iterator - returned directly
• Enumeration - wrapped
• Collection - iterator from collection returned
• Map - values iterator returned
• Dictionary - values (elements) enumeration returned as iterator
• array - iterator over array returned
• object with iterator() public method accessed by reflection
• object - singleton iterator

The iterator will only stop looping if the remove method is called enough times to empty the collection, or if the collection is empty to start with.
Parameters:
  coll - the collection to iterate over, not null a new looping iterator
throws:
  NullPointerException - if the collection is null

The iterator will only stop looping if the remove method is called enough times to empty the list, or if the list is empty to start with.
Parameters:
  list - the list to iterate over, not null a new looping iterator
throws:
  NullPointerException - if the list is null
since:
   Commons Collections 3.2

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

 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.
Parameters:
  root - the root object to start iterating from, null results in an empty iterator
Parameters:
  transformer - the transformer to use, see above, null uses no effect transformer a new object graph iterator
since:
   Commons Collections 3.1

This iterator is a valid iterator object that will iterate over the specified object.

WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use new SingletonIterator(object) for compatability.
Parameters:
  object - the single object over which to iterate a singleton iterator over the object

This iterator is a valid list iterator object that will iterate over the specified object.
Parameters:
  object - the single object over which to iterate a singleton list iterator over the object

As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.
Parameters:
  iterator - the iterator to use, not null an array of the iterator contents
throws:
  NullPointerException - if iterator parameter is null

As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.
Parameters:
  iterator - the iterator to use, not null
Parameters:
  arrayClass - the class of array to create an array of the iterator contents
throws:
  NullPointerException - if iterator parameter is null
throws:
  NullPointerException - if arrayClass is null
throws:
  ClassCastException - if the arrayClass is invalid

As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.
Parameters:
  iterator - the iterator to use, not null a list of the iterator contents
throws:
  NullPointerException - if iterator parameter is null

As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.
Parameters:
  iterator - the iterator to use, not null
Parameters:
  estimatedSize - the initial size of the ArrayList a list of the iterator contents
throws:
  NullPointerException - if iterator parameter is null
throws:
  IllegalArgumentException - if the size is less than 1

As the wrapped Iterator is traversed, a LinkedList of its values is cached, permitting all required operations of ListIterator.
Parameters:
  iterator - the iterator to use, not null a new iterator
throws:
  NullPointerException - if iterator parameter is null

The transformation occurs during the next() method and the underlying iterator is unaffected by the transformation.
Parameters:
  iterator - the iterator to use, not null
Parameters:
  transform - the transform to use, not null a new transforming iterator
throws:
  NullPointerException - if either parameter is null