public class IteratorUtils extends Object
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.
Modifier and Type | Field and Description |
---|---|
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 and Description |
---|
IteratorUtils()
IteratorUtils is not normally instantiated.
|
Modifier and Type | Method and Description |
---|---|
static ResettableIterator |
arrayIterator(Object array)
Gets an iterator over an object or primitive array.
|
static ResettableIterator |
arrayIterator(Object[] array)
Gets an iterator over an object array.
|
static ResettableIterator |
arrayIterator(Object[] array,
int start)
Gets an iterator over the end part of an object array.
|
static ResettableIterator |
arrayIterator(Object[] array,
int start,
int end)
Gets an iterator over part of an object array.
|
static ResettableIterator |
arrayIterator(Object array,
int start)
Gets an iterator over the end part of an object or primitive array.
|
static ResettableIterator |
arrayIterator(Object array,
int start,
int end)
Gets an iterator over part of an object or primitive array.
|
static ResettableListIterator |
arrayListIterator(Object array)
Gets a list iterator over an object or primitive array.
|
static ResettableListIterator |
arrayListIterator(Object[] array)
Gets a list iterator over an object array.
|
static ResettableListIterator |
arrayListIterator(Object[] array,
int start)
Gets a list iterator over the end part of an object array.
|
static ResettableListIterator |
arrayListIterator(Object[] array,
int start,
int end)
Gets a list iterator over part of an object array.
|
static ResettableListIterator |
arrayListIterator(Object array,
int start)
Gets a list iterator over the end part of an object or primitive array.
|
static ResettableListIterator |
arrayListIterator(Object array,
int start,
int end)
Gets a list iterator over part of an object or primitive array.
|
static Enumeration |
asEnumeration(Iterator iterator)
Gets an enumeration that wraps an iterator.
|
static Iterator |
asIterator(Enumeration enumeration)
Gets an iterator that provides an iterator view of the given enumeration.
|
static Iterator |
asIterator(Enumeration enumeration,
Collection removeCollection)
Gets an iterator that provides an iterator view of the given enumeration
that will remove elements from the specified collection.
|
static Iterator |
chainedIterator(Collection iterators)
Gets an iterator that iterates through a collections of
Iterator s
one after another. |
static Iterator |
chainedIterator(Iterator[] iterators)
Gets an iterator that iterates through an array of
Iterator s
one after another. |
static Iterator |
chainedIterator(Iterator iterator1,
Iterator iterator2)
Gets an iterator that iterates through two
Iterator s
one after another. |
static Iterator |
collatedIterator(Comparator comparator,
Collection iterators)
Gets an iterator that provides an ordered iteration over the elements
contained in a collection of
Iterator s. |
static Iterator |
collatedIterator(Comparator comparator,
Iterator[] iterators)
Gets an iterator that provides an ordered iteration over the elements
contained in an array of
Iterator s. |
static Iterator |
collatedIterator(Comparator comparator,
Iterator iterator1,
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 Iterator |
filteredIterator(Iterator iterator,
Predicate predicate)
Gets an iterator that filters another iterator.
|
static ListIterator |
filteredListIterator(ListIterator listIterator,
Predicate predicate)
Gets a list iterator that filters another list iterator.
|
static Iterator |
getIterator(Object obj)
Gets a suitable Iterator for the given object.
|
static ResettableIterator |
loopingIterator(Collection coll)
Gets an iterator that loops continuously over the supplied collection.
|
static ResettableListIterator |
loopingListIterator(List list)
Gets an iterator that loops continuously over the supplied list.
|
static Iterator |
objectGraphIterator(Object root,
Transformer transformer)
Gets an iterator that operates over an object graph.
|
static ResettableIterator |
singletonIterator(Object object)
Gets a singleton iterator.
|
static ListIterator |
singletonListIterator(Object object)
Gets a singleton list iterator.
|
static Object[] |
toArray(Iterator iterator)
Gets an array based on an iterator.
|
static Object[] |
toArray(Iterator iterator,
Class arrayClass)
Gets an array based on an iterator.
|
static List |
toList(Iterator iterator)
Gets a list based on an iterator.
|
static List |
toList(Iterator iterator,
int estimatedSize)
Gets a list based on an iterator.
|
static ListIterator |
toListIterator(Iterator iterator)
Gets a list iterator based on a simple iterator.
|
static Iterator |
transformedIterator(Iterator iterator,
Transformer transform)
Gets an iterator that transforms the elements of another iterator.
|
static Iterator |
unmodifiableIterator(Iterator iterator)
Gets an immutable version of an
Iterator . |
static ListIterator |
unmodifiableListIterator(ListIterator listIterator)
Gets an immutable version of a
ListIterator . |
static MapIterator |
unmodifiableMapIterator(MapIterator mapIterator)
Gets an immutable version of a
MapIterator . |
public static final ResettableIterator EMPTY_ITERATOR
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.
public static final ResettableListIterator EMPTY_LIST_ITERATOR
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.
public static final OrderedIterator EMPTY_ORDERED_ITERATOR
public static final MapIterator EMPTY_MAP_ITERATOR
public static final OrderedMapIterator EMPTY_ORDERED_MAP_ITERATOR
public static ResettableIterator emptyIterator()
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.
public static ResettableListIterator emptyListIterator()
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.
public static OrderedIterator emptyOrderedIterator()
This iterator is a valid iterator object that will iterate over nothing.
public static MapIterator emptyMapIterator()
This iterator is a valid map iterator object that will iterate over nothing.
public static OrderedMapIterator emptyOrderedMapIterator()
This iterator is a valid map iterator object that will iterate over nothing.
public static ResettableIterator singletonIterator(Object object)
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.
object
- the single object over which to iteratepublic static ListIterator singletonListIterator(Object object)
This iterator is a valid list iterator object that will iterate over the specified object.
object
- the single object over which to iteratepublic static ResettableIterator arrayIterator(Object[] array)
WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use new ArrayIterator(array)
for compatability.
array
- the array over which to iterateNullPointerException
- if array is nullpublic static ResettableIterator arrayIterator(Object array)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
array
- the array over which to iterateIllegalArgumentException
- if the array is not an arrayNullPointerException
- if array is nullpublic static ResettableIterator arrayIterator(Object[] array, int start)
WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use new ArrayIterator(array,start)
for compatability.
array
- the array over which to iteratestart
- the index to start iterating atIndexOutOfBoundsException
- if start is less than zero or greater
than the length of the arrayNullPointerException
- if array is nullpublic static ResettableIterator arrayIterator(Object array, int start)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
array
- the array over which to iteratestart
- the index to start iterating atIllegalArgumentException
- if the array is not an arrayIndexOutOfBoundsException
- if start is less than zero or greater
than the length of the arrayNullPointerException
- if array is nullpublic static ResettableIterator arrayIterator(Object[] array, int start, int end)
WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use new ArrayIterator(array,start,end)
for compatability.
array
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating atIndexOutOfBoundsException
- if array bounds are invalidIllegalArgumentException
- if end is before startNullPointerException
- if array is nullpublic static ResettableIterator arrayIterator(Object array, int start, int end)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
array
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating atIllegalArgumentException
- if the array is not an arrayIndexOutOfBoundsException
- if array bounds are invalidIllegalArgumentException
- if end is before startNullPointerException
- if array is nullpublic static ResettableListIterator arrayListIterator(Object[] array)
array
- the array over which to iterateNullPointerException
- if array is nullpublic static ResettableListIterator arrayListIterator(Object array)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
array
- the array over which to iterateIllegalArgumentException
- if the array is not an arrayNullPointerException
- if array is nullpublic static ResettableListIterator arrayListIterator(Object[] array, int start)
array
- the array over which to iteratestart
- the index to start iterating atIndexOutOfBoundsException
- if start is less than zeroNullPointerException
- if array is nullpublic static ResettableListIterator arrayListIterator(Object array, int start)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
array
- the array over which to iteratestart
- the index to start iterating atIllegalArgumentException
- if the array is not an arrayIndexOutOfBoundsException
- if start is less than zeroNullPointerException
- if array is nullpublic static ResettableListIterator arrayListIterator(Object[] array, int start, int end)
array
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating atIndexOutOfBoundsException
- if array bounds are invalidIllegalArgumentException
- if end is before startNullPointerException
- if array is nullpublic static ResettableListIterator arrayListIterator(Object array, int start, int end)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
array
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating atIllegalArgumentException
- if the array is not an arrayIndexOutOfBoundsException
- if array bounds are invalidIllegalArgumentException
- if end is before startNullPointerException
- if array is nullpublic static Iterator unmodifiableIterator(Iterator iterator)
Iterator
. The returned object
will always throw an UnsupportedOperationException
for
the Iterator.remove()
method.iterator
- the iterator to make immutablepublic static ListIterator unmodifiableListIterator(ListIterator listIterator)
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.listIterator
- the iterator to make immutablepublic static MapIterator unmodifiableMapIterator(MapIterator mapIterator)
MapIterator
. The returned object
will always throw an UnsupportedOperationException
for
the Iterator.remove()
, MapIterator.setValue(Object)
methods.mapIterator
- the iterator to make immutablepublic static Iterator chainedIterator(Iterator iterator1, Iterator iterator2)
Iterator
s
one after another.iterator1
- the first iterators to use, not nulliterator2
- the first iterators to use, not nullNullPointerException
- if either iterator is nullpublic static Iterator chainedIterator(Iterator[] iterators)
Iterator
s
one after another.iterators
- the iterators to use, not null or empty or contain nullsNullPointerException
- if iterators array is null or contains a nullpublic static Iterator chainedIterator(Collection iterators)
Iterator
s
one after another.iterators
- the iterators to use, not null or empty or contain nullsNullPointerException
- if iterators collection is null or contains a nullClassCastException
- if the iterators collection contains the wrong object typepublic static Iterator collatedIterator(Comparator comparator, Iterator iterator1, Iterator iterator2)
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.
comparator
- the comparator to use, may be null for natural orderiterator1
- the first iterators to use, not nulliterator2
- the first iterators to use, not nullNullPointerException
- if either iterator is nullpublic static Iterator collatedIterator(Comparator comparator, Iterator[] iterators)
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.
comparator
- the comparator to use, may be null for natural orderiterators
- the iterators to use, not null or empty or contain nullsNullPointerException
- if iterators array is null or contains a nullpublic static Iterator collatedIterator(Comparator comparator, Collection iterators)
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.
comparator
- the comparator to use, may be null for natural orderiterators
- the iterators to use, not null or empty or contain nullsNullPointerException
- if iterators collection is null or contains a nullClassCastException
- if the iterators collection contains the wrong object typepublic static Iterator objectGraphIterator(Object root, Transformer transformer)
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 -- LeafThe 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.
root
- the root object to start iterating from, null results in an empty iteratortransformer
- the transformer to use, see above, null uses no effect transformerpublic static Iterator transformedIterator(Iterator iterator, Transformer transform)
The transformation occurs during the next() method and the underlying iterator is unaffected by the transformation.
iterator
- the iterator to use, not nulltransform
- the transform to use, not nullNullPointerException
- if either parameter is nullpublic static Iterator filteredIterator(Iterator iterator, Predicate predicate)
The returned iterator will only return objects that match the specified filtering predicate.
iterator
- the iterator to use, not nullpredicate
- the predicate to use as a filter, not nullNullPointerException
- if either parameter is nullpublic static ListIterator filteredListIterator(ListIterator listIterator, Predicate predicate)
The returned iterator will only return objects that match the specified filtering predicate.
listIterator
- the list iterator to use, not nullpredicate
- the predicate to use as a filter, not nullNullPointerException
- if either parameter is nullpublic static ResettableIterator loopingIterator(Collection coll)
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.
coll
- the collection to iterate over, not nullNullPointerException
- if the collection is nullpublic static ResettableListIterator loopingListIterator(List 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.
list
- the list to iterate over, not nullNullPointerException
- if the list is nullpublic static Iterator asIterator(Enumeration enumeration)
enumeration
- the enumeration to usepublic static Iterator asIterator(Enumeration enumeration, Collection removeCollection)
enumeration
- the enumeration to useremoveCollection
- the collection to remove elements frompublic static Enumeration asEnumeration(Iterator iterator)
iterator
- the iterator to use, not nullNullPointerException
- if iterator is nullpublic static ListIterator toListIterator(Iterator iterator)
As the wrapped Iterator is traversed, a LinkedList of its values is cached, permitting all required operations of ListIterator.
iterator
- the iterator to use, not nullNullPointerException
- if iterator parameter is nullpublic static Object[] toArray(Iterator iterator)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.
iterator
- the iterator to use, not nullNullPointerException
- if iterator parameter is nullpublic static Object[] toArray(Iterator iterator, Class arrayClass)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.
iterator
- the iterator to use, not nullarrayClass
- the class of array to createNullPointerException
- if iterator parameter is nullNullPointerException
- if arrayClass is nullClassCastException
- if the arrayClass is invalidpublic static List toList(Iterator iterator)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.
iterator
- the iterator to use, not nullNullPointerException
- if iterator parameter is nullpublic static List toList(Iterator iterator, int estimatedSize)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.
iterator
- the iterator to use, not nullestimatedSize
- the initial size of the ArrayListNullPointerException
- if iterator parameter is nullIllegalArgumentException
- if the size is less than 1public static Iterator getIterator(Object obj)
This method can handles objects as follows
obj
- the object to convert to an iteratorCopyright © 2001–2015 The Apache Software Foundation. All rights reserved.