## org.apache.commons.collections
Class IteratorUtils

    java.lang.Object
      org.apache.commons.collections.IteratorUtils

    public class IteratorUtils

extends java.lang.Object

Provides static utility methods and decorators for `Iterator` instances. The implementations are provided in the iterators subpackage.

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: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Stephen Colebourne, Phil Steitz

Field Summary
`static ResettableIterator` `EMPTY_ITERATOR` An iterator over no elements.
`static ResettableListIterator` `EMPTY_LIST_ITERATOR` A list iterator over no elements.
`static MapIterator` `EMPTY_MAP_ITERATOR` A map iterator over no elements.
`static OrderedIterator` `EMPTY_ORDERED_ITERATOR` An ordered iterator over no elements.
`static OrderedMapIterator` `EMPTY_ORDERED_MAP_ITERATOR` An ordered map iterator over no elements.

Constructor Summary
`IteratorUtils()` IteratorUtils is not normally instantiated.

Method Summary
`static ResettableIterator` `arrayIterator(java.lang.Object array)` Gets an iterator over an object or primitive array.
`static ResettableIterator` `arrayIterator(java.lang.Object[] array)` Gets an iterator over an object array.
`static ResettableIterator` `arrayIterator(java.lang.Object[] array, int start)` Gets an iterator over the end part of an object array.
`static ResettableIterator` `arrayIterator(java.lang.Object[] array, int start, int end)` Gets an iterator over part of an object array.
`static ResettableIterator` `arrayIterator(java.lang.Object array, int start)` Gets an iterator over the end part of an object or primitive array.
`static ResettableIterator` `arrayIterator(java.lang.Object array, int start, int end)` Gets an iterator over part of an object or primitive array.
`static ResettableListIterator` `arrayListIterator(java.lang.Object array)` Gets a list iterator over an object or primitive array.
`static ResettableListIterator` `arrayListIterator(java.lang.Object[] array)` Gets a list iterator over an object array.
`static ResettableListIterator` `arrayListIterator(java.lang.Object[] array, int start)` Gets a list iterator over the end part of an object array.
`static ResettableListIterator` `arrayListIterator(java.lang.Object[] array, int start, int end)` Gets a list iterator over part of an object array.
`static ResettableListIterator` `arrayListIterator(java.lang.Object array, int start)` Gets a list iterator over the end part of an object or primitive array.
`static ResettableListIterator` `arrayListIterator(java.lang.Object array, int start, int end)` Gets a list iterator over part of an object or primitive array.
`static java.util.Enumeration` `asEnumeration(java.util.Iterator iterator)` Gets an enumeration that wraps an iterator.
`static java.util.Iterator` `asIterator(java.util.Enumeration enumeration)` Gets an iterator that provides an iterator view of the given enumeration.
`static java.util.Iterator` `asIterator(java.util.Enumeration enumeration, java.util.Collection removeCollection)` Gets an iterator that provides an iterator view of the given enumeration that will remove elements from the specified collection.
`static java.util.Iterator` `chainedIterator(java.util.Collection iterators)` Gets an iterator that iterates through a collections of `Iterator`s one after another.
`static java.util.Iterator` `chainedIterator(java.util.Iterator[] iterators)` Gets an iterator that iterates through an array of `Iterator`s one after another.
`static java.util.Iterator` `chainedIterator(java.util.Iterator iterator1, java.util.Iterator iterator2)` Gets an iterator that iterates through two `Iterator`s one after another.
`static java.util.Iterator` `collatedIterator(java.util.Comparator comparator, java.util.Collection iterators)` Gets an iterator that provides an ordered iteration over the elements contained in a collection of `Iterator`s.
`static java.util.Iterator` `collatedIterator(java.util.Comparator comparator, java.util.Iterator[] iterators)` Gets an iterator that provides an ordered iteration over the elements contained in an array of `Iterator`s.
`static java.util.Iterator` `collatedIterator(java.util.Comparator comparator, java.util.Iterator iterator1, java.util.Iterator iterator2)` Gets an iterator that provides an ordered iteration over the elements contained in a collection of ordered `Iterator`s.
`static ResettableIterator` `emptyIterator()` Gets an empty iterator.
`static ResettableListIterator` `emptyListIterator()` Gets an empty list iterator.
`static MapIterator` `emptyMapIterator()` Gets an empty map iterator.
`static OrderedIterator` `emptyOrderedIterator()` Gets an empty ordered iterator.
`static OrderedMapIterator` `emptyOrderedMapIterator()` Gets an empty ordered map iterator.
`static java.util.Iterator` `filteredIterator(java.util.Iterator iterator, Predicate predicate)` Gets an iterator that filters another iterator.
`static java.util.ListIterator` `filteredListIterator(java.util.ListIterator listIterator, Predicate predicate)` Gets a list iterator that filters another list iterator.
`static java.util.Iterator` `getIterator(java.lang.Object obj)` Gets a suitable Iterator for the given object.
`static ResettableIterator` `loopingIterator(java.util.Collection coll)` Gets an iterator that loops continuously over the supplied collection.
`static ResettableListIterator` `loopingListIterator(java.util.List list)` Gets an iterator that loops continuously over the supplied list.
`static java.util.Iterator` `objectGraphIterator(java.lang.Object root, Transformer transformer)` Gets an iterator that operates over an object graph.
`static ResettableIterator` `singletonIterator(java.lang.Object object)` Gets a singleton iterator.
`static java.util.ListIterator` `singletonListIterator(java.lang.Object object)` Gets a singleton list iterator.
`static java.lang.Object[]` `toArray(java.util.Iterator iterator)` Gets an array based on an iterator.
`static java.lang.Object[]` `toArray(java.util.Iterator iterator, java.lang.Class arrayClass)` Gets an array based on an iterator.
`static java.util.List` `toList(java.util.Iterator iterator)` Gets a list based on an iterator.
`static java.util.List` `toList(java.util.Iterator iterator, int estimatedSize)` Gets a list based on an iterator.
`static java.util.ListIterator` `toListIterator(java.util.Iterator iterator)` Gets a list iterator based on a simple iterator.
`static java.util.Iterator` `transformedIterator(java.util.Iterator iterator, Transformer transform)` Gets an iterator that transforms the elements of another iterator.
`static java.util.Iterator` `unmodifiableIterator(java.util.Iterator iterator)` Gets an immutable version of an `Iterator`.
`static java.util.ListIterator` `unmodifiableListIterator(java.util.ListIterator listIterator)` Gets an immutable version of a `ListIterator`.
`static MapIterator` `unmodifiableMapIterator(MapIterator mapIterator)` Gets an immutable version of a `MapIterator`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### EMPTY_ITERATOR

    public static final ResettableIterator EMPTY_ITERATOR

  An iterator over no elements.

  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.

