* The iterator implements a {@link #reset} method, allowing the reset of * the iterator back to the start if required. + *
* * @param* This iterator does not support {@link #add(Object)} or {@link #remove()}, as the array * cannot be changed in size. The {@link #set(Object)} method is supported however. + *
* * @param* This method sets the element that was returned by the last call * to {@link #next()} of {@link #previous()}. + *
*
* Note: {@link java.util.ListIterator} implementations that support
* {@code add()} and {@code remove()} only allow {@code set()} to be called
@@ -189,6 +190,7 @@ public class ArrayListIterator
* In case an offset parameter other than 0 is provided, the decorated * iterator is immediately advanced to this position, skipping all elements * before that position. + *
* * @param* The iterator is immediately advanced until it reaches the position at {@code offset}, * incurring O(n) time. + *
* * @param iterator the iterator to be decorated * @param offset the index of the first element of the decorated iterator to return @@ -123,6 +126,7 @@ public class BoundedIterator* This iterator decorates the underlying iterator, only allowing through * those elements that match the specified {@link Predicate Predicate}. + *
* * @param* This iterator decorates the underlying iterator, only allowing through * those elements that match the specified {@link Predicate Predicate}. + *
* * @param* Under many circumstances, linking Iterators together in this manner is more * efficient (and convenient) than reading out the contents of each Iterator * into a List and creating a new Iterator. + *
** Calling a method that adds new Iterator after a method in the Iterator * interface has been called will result in an UnsupportedOperationException. + *
** NOTE: As from version 3.0, the IteratorChain may contain no iterators. In * this case the class will function as an empty iterator. + *
** NOTE: As from version 4.0, the IteratorChain stores the iterators in a queue * and removes any reference to them as soon as they are not used anymore. Thus, * the methods {@code setIterator(Iterator)} and {@code getIterators()} have been * removed and {@link #size()} will return the number of remaining iterators in * the queue. + *
* * @param* You will normally use {@link #addIterator(Iterator)} to add some * iterators after using this constructor. + *
*/ public IteratorChain() { } @@ -84,6 +90,7 @@ public class IteratorChain* This method takes a collection of iterators. The newly constructed * iterator will iterate through each one of the input iterators in turn. + *
* * @param iteratorChain the collection of iterators, not null * @throws NullPointerException if iterators collection is or contains null @@ -102,9 +109,11 @@ public class IteratorChain* You will normally use {@link #addIterator(Iterator)} to add some more * iterators after using this constructor. + *
* * @param iterator the first child iterator in the IteratorChain, not null * @throws NullPointerException if the iterator is null @@ -118,6 +127,7 @@ public class IteratorChain* This method takes an array of iterators. The newly constructed iterator * will iterate through each one of the input iterators in turn. + *
* * @param iteratorChain the array of iterators, not null * @throws NullPointerException if iterators array is or contains null @@ -133,6 +143,7 @@ public class IteratorChain* This method takes two iterators. The newly constructed iterator will * iterate through each one of the input iterators in turn. + *
* * @param first the first child iterator in the IteratorChain, not null * @param second the second child iterator in the IteratorChain, not null diff --git a/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java b/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java index 7c686534f..4e8a3075b 100644 --- a/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java +++ b/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java @@ -25,9 +25,11 @@ import java.util.Iterator; * method from the Iterator interface is called, the LazyIteratorChain will delegate * to a single underlying Iterator. The LazyIteratorChain will invoke the Iterators * in sequence until all Iterators are exhausted. + * ** The Iterators are provided by {@link #nextIterator(int)} which has to be overridden by * subclasses and allows to lazily create the Iterators as they are accessed: + *
*
* return new LazyIteratorChain<String>() {
* protected Iterator<String> nextIterator(int count) {
@@ -39,9 +41,11 @@ import java.util.Iterator;
* Once the inner Iterator's {@link Iterator#hasNext()} method returns false,
* {@link #nextIterator(int)} will be called to obtain another iterator, and so on
* until {@link #nextIterator(int)} returns null, indicating that the chain is exhausted.
+ *
*
* NOTE: The LazyIteratorChain may contain no iterators. In this case the class will
* function as an empty iterator.
+ *
*
* @param the type of elements in this iterator.
* @since 4.0
@@ -94,6 +98,7 @@ public abstract class LazyIteratorChain implements Iterator {
* Gets the next iterator after the previous one has been exhausted.
*
* This method MUST return null when there are no more iterators.
+ *
*
* @param count the number of time this method has been called (starts with 1)
* @return the next iterator, or null if there are no more.
@@ -106,6 +111,7 @@ public abstract class LazyIteratorChain implements Iterator {
* As with next() and hasNext(), this method calls remove() on the underlying Iterator.
* Therefore, this method may throw an UnsupportedOperationException if the underlying
* Iterator does not support this method.
+ *
*
* @throws UnsupportedOperationException if the remove operator is not
* supported by the underlying Iterator
diff --git a/src/main/java/org/apache/commons/collections4/iterators/ListIteratorWrapper.java b/src/main/java/org/apache/commons/collections4/iterators/ListIteratorWrapper.java
index ec77677dd..3c5ae6235 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/ListIteratorWrapper.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/ListIteratorWrapper.java
@@ -38,10 +38,13 @@ import org.apache.commons.collections4.ResettableListIterator;
* This class allows a regular {@code Iterator} to behave as a
* {@code ListIterator}. It achieves this by building a list internally
* of as the underlying iterator is traversed.
+ *
*
* The optional operations of {@code ListIterator} are not supported for plain {@code Iterator}s.
+ *
*
* This class implements ResettableListIterator from Commons Collections 3.2.
+ *
*
* @param the type of elements in this iterator.
* @since 2.1
diff --git a/src/main/java/org/apache/commons/collections4/iterators/LoopingIterator.java b/src/main/java/org/apache/commons/collections4/iterators/LoopingIterator.java
index ac62a1ce8..65bbe98e5 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/LoopingIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/LoopingIterator.java
@@ -29,9 +29,11 @@ import org.apache.commons.collections4.ResettableIterator;
* The iterator will loop continuously around the provided elements, unless
* there are no elements in the collection to begin with, or all the elements
* have been {@link #remove removed}.
+ *
*
* Concurrent modifications are not directly supported, and for most collection
* implementations will throw a ConcurrentModificationException.
+ *
*
* @param the type of elements returned by this iterator.
* @since 3.0
@@ -48,6 +50,7 @@ public class LoopingIterator implements ResettableIterator {
*
* There is no way to reset an Iterator instance without recreating it from
* the original source, so the Collection must be passed in.
+ *
*
* @param collection the collection to wrap
* @throws NullPointerException if the collection is null
@@ -62,6 +65,7 @@ public class LoopingIterator implements ResettableIterator {
*
* Returns false only if the collection originally had zero elements, or
* all the elements have been {@link #remove removed}.
+ *
*
* @return {@code true} if there are more elements
*/
@@ -74,6 +78,7 @@ public class LoopingIterator implements ResettableIterator {
* Returns the next object in the collection.
*
* If at the end of the collection, return the first element.
+ *
*
* @return the next object
* @throws NoSuchElementException if there are no elements
@@ -96,11 +101,13 @@ public class LoopingIterator implements ResettableIterator {
* This feature is only supported if the underlying collection's
* {@link Collection#iterator()} method returns an implementation
* that supports it.
+ *
*
* This method can only be called after at least one {@link #next} method call.
* After a removal, the remove method may not be called again until another
* next has been performed. If the {@link #reset} is called, then remove may
* not be called until {@link #next} is called again.
+ *
*/
@Override
public void remove() {
diff --git a/src/main/java/org/apache/commons/collections4/iterators/LoopingListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/LoopingListIterator.java
index 0282fb2ac..c0defe371 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/LoopingListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/LoopingListIterator.java
@@ -30,10 +30,12 @@ import org.apache.commons.collections4.ResettableListIterator;
* The iterator will loop continuously around the provided list,
* unless there are no elements in the collection to begin with, or
* all of the elements have been {@link #remove removed}.
+ *
*
* Concurrent modifications are not directly supported, and for most
* collection implementations will throw a
* ConcurrentModificationException.
+ *
*
* @param the type of elements returned by this iterator.
* @since 3.2
@@ -51,6 +53,7 @@ public class LoopingListIterator implements ResettableListIterator {
* There is no way to reset a ListIterator instance without
* recreating it from the original source, so the List must be
* passed in and a reference to it held.
+ *
*
* @param list the list to wrap
* @throws NullPointerException if the list is null
@@ -66,10 +69,12 @@ public class LoopingListIterator implements ResettableListIterator {
* The element is inserted before the next element that would be
* returned by {@link #next}, if any, and after the next element
* that would be returned by {@link #previous}, if any.
+ *
*
* This feature is only supported if the underlying list's
* {@link List#listIterator} method returns an implementation
* that supports it.
+ *
*
* @param obj the element to insert
* @throws UnsupportedOperationException if the add method is not
@@ -85,6 +90,7 @@ public class LoopingListIterator implements ResettableListIterator {
*
* Returns false only if the list originally had zero elements, or
* all elements have been {@link #remove removed}.
+ *
*
* @return {@code true} if there are more elements
*/
@@ -98,6 +104,7 @@ public class LoopingListIterator implements ResettableListIterator {
*
* Returns false only if the list originally had zero elements, or
* all elements have been {@link #remove removed}.
+ *
*
* @return {@code true} if there are more elements
*/
@@ -114,6 +121,7 @@ public class LoopingListIterator implements ResettableListIterator {
* Returns the next object in the list.
*
* If at the end of the list, returns the first element.
+ *
*
* @return the object after the last element returned
* @throws NoSuchElementException if there are no elements in the list
@@ -137,6 +145,7 @@ public class LoopingListIterator implements ResettableListIterator {
* As would be expected, if the iterator is at the physical end of
* the underlying list, 0 is returned, signifying the beginning of
* the list.
+ *
*
* @return the index of the element that would be returned if next() were called
* @throws NoSuchElementException if there are no elements in the list
@@ -158,6 +167,7 @@ public class LoopingListIterator implements ResettableListIterator {
*
* If at the beginning of the list, return the last element. Note
* that in this case, traversal to find that element takes linear time.
+ *
*
* @return the object before the last element returned
* @throws NoSuchElementException if there are no elements in the list
@@ -186,6 +196,7 @@ public class LoopingListIterator implements ResettableListIterator {
* As would be expected, if at the iterator is at the physical
* beginning of the underlying list, the list's size minus one is
* returned, signifying the end of the list.
+ *
*
* @return the index of the element that would be returned if previous() were called
* @throws NoSuchElementException if there are no elements in the list
@@ -208,6 +219,7 @@ public class LoopingListIterator implements ResettableListIterator {
* This feature is only supported if the underlying list's
* {@link List#iterator()} method returns an implementation
* that supports it.
+ *
*
* This method can only be called after at least one {@link #next}
* or {@link #previous} method call. After a removal, the remove
@@ -215,6 +227,7 @@ public class LoopingListIterator implements ResettableListIterator {
* {@link #previous} has been performed. If the {@link #reset} is
* called, then remove may not be called until {@link #next} or
* {@link #previous} is called again.
+ *
*
* @throws UnsupportedOperationException if the remove method is
* not supported by the iterator implementation of the underlying
@@ -240,6 +253,7 @@ public class LoopingListIterator implements ResettableListIterator {
* This feature is only supported if the underlying list's
* {@link List#listIterator} method returns an implementation
* that supports it.
+ *
*
* @param obj the element with which to replace the last element returned
* @throws UnsupportedOperationException if the set method is not
diff --git a/src/main/java/org/apache/commons/collections4/iterators/NodeListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/NodeListIterator.java
index 56495e379..01f4c3d11 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/NodeListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/NodeListIterator.java
@@ -28,6 +28,7 @@ import org.w3c.dom.NodeList;
*
* This iterator does not support {@link #remove()} as a {@link NodeList} does not support
* removal of items.
+ *
*
* @since 4.0
* @see NodeList
diff --git a/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayIterator.java b/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayIterator.java
index 3a8b324a3..c0178d0a9 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayIterator.java
@@ -25,9 +25,11 @@ import org.apache.commons.collections4.ResettableIterator;
*
* This iterator does not support {@link #remove}, as the object array cannot be
* structurally modified.
+ *
*
* The iterator implements a {@link #reset} method, allowing the reset of the iterator
* back to the start if required.
+ *
*
* @param the type of elements returned by this iterator.
* @since 3.0
diff --git a/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java
index 0ce40da9b..06851a176 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java
@@ -25,9 +25,11 @@ import org.apache.commons.collections4.ResettableListIterator;
*
* This iterator does not support {@link #add} or {@link #remove}, as the object array
* cannot be structurally modified. The {@link #set} method is supported however.
+ *
*
* The iterator implements a {@link #reset} method, allowing the reset of the iterator
* back to the start if required.
+ *
*
* @param the type of elements returned by this iterator.
* @see org.apache.commons.collections4.iterators.ObjectArrayIterator
@@ -172,13 +174,15 @@ public class ObjectArrayListIterator extends ObjectArrayIterator
*
* This method sets the element that was returned by the last call
* to {@link #next()} of {@link #previous()}.
- *
+ *
+ *
* Note: {@link java.util.ListIterator} implementations that support {@code add()}
* and {@code remove()} only allow {@code set()} to be called once per call
* to {@code next()} or {@code previous} (see the {@link java.util.ListIterator}
* Javadoc for more details). Since this implementation does not support
* {@code add()} or {@code remove()}, {@code set()} may be
* called as often as desired.
+ *
*
* @param obj the object to set into the array
* @throws IllegalStateException if next() has not yet been called.
diff --git a/src/main/java/org/apache/commons/collections4/iterators/ObjectGraphIterator.java b/src/main/java/org/apache/commons/collections4/iterators/ObjectGraphIterator.java
index b094b4b47..6ccadaf38 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/ObjectGraphIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/ObjectGraphIterator.java
@@ -30,8 +30,10 @@ import org.apache.commons.collections4.Transformer;
* The iteration starts from a single root object.
* It uses a {@code Transformer} to extract the iterators and elements.
* Its main benefit is that no intermediate {@code List} is created.
+ *
*
* For example, consider an object graph:
+ *
*
* |- Branch -- Leaf
* | \- Leaf
@@ -43,8 +45,10 @@ import org.apache.commons.collections4.Transformer;
* |- Tree | /- Leaf
* |- Branch -- Leaf
* |- Branch -- Leaf
+ *
* The following {@code 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) {
@@ -67,9 +71,11 @@ import org.apache.commons.collections4.Transformer;
* 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.
+ *
*
* @param the type of elements returned by this iterator.
* @since 3.1
@@ -118,6 +124,7 @@ public class ObjectGraphIterator implements Iterator {
* be used to iterate over nested iterators. That is to say that the iterator
* passed in here contains other iterators, which may in turn contain further
* iterators.
+ *
*
* @param rootIterator the root iterator, null will result in an empty iterator
*/
@@ -208,6 +215,7 @@ public class ObjectGraphIterator implements Iterator {
* This method calls remove() on the underlying Iterator, and it may
* throw an UnsupportedOperationException if the underlying Iterator
* does not support this method.
+ *
*
* @throws UnsupportedOperationException
* if the remove operator is not supported by the underlying Iterator
diff --git a/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java b/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
index 4f8d407c4..e8e3c381b 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
@@ -26,6 +26,7 @@ import java.util.Objects;
* The decorator supports the removal operation, but an {@link IllegalStateException}
* will be thrown if {@link #remove()} is called directly after a call to
* {@link #peek()} or {@link #element()}.
+ *
*
* @param the type of elements returned by this iterator.
* @since 4.0
@@ -36,6 +37,7 @@ public class PeekingIterator implements Iterator {
* Decorates the specified iterator to support one-element lookahead.
*
* If the iterator is already a {@link PeekingIterator} it is returned directly.
+ *
*
* @param the element type
* @param iterator the iterator to decorate
@@ -128,9 +130,11 @@ public class PeekingIterator implements Iterator {
*
* Note: this method does not throw a {@link NoSuchElementException} if the iterator
* is already exhausted. If you want such a behavior, use {@link #element()} instead.
+ *
*
* The rationale behind this is to follow the {@link java.util.Queue} interface
* which uses the same terminology.
+ *
*
* @return the next element from the iterator
*/
diff --git a/src/main/java/org/apache/commons/collections4/iterators/PermutationIterator.java b/src/main/java/org/apache/commons/collections4/iterators/PermutationIterator.java
index 449b110df..ef1f9b286 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/PermutationIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/PermutationIterator.java
@@ -33,9 +33,11 @@ import java.util.Objects;
* The iterator will return exactly n! permutations of the input collection.
* The {@code remove()} operation is not supported, and will throw an
* {@code UnsupportedOperationException}.
+ *
*
* NOTE: in case an empty collection is provided, the iterator will
* return exactly one empty list as result, as 0! = 1.
+ *
*
* @param the type of the objects being permuted
*
diff --git a/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java b/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java
index 9e225f6db..340e793b2 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java
@@ -26,9 +26,11 @@ import java.util.Objects;
*
* The decorator stores the pushed back elements in a LIFO manner: the last element
* that has been pushed back, will be returned as the next element in a call to {@link #next()}.
+ *
*
* The decorator does not support the removal operation. Any call to {@link #remove()} will
* result in an {@link UnsupportedOperationException}.
+ *
*
* @param the type of elements returned by this iterator.
* @since 4.0
@@ -39,6 +41,7 @@ public class PushbackIterator implements Iterator {
* Decorates the specified iterator to support one-element lookahead.
*
* If the iterator is already a {@link PushbackIterator} it is returned directly.
+ *
*
* @param the element type
* @param iterator the iterator to decorate
@@ -84,6 +87,7 @@ public class PushbackIterator implements Iterator {
* Push back the given element to the iterator.
*
* Calling {@link #next()} immediately afterwards will return exactly this element.
+ *
*
* @param item the element to push back to the iterator
*/
diff --git a/src/main/java/org/apache/commons/collections4/iterators/ReverseListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/ReverseListIterator.java
index 9fbd7a13a..48b4dd6ff 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/ReverseListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/ReverseListIterator.java
@@ -33,6 +33,7 @@ import org.apache.commons.collections4.ResettableListIterator;
* However, the {@code nextIndex()} method returns the correct
* index in the list, thus it starts high and reduces as the iteration
* continues. The previous methods work similarly.
+ *
*
* @param the type of elements returned by this iterator.
* @since 3.2