### EMPTY_LIST_ITERATOR

    public static final ResettableListIterator EMPTY_LIST_ITERATOR

  A list iterator over no elements.

  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.

### EMPTY_ORDERED_ITERATOR

    public static final OrderedIterator EMPTY_ORDERED_ITERATOR

  An ordered iterator over no elements.

### EMPTY_MAP_ITERATOR

    public static final MapIterator EMPTY_MAP_ITERATOR

  A map iterator over no elements.

### EMPTY_ORDERED_MAP_ITERATOR

    public static final OrderedMapIterator EMPTY_ORDERED_MAP_ITERATOR

  An ordered map iterator over no elements.

Constructor Detail

### IteratorUtils

    public IteratorUtils()

  IteratorUtils is not normally instantiated.

Method Detail

### emptyIterator

    public static ResettableIterator emptyIterator()

  Gets an empty iterator.

  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.

  Returns:
    an iterator over nothing

### emptyListIterator

    public static ResettableListIterator emptyListIterator()

  Gets an empty list iterator.

  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.

  Returns:
    a list iterator over nothing

### emptyOrderedIterator

    public static OrderedIterator emptyOrderedIterator()

  Gets an empty ordered iterator.

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

  Returns:
    an ordered iterator over nothing

### emptyMapIterator

    public static MapIterator emptyMapIterator()

  Gets an empty map iterator.

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

  Returns:
    a map iterator over nothing

### emptyOrderedMapIterator

    public static OrderedMapIterator emptyOrderedMapIterator()

  Gets an empty ordered map iterator.

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

  Returns:
    a map iterator over nothing

### singletonIterator

    public static ResettableIterator singletonIterator(java.lang.Object object)

  Gets a singleton iterator.

  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
  Returns:
    a singleton iterator over the object

### singletonListIterator

    public static java.util.ListIterator singletonListIterator(java.lang.Object object)

  Gets a singleton list iterator.

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

  Parameters:
    `object` - the single object over which to iterate
  Returns:
    a singleton list iterator over the object

### arrayIterator

    public static ResettableIterator arrayIterator(java.lang.Object[] array)

  Gets an iterator over an object array.

  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
  Returns:
    an iterator over the array
  Throws:
    `java.lang.NullPointerException` - if array is null

### arrayIterator

    public static ResettableIterator arrayIterator(java.lang.Object array)

  Gets an iterator over an object or primitive array.

  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
  Returns:
    an iterator over the array
  Throws:
    `java.lang.IllegalArgumentException` - if the array is not an array
    `java.lang.NullPointerException` - if array is null

### arrayIterator

    public static ResettableIterator arrayIterator(java.lang.Object[] array,
                                                   int start)

  Gets an iterator over the end part of an object array.

  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
    `start` - the index to start iterating at
  Returns:
    an iterator over part of the array
  Throws:
    `java.lang.IndexOutOfBoundsException` - if start is less than zero or greater than the length of the array
    `java.lang.NullPointerException` - if array is null

### arrayIterator

    public static ResettableIterator arrayIterator(java.lang.Object array,
                                                   int start)

  Gets an iterator over the end part of an object or primitive array.

  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
    `start` - the index to start iterating at
  Returns:
    an iterator over part of the array
  Throws:
    `java.lang.IllegalArgumentException` - if the array is not an array
    `java.lang.IndexOutOfBoundsException` - if start is less than zero or greater than the length of the array
    `java.lang.NullPointerException` - if array is null

### arrayIterator

    public static ResettableIterator arrayIterator(java.lang.Object[] array,
                                                   int start,
                                                   int end)

  Gets an iterator over part of an object array.

  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
    `start` - the index to start iterating at
    `end` - the index to finish iterating at
  Returns:
    an iterator over part of the array
  Throws:
    `java.lang.IndexOutOfBoundsException` - if array bounds are invalid
    `java.lang.IllegalArgumentException` - if end is before start
    `java.lang.NullPointerException` - if array is null

### arrayIterator

    public static ResettableIterator arrayIterator(java.lang.Object array,
                                                   int start,
                                                   int end)

  Gets an iterator over part of an object or primitive array.

  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
    `start` - the index to start iterating at
    `end` - the index to finish iterating at
  Returns:
    an iterator over part of the array
  Throws:
    `java.lang.IllegalArgumentException` - if the array is not an array
    `java.lang.IndexOutOfBoundsException` - if array bounds are invalid
    `java.lang.IllegalArgumentException` - if end is before start
    `java.lang.NullPointerException` - if array is null

### arrayListIterator

    public static ResettableListIterator arrayListIterator(java.lang.Object[] array)

  Gets a list iterator over an object array.

  Parameters:
    `array` - the array over which to iterate
  Returns:
    a list iterator over the array
  Throws:
    `java.lang.NullPointerException` - if array is null

### arrayListIterator

    public static ResettableListIterator arrayListIterator(java.lang.Object array)

  Gets a list iterator over an object or primitive array.

  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
  Returns:
    a list iterator over the array
  Throws:
    `java.lang.IllegalArgumentException` - if the array is not an array
    `java.lang.NullPointerException` - if array is null

### arrayListIterator

    public static ResettableListIterator arrayListIterator(java.lang.Object[] array,
                                                           int start)

  Gets a list iterator over the end part of an object array.

  Parameters:
    `array` - the array over which to iterate
    `start` - the index to start iterating at
  Returns:
    a list iterator over part of the array
  Throws:
    `java.lang.IndexOutOfBoundsException` - if start is less than zero
    `java.lang.NullPointerException` - if array is null

### arrayListIterator

    public static ResettableListIterator arrayListIterator(java.lang.Object array,
                                                           int start)

  Gets a list iterator over the end part of an object or primitive array.

  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
    `start` - the index to start iterating at
  Returns:
    a list iterator over part of the array
  Throws:
    `java.lang.IllegalArgumentException` - if the array is not an array
    `java.lang.IndexOutOfBoundsException` - if start is less than zero
    `java.lang.NullPointerException` - if array is null

### arrayListIterator

    public static ResettableListIterator arrayListIterator(java.lang.Object[] array,
                                                           int start,
                                                           int end)

  Gets a list iterator over part of an object array.

  Parameters:
    `array` - the array over which to iterate
    `start` - the index to start iterating at
    `end` - the index to finish iterating at
  Returns:
    a list iterator over part of the array
  Throws:
    `java.lang.IndexOutOfBoundsException` - if array bounds are invalid
    `java.lang.IllegalArgumentException` - if end is before start
    `java.lang.NullPointerException` - if array is null

### arrayListIterator

    public static ResettableListIterator arrayListIterator(java.lang.Object array,
                                                           int start,
                                                           int end)

  Gets a list iterator over part of an object or primitive array.

  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
    `start` - the index to start iterating at
    `end` - the index to finish iterating at
  Returns:
    a list iterator over part of the array
  Throws:
    `java.lang.IllegalArgumentException` - if the array is not an array
    `java.lang.IndexOutOfBoundsException` - if array bounds are invalid
    `java.lang.IllegalArgumentException` - if end is before start
    `java.lang.NullPointerException` - if array is null

### unmodifiableIterator

    public static java.util.Iterator unmodifiableIterator(java.util.Iterator iterator)

  Gets an immutable version of an `Iterator`. The returned object will always throw an `UnsupportedOperationException` for the `Iterator.remove()` method.

  Parameters:
    `iterator` - the iterator to make immutable
  Returns:
    an immutable version of the iterator

### unmodifiableListIterator

    public static java.util.ListIterator unmodifiableListIterator(java.util.ListIterator listIterator)

  Gets an immutable version of a `ListIterator`. The returned object will always throw an `UnsupportedOperationException` for the `Iterator.remove()`, `ListIterator.add(java.lang.Object)` and `ListIterator.set(java.lang.Object)` methods.

  Parameters:
    `listIterator` - the iterator to make immutable
  Returns:
    an immutable version of the iterator

### unmodifiableMapIterator

    public static MapIterator unmodifiableMapIterator(MapIterator mapIterator)

  Gets an immutable version of a `MapIterator`. The returned object will always throw an `UnsupportedOperationException` for the `Iterator.remove()`, `MapIterator.setValue(Object)` methods.

  Parameters:
    `mapIterator` - the iterator to make immutable
  Returns:
    an immutable version of the iterator

### chainedIterator

    public static java.util.Iterator chainedIterator(java.util.Iterator iterator1,
                                                     java.util.Iterator iterator2)

  Gets an iterator that iterates through two `Iterator`s one after another.

  Parameters:
    `iterator1` - the first iterators to use, not null
    `iterator2` - the first iterators to use, not null
  Returns:
    a combination iterator over the iterators
  Throws:
    `java.lang.NullPointerException` - if either iterator is null

### chainedIterator

    public static java.util.Iterator chainedIterator(java.util.Iterator[] iterators)

  Gets an iterator that iterates through an array of `Iterator`s one after another.

  Parameters:
    `iterators` - the iterators to use, not null or empty or contain nulls
  Returns:
    a combination iterator over the iterators
  Throws:
    `java.lang.NullPointerException` - if iterators array is null or contains a null

### chainedIterator

    public static java.util.Iterator chainedIterator(java.util.Collection iterators)

  Gets an iterator that iterates through a collections of `Iterator`s one after another.

  Parameters:
    `iterators` - the iterators to use, not null or empty or contain nulls
  Returns:
    a combination iterator over the iterators
  Throws:
    `java.lang.NullPointerException` - if iterators collection is null or contains a null
    `java.lang.ClassCastException` - if the iterators collection contains the wrong object type

### collatedIterator

    public static java.util.Iterator collatedIterator(java.util.Comparator comparator,
                                                      java.util.Iterator iterator1,
                                                      java.util.Iterator iterator2)

  Gets an iterator that provides an ordered iteration over the elements contained in a collection of ordered `Iterator`s.

  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
    `iterator1` - the first iterators to use, not null
    `iterator2` - the first iterators to use, not null
  Returns:
    a combination iterator over the iterators
  Throws:
    `java.lang.NullPointerException` - if either iterator is null

### collatedIterator

    public static java.util.Iterator collatedIterator(java.util.Comparator comparator,
                                                      java.util.Iterator[] iterators)

  Gets an iterator that provides an ordered iteration over the elements contained in an array of `Iterator`s.

  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
    `iterators` - the iterators to use, not null or empty or contain nulls
  Returns:
    a combination iterator over the iterators
  Throws:
    `java.lang.NullPointerException` - if iterators array is null or contains a null

### collatedIterator

    public static java.util.Iterator collatedIterator(java.util.Comparator comparator,
                                                      java.util.Collection iterators)

  Gets an iterator that provides an ordered iteration over the elements contained in a collection of `Iterator`s.

  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
    `iterators` - the iterators to use, not null or empty or contain nulls
  Returns:
    a combination iterator over the iterators
  Throws:
    `java.lang.NullPointerException` - if iterators collection is null or contains a null
    `java.lang.ClassCastException` - if the iterators collection contains the wrong object type

### objectGraphIterator

    public static java.util.Iterator objectGraphIterator(java.lang.Object root,
                                                         Transformer transformer)

  Gets an iterator that operates over 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.

  Parameters:
    `root` - the root object to start iterating from, null results in an empty iterator
    `transformer` - the transformer to use, see above, null uses no effect transformer
  Returns:
    a new object graph iterator
  Since:
    Commons Collections 3.1

### transformedIterator

    public static java.util.Iterator transformedIterator(java.util.Iterator iterator,
                                                         Transformer transform)

  Gets an iterator that transforms the elements of another iterator.

  The transformation occurs during the next() method and the underlying iterator is unaffected by the transformation.

  Parameters:
    `iterator` - the iterator to use, not null
    `transform` - the transform to use, not null
  Returns:
    a new transforming iterator
  Throws:
    `java.lang.NullPointerException` - if either parameter is null

### filteredIterator

    public static java.util.Iterator filteredIterator(java.util.Iterator iterator,
                                                      Predicate predicate)

  Gets an iterator that filters another iterator.

  The returned iterator will only return objects that match the specified filtering predicate.

  Parameters:
    `iterator` - the iterator to use, not null
    `predicate` - the predicate to use as a filter, not null
  Returns:
    a new filtered iterator
  Throws:
    `java.lang.NullPointerException` - if either parameter is null

### filteredListIterator

    public static java.util.ListIterator filteredListIterator(java.util.ListIterator listIterator,
                                                              Predicate predicate)

  Gets a list iterator that filters another list iterator.

  The returned iterator will only return objects that match the specified filtering predicate.

  Parameters:
    `listIterator` - the list iterator to use, not null
    `predicate` - the predicate to use as a filter, not null
  Returns:
    a new filtered iterator
  Throws:
    `java.lang.NullPointerException` - if either parameter is null

### loopingIterator

    public static ResettableIterator loopingIterator(java.util.Collection coll)

  Gets an iterator that loops continuously over the supplied collection.

  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
  Returns:
    a new looping iterator
  Throws:
    `java.lang.NullPointerException` - if the collection is null

### loopingListIterator

    public static ResettableListIterator loopingListIterator(java.util.List list)

  Gets an iterator that loops continuously over the supplied list.

  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
  Returns:
    a new looping iterator
  Throws:
    `java.lang.NullPointerException` - if the list is null
  Since:
    Commons Collections 3.2

### asIterator

    public static java.util.Iterator asIterator(java.util.Enumeration enumeration)

  Gets an iterator that provides an iterator view of the given enumeration.

  Parameters:
    `enumeration` - the enumeration to use
  Returns:
    a new iterator

### asIterator

    public static java.util.Iterator asIterator(java.util.Enumeration enumeration,
                                                java.util.Collection removeCollection)

  Gets an iterator that provides an iterator view of the given enumeration that will remove elements from the specified collection.

  Parameters:
    `enumeration` - the enumeration to use
    `removeCollection` - the collection to remove elements from
  Returns:
    a new iterator

### asEnumeration

    public static java.util.Enumeration asEnumeration(java.util.Iterator iterator)

  Gets an enumeration that wraps an iterator.

  Parameters:
    `iterator` - the iterator to use, not null
  Returns:
    a new enumeration
  Throws:
    `java.lang.NullPointerException` - if iterator is null

### toListIterator

    public static java.util.ListIterator toListIterator(java.util.Iterator iterator)

  Gets a list iterator based on a simple iterator.

  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
  Returns:
    a new iterator
  Throws:
    `java.lang.NullPointerException` - if iterator parameter is null

### toArray

    public static java.lang.Object[] toArray(java.util.Iterator iterator)

  Gets an array based on an iterator.

  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
  Returns:
    an array of the iterator contents
  Throws:
    `java.lang.NullPointerException` - if iterator parameter is null

### toArray

    public static java.lang.Object[] toArray(java.util.Iterator iterator,
                                             java.lang.Class arrayClass)

  Gets an array based on an iterator.

  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
    `arrayClass` - the class of array to create
  Returns:
    an array of the iterator contents
  Throws:
    `java.lang.NullPointerException` - if iterator parameter is null
    `java.lang.NullPointerException` - if arrayClass is null
    `java.lang.ClassCastException` - if the arrayClass is invalid

### toList

    public static java.util.List toList(java.util.Iterator iterator)

  Gets a list based on an iterator.

  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
  Returns:
    a list of the iterator contents
  Throws:
    `java.lang.NullPointerException` - if iterator parameter is null

### toList

    public static java.util.List toList(java.util.Iterator iterator,
                                        int estimatedSize)

  Gets a list based on an iterator.

  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
    `estimatedSize` - the initial size of the ArrayList
  Returns:
    a list of the iterator contents
  Throws:
    `java.lang.NullPointerException` - if iterator parameter is null
    `java.lang.IllegalArgumentException` - if the size is less than 1

### getIterator

    public static java.util.Iterator getIterator(java.lang.Object obj)

  Gets a suitable Iterator for the given object.

  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

  Parameters:
    `obj` - the object to convert to an iterator
  Returns:
    a suitable iterator, never null

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.