commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections/iterators CollatingIterator.java EnumerationIterator.java ArrayListIterator.java ArrayIterator.java
Date Mon, 29 Sep 2003 22:37:41 GMT
scolebourne    2003/09/29 15:37:41

  Modified:    collections/src/java/org/apache/commons/collections/iterators
                        CollatingIterator.java EnumerationIterator.java
                        ArrayListIterator.java ArrayIterator.java
  Log:
  Javadoc and Code tidy
  
  Revision  Changes    Path
  1.9       +90 -92    jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
  
  Index: CollatingIterator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/CollatingIterator.java,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- CollatingIterator.java	29 Sep 2003 22:02:33 -0000	1.8
  +++ CollatingIterator.java	29 Sep 2003 22:37:40 -0000	1.9
  @@ -68,9 +68,10 @@
   
   /**
    * Provides an ordered iteration over the elements contained in
  - * a collection of ordered {@link Iterator}s.  In other words,
  - * given two ordered {@link Iterator}s <code>A</code> and <code>B</code>,
  - * my {@link #next} method will return the lesser of 
  + * a collection of ordered {@link Iterator}s.
  + * <p>
  + * Given two ordered {@link Iterator}s <code>A</code> and <code>B</code>,
  + * the {@link #next} method on this iterator will return the lesser of 
    * <code>A.next()</code> and <code>B.next()</code>.
    *
    * @since Commons Collections 2.1
  @@ -81,10 +82,10 @@
    */
   public class CollatingIterator implements Iterator {
   
  -    /** My {@link Comparator}. */
  +    /** The {@link Comparator} used to evaluate order. */
       private Comparator comparator = null;
   
  -    /** My list of {@link Iterator}s. */
  +    /** The list of {@link Iterator}s to evaluate. */
       private ArrayList iterators = null;
      
       /** {@link Iterator#next Next} objects peeked from each iterator. */
  @@ -97,8 +98,7 @@
       private int lastReturned = -1;
   
       // Constructors
  -    // -------------------------------------------------------------------
  -    
  +    // ----------------------------------------------------------------------
       /**
        * Constructs a new <code>CollatingIterator</code>.  Natural sort order
        * will be used, and child iterators will have to be manually added 
  @@ -113,10 +113,9 @@
        * specified comparator for ordering.  Child iterators will have to be 
        * manually added using the {@link #addIterator(Iterator)} method.
        *
  -     * @param comp  the comparator to use for ordering, or <code>null</code>
  -     *    to use natural sort order
  +     * @param comp  the comparator to use to sort, or null to use natural sort order
        */
  -    public CollatingIterator(Comparator comp) {
  +    public CollatingIterator(final Comparator comp) {
           this(comp,2);
       }
       
  @@ -126,12 +125,11 @@
        * capacity.  Child iterators will have to be 
        * manually added using the {@link #addIterator(Iterator)} method.
        *
  -     * @param comp  the comparator to use for ordering, or <code>null</code>
  -     *    to use natural sort order
  +     * @param comp  the comparator to use to sort, or null to use natural sort order
        * @param initIterCapacity  the initial capacity for the internal list
        *    of child iterators
        */
  -    public CollatingIterator(Comparator comp, int initIterCapacity) {
  +    public CollatingIterator(final Comparator comp, final int initIterCapacity) {
           iterators = new ArrayList(initIterCapacity);
           setComparator(comp);
       }
  @@ -141,13 +139,12 @@
        * specified comparator to provide ordered iteration over the two
        * given iterators.
        *
  -     * @param comp  the comparator to use to sort, or null to use natural
  -     *    sort order
  +     * @param comp  the comparator to use to sort, or null to use natural sort order
        * @param a  the first child ordered iterator
        * @param b  the second child ordered iterator
        * @throws NullPointerException if either iterator is null
        */
  -    public CollatingIterator(Comparator comp, Iterator a, Iterator b) {
  +    public CollatingIterator(final Comparator comp, final Iterator a, final Iterator b)
{
           this(comp,2);
           addIterator(a);
           addIterator(b);
  @@ -158,12 +155,11 @@
        * specified comparator to provide ordered iteration over the array
        * of iterators.
        *
  -     * @param comp  the comparator to use to sort, or null to use natural
  -     *    sort order
  +     * @param comp  the comparator to use to sort, or null to use natural sort order
        * @param iterators  the array of iterators
        * @throws NullPointerException if iterators array is or contains null
        */
  -    public CollatingIterator(Comparator comp, Iterator[] iterators) {
  +    public CollatingIterator(final Comparator comp, final Iterator[] iterators) {
           this(comp, iterators.length);
           for (int i = 0; i < iterators.length; i++) {
               addIterator(iterators[i]);
  @@ -175,14 +171,13 @@
        * specified comparator to provide ordered iteration over the collection
        * of iterators.
        *
  -     * @param comp  the comparator to use to sort, or null to use natural
  -     *    sort order
  +     * @param comp  the comparator to use to sort, or null to use natural sort order
        * @param iterators  the collection of iterators
        * @throws NullPointerException if the iterators collection is or contains null
        * @throws ClassCastException if the iterators collection contains an
        *         element that's not an {@link Iterator}
        */
  -    public CollatingIterator(Comparator comp, Collection iterators) {
  +    public CollatingIterator(final Comparator comp, final Collection iterators) {
           this(comp, iterators.size());
           for (Iterator it = iterators.iterator(); it.hasNext();) {
               Iterator item = (Iterator) it.next();
  @@ -191,14 +186,15 @@
       }
   
       // Public Methods
  -    // -------------------------------------------------------------------
  -
  +    // ----------------------------------------------------------------------
       /**
  -     * Add the given {@link Iterator} to my collection to collate.
  -     * @throws IllegalStateException if I've already started iterating
  +     * Adds the given {@link Iterator} to the iterators being collated.
  +     * 
  +     * @param iterator  the iterator to add to the collation, must not be null
  +     * @throws IllegalStateException if iteration has started
        * @throws NullPointerException if the iterator is null
        */
  -    public void addIterator(Iterator iterator) {
  +    public void addIterator(final Iterator iterator) {
           checkNotStarted();
           if (iterator == null) {
               throw new NullPointerException("Iterator must not be null");
  @@ -207,15 +203,15 @@
       }
   
       /**
  -     * Set the Iterator at the given index     
  +     * Sets the iterator at the given index.
        * 
  -     * @param index      index of the Iterator to replace
  -     * @param iterator   Iterator to place at the given index
  +     * @param index  index of the Iterator to replace
  +     * @param iterator  Iterator to place at the given index
        * @throws IndexOutOfBoundsException if index &lt; 0 or index &gt; size()
  -     * @throws IllegalStateException if I've already started iterating
  +     * @throws IllegalStateException if iteration has started
        * @throws NullPointerException if the iterator is null
        */
  -    public void setIterator(int index, Iterator iterator) throws IndexOutOfBoundsException
{
  +    public void setIterator(final int index, final Iterator iterator) {
           checkNotStarted();
           if (iterator == null) {
               throw new NullPointerException("Iterator must not be null");
  @@ -224,7 +220,7 @@
       }
   
       /**
  -     * Get the list of Iterators (unmodifiable)
  +     * Gets the list of Iterators (unmodifiable).
        * 
        * @return the unmodifiable list of iterators added
        */
  @@ -233,28 +229,28 @@
       }
   
       /**
  -     * Set the {@link Comparator} by which I collate.
  -     * @throws IllegalStateException if I've already started iterating
  +     * Gets the {@link Comparator} by which collatation occurs.
        */
  -    public void setComparator(Comparator comp) {
  -        checkNotStarted();
  -        comparator = comp;
  +    public Comparator getComparator() {
  +        return comparator;
       }
   
       /**
  -     * Get the {@link Comparator} by which I collate.
  +     * Sets the {@link Comparator} by which collation occurs.
  +     * 
  +     * @throws IllegalStateException if iteration has started
        */
  -    public Comparator getComparator() {
  -        return comparator;
  +    public void setComparator(final Comparator comp) {
  +        checkNotStarted();
  +        comparator = comp;
       }
   
       // Iterator Methods
       // -------------------------------------------------------------------
  -
       /**
  -     *  Returns <code>true</code> if any child iterator has remaining elements.
  +     * Returns <code>true</code> if any child iterator has remaining elements.
        *
  -     *  @return true if this iterator has remaining elements
  +     * @return true if this iterator has remaining elements
        */
       public boolean hasNext() {
           start();
  @@ -262,53 +258,51 @@
       }
   
       /**
  -     *  Returns the next ordered element from a child iterator.
  +     * Returns the next ordered element from a child iterator.
        *
  -     *  @return the next ordered element
  -     *  @throws NoSuchElementException  if no child iterator has any more
  -     *    elements
  +     * @return the next ordered element
  +     * @throws NoSuchElementException if no child iterator has any more elements
        */
       public Object next() throws NoSuchElementException {
  -        if(!hasNext()) {
  +        if (hasNext() == false) {
  +            throw new NoSuchElementException();
  +        }
  +        int leastIndex = least();
  +        if (leastIndex == -1) {
               throw new NoSuchElementException();
           } else {
  -            int leastIndex = least();
  -            if(leastIndex == -1) {
  -                throw new NoSuchElementException();
  -            } else {
  -                Object val = values.get(leastIndex);
  -                clear(leastIndex);
  -                lastReturned = leastIndex;
  -                return val;
  -            }
  -        }        
  +            Object val = values.get(leastIndex);
  +            clear(leastIndex);
  +            lastReturned = leastIndex;
  +            return val;
  +        }
       }
   
       /**
  -     *  Removes the last returned element from the child iterator that 
  -     *  produced it.
  +     * Removes the last returned element from the child iterator that 
  +     * produced it.
        *
  -     *  @throws IllegalStateException  if there is no last returned element,
  -     *    or if the last returned element has already been removed
  +     * @throws IllegalStateException if there is no last returned element,
  +     *  or if the last returned element has already been removed
        */
       public void remove() {
  -        if(-1 == lastReturned) {
  +        if (lastReturned == -1) {
               throw new IllegalStateException("No value can be removed at present");
  -        } else {
  -            Iterator iter = (Iterator)(iterators.get(lastReturned));
  -            iter.remove();
           }
  +        Iterator it = (Iterator) (iterators.get(lastReturned));
  +        it.remove();
       }
   
       // Private Methods
       // -------------------------------------------------------------------
  -
  -    /** Initialize my collating state if it hasn't been already. */
  +    /** 
  +     * Initializes the collating state if it hasn't been already.
  +     */
       private void start() {
  -        if(null == values) {
  +        if (values == null) {
               values = new ArrayList(iterators.size());
               valueSet = new BitSet(iterators.size());
  -            for(int i=0;i<iterators.size();i++) {
  +            for (int i = 0; i < iterators.size(); i++) {
                   values.add(null);
                   valueSet.clear(i);
               }
  @@ -316,7 +310,7 @@
       }
   
       /** 
  -     * Set the {@link #values} and {@link #valueSet} attributes 
  +     * Sets the {@link #values} and {@link #valueSet} attributes 
        * at position <i>i</i> to the next value of the 
        * {@link #iterators iterator} at position <i>i</i>, or 
        * clear them if the <i>i</i><sup>th</sup> iterator
  @@ -325,9 +319,9 @@
        * @return <tt>false</tt> iff there was no value to set
        */
       private boolean set(int i) {
  -        Iterator iter = (Iterator)(iterators.get(i));
  -        if(iter.hasNext()) {
  -            values.set(i,iter.next());
  +        Iterator it = (Iterator)(iterators.get(i));
  +        if (it.hasNext()) {
  +            values.set(i, it.next());
               valueSet.set(i);
               return true;
           } else {
  @@ -338,7 +332,7 @@
       }
   
       /** 
  -     * Clear the {@link #values} and {@link #valueSet} attributes 
  +     * Clears the {@link #values} and {@link #valueSet} attributes 
        * at position <i>i</i>.
        */
       private void clear(int i) {
  @@ -347,11 +341,13 @@
       }
   
       /** 
  -     * Throw {@link IllegalStateException} iff I've been {@link #start started}.
  -     * @throws IllegalStateException iff I've been {@link #start started}
  +     * Throws {@link IllegalStateException} if iteration has started 
  +     * via {@link #start}.
  +     * 
  +     * @throws IllegalStateException if iteration started
        */
       private void checkNotStarted() throws IllegalStateException {
  -        if (null != values) {
  +        if (values != null) {
               throw new IllegalStateException("Can't do that after next or hasNext has been
called.");
           }
       }
  @@ -359,21 +355,23 @@
       /** 
        * Returns the index of the least element in {@link #values},
        * {@link #set(int) setting} any uninitialized values.
  +     * 
  +     * @throws IllegalStateException
        */
  -    private int least() throws IllegalStateException {
  +    private int least() {
           int leastIndex = -1;
           Object leastObject = null;                
  -        for(int i=0;i<values.size();i++) {
  -            if(!valueSet.get(i)) {
  +        for (int i = 0; i < values.size(); i++) {
  +            if (valueSet.get(i) == false) {
                   set(i);
               }
  -            if(valueSet.get(i)) {
  -                if(leastIndex == -1) {
  +            if (valueSet.get(i)) {
  +                if (leastIndex == -1) {
                       leastIndex = i;
                       leastObject = values.get(i);
                   } else {
                       Object curObject = values.get(i);
  -                    if(comparator.compare(curObject,leastObject) < 0) {
  +                    if (comparator.compare(curObject,leastObject) < 0) {
                           leastObject = curObject;
                           leastIndex = i;
                       }
  @@ -388,8 +386,8 @@
        * <code>true</code>.
        */
       private boolean anyValueSet(BitSet set) {
  -        for(int i=0;i<set.size();i++) {
  -            if(set.get(i)) {
  +        for (int i = 0; i < set.size(); i++) {
  +            if (set.get(i)) {
                   return true;
               }
           }
  @@ -401,9 +399,9 @@
        * in the given list has a next value.
        */
       private boolean anyHasNext(ArrayList iters) {
  -        for(int i=0;i<iters.size();i++) {
  -            Iterator iter = (Iterator)iters.get(i);
  -            if(iter.hasNext()) {
  +        for (int i = 0; i < iters.size(); i++) {
  +            Iterator it = (Iterator) iters.get(i);
  +            if (it.hasNext()) {
                   return true;
               }
           }
  
  
  
  1.5       +40 -40    jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/EnumerationIterator.java
  
  Index: EnumerationIterator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/EnumerationIterator.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- EnumerationIterator.java	29 Sep 2003 22:02:33 -0000	1.4
  +++ EnumerationIterator.java	29 Sep 2003 22:37:40 -0000	1.5
  @@ -73,61 +73,64 @@
    */
   public class EnumerationIterator implements Iterator {
       
  +    /** The collection to remove elements from */
       private Collection collection;
  -
  +    /** The enumeration being converted */
       private Enumeration enumeration;
  -
  +    /** The last object retrieved */
       private Object last;
       
  +    // Constructors
  +    //-----------------------------------------------------------------------
       /**
  -     *  Constructs a new <code>EnumerationIterator</code> that will not
  -     *  function until {@link #setEnumeration(Enumeration)} is called.
  +     * Constructs a new <code>EnumerationIterator</code> that will not
  +     * function until {@link #setEnumeration(Enumeration)} is called.
        */
       public EnumerationIterator() {
           this(null, null);
       }
   
       /**
  -     *  Constructs a new <code>EnumerationIterator</code> that provides
  -     *  an iterator view of the given enumeration.
  +     * Constructs a new <code>EnumerationIterator</code> that provides
  +     * an iterator view of the given enumeration.
        *
  -     *  @param enumeration  the enumeration to use
  +     * @param enumeration  the enumeration to use
        */
  -    public EnumerationIterator( Enumeration enumeration ) {
  +    public EnumerationIterator(final Enumeration enumeration) {
           this(enumeration, null);
       }
   
       /**
  -     *  Constructs a new <code>EnumerationIterator</code> that will remove
  -     *  elements from the specified collection.
  +     * Constructs a new <code>EnumerationIterator</code> that will remove
  +     * elements from the specified collection.
        *
  -     *  @param enum  the enumeration to use
  -     *  @param collection  the collection to remove elements form
  +     * @param enum  the enumeration to use
  +     * @param collection  the collection to remove elements form
        */
  -    public EnumerationIterator( Enumeration enum, Collection collection ) {
  +    public EnumerationIterator(final Enumeration enum, final Collection collection) {
  +        super();
           this.enumeration = enum;
           this.collection = collection;
           this.last = null;
       }
   
       // Iterator interface
  -    //-------------------------------------------------------------------------
  -
  +    //-----------------------------------------------------------------------
       /**
  -     *  Returns true if the underlying enumeration has more elements.
  +     * Returns true if the underlying enumeration has more elements.
        *
  -     *  @return true if the underlying enumeration has more elements
  -     *  @throws NullPointerException  if the underlying enumeration is null
  +     * @return true if the underlying enumeration has more elements
  +     * @throws NullPointerException  if the underlying enumeration is null
        */
       public boolean hasNext() {
           return enumeration.hasMoreElements();
       }
   
       /**
  -     *  Returns the next object from the enumeration.
  +     * Returns the next object from the enumeration.
        *
  -     *  @return the next object from the enumeration
  -     *  @throws NullPointerException if the enumeration is null
  +     * @return the next object from the enumeration
  +     * @throws NullPointerException if the enumeration is null
        */
       public Object next() {
           last = enumeration.nextElement();
  @@ -135,48 +138,45 @@
       }
   
       /**
  +     * Removes the last retrieved element if a collection is attached.
  +     * <p>
        * Functions if an associated <code>Collection</code> is known.
        * If so, the first occurrence of the last returned object from this
        * iterator will be removed from the collection.
        *
        * @exception IllegalStateException <code>next()</code> not called.
  -     * @exception UnsupportedOperationException No associated
  -     * <code>Collection</code>.
  +     * @exception UnsupportedOperationException if no associated collection
        */
       public void remove() {
           if (collection != null) {
               if (last != null) {
                   collection.remove(last);
  +            } else {
  +                throw new IllegalStateException("next() must have been called for remove()
to function");
               }
  -            else {
  -                throw new IllegalStateException
  -                    ("next() must have been called for remove() to function");
  -            }
  -        }
  -        else {
  -            throw new UnsupportedOperationException
  -                ("No Collection associated with this Iterator");
  +        } else {
  +            throw new UnsupportedOperationException("No Collection associated with this
Iterator");
           }
       }
   
       // Properties
  -    //-------------------------------------------------------------------------
  -
  +    //-----------------------------------------------------------------------
       /**
  -     *  Returns the underlying enumeration.
  +     * Returns the underlying enumeration.
        *
  -     *  @return the underlying enumeration
  +     * @return the underlying enumeration
        */
       public Enumeration getEnumeration() {
           return enumeration;
       }
   
       /**
  -     *  Sets the underlying enumeration.
  +     * Sets the underlying enumeration.
        *
  -     *  @param enumeration  the new underlying enumeration
  +     * @param enumeration  the new underlying enumeration
        */
  -    public void setEnumeration( Enumeration enumeration ) {
  +    public void setEnumeration(final Enumeration enumeration) {
           this.enumeration = enumeration;
       }
  +    
   }
  
  
  
  1.6       +18 -16    jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayListIterator.java
  
  Index: ArrayListIterator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayListIterator.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- ArrayListIterator.java	29 Sep 2003 03:56:12 -0000	1.5
  +++ ArrayListIterator.java	29 Sep 2003 22:37:40 -0000	1.6
  @@ -86,13 +86,16 @@
   public class ArrayListIterator extends ArrayIterator implements ResetableListIterator {
   
       /**
  -     * Holds the index of the last item returned by a call to <code>next()</code>
or <code>previous()</code>. This
  -     *  is set to <code>-1</code> if neither method has yet been invoked. <code>lastItemIndex</code>
is used to to
  -     * implement the {@link #set} method.
  +     * Holds the index of the last item returned by a call to <code>next()</code>
  +     * or <code>previous()</code>. This is set to <code>-1</code>
if neither method
  +     * has yet been invoked. <code>lastItemIndex</code> is used to to implement

  +     * the {@link #set} method.
        *
        */
       protected int lastItemIndex = -1;
   
  +    // Constructors
  +    // ----------------------------------------------------------------------
       /**
        * Constructor for use with <code>setArray</code>.
        * <p>
  @@ -120,14 +123,14 @@
        * specified array from a specific start index.
        *
        * @param array  the array to iterate over
  -     * @param start  the index to start iterating at
  +     * @param startIndex  the index to start iterating at
        * @throws IllegalArgumentException if <code>array</code> is not an array.
        * @throws NullPointerException if <code>array</code> is <code>null</code>
        * @throws IndexOutOfBoundsException if the start index is out of bounds
        */
  -    public ArrayListIterator(Object array, int start) {
  -        super(array, start);
  -        this.startIndex = start;
  +    public ArrayListIterator(Object array, int startIndex) {
  +        super(array, startIndex);
  +        this.startIndex = startIndex;
       }
   
       /**
  @@ -135,21 +138,20 @@
        * in the specified array.
        *
        * @param array  the array to iterate over
  -     * @param start  the index to start iterating at
  -     * @param end  the index (exclusive) to finish iterating at
  +     * @param startIndex  the index to start iterating at
  +     * @param endIndex  the index (exclusive) to finish iterating at
        * @throws IllegalArgumentException if <code>array</code> is not an array.
        * @throws IndexOutOfBoundsException if the start or end index is out of bounds
        * @throws IllegalArgumentException if end index is before the start
        * @throws NullPointerException if <code>array</code> is <code>null</code>
        */
  -    public ArrayListIterator(Object array, int start, int end) {
  -        super(array, start, end);
  -        this.startIndex = start;
  +    public ArrayListIterator(Object array, int startIndex, int endIndex) {
  +        super(array, startIndex, endIndex);
  +        this.startIndex = startIndex;
       }
   
       // ListIterator interface
  -    //-------------------------------------------------------------------------
  -
  +    //-----------------------------------------------------------------------
       /**
        * Returns true if there are previous elements to return from the array.
        *
  
  
  
  1.6       +66 -70    jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayIterator.java
  
  Index: ArrayIterator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayIterator.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- ArrayIterator.java	31 Aug 2003 17:25:49 -0000	1.5
  +++ ArrayIterator.java	29 Sep 2003 22:37:40 -0000	1.6
  @@ -61,7 +61,7 @@
   import java.util.NoSuchElementException;
   
   /** 
  - * Implements an {@link java.util.Iterator Iterator} over an array.
  + * Implements an {@link java.util.Iterator Iterator} over any array.
    * <p>
    * The array can be either an array of object or of primitives. If you know 
    * that you have an object array, the 
  @@ -74,15 +74,15 @@
    * @since Commons Collections 1.0
    * @version $Revision$ $Date$
    *
  - * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
  + * @author James Strachan
    * @author Mauricio S. Moura
  - * @author <a href="mailto:mas@apache.org">Michael A. Smith</a>
  - * @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a>
  + * @author Michael A. Smith
  + * @author Neil O'Toole
    * @author Stephen Colebourne
    */
   public class ArrayIterator implements ResetableIterator {
   
  -    /** The array */    
  +    /** The array to iterate over */    
       protected Object array;
       /** The start index to loop from */
       protected int startIndex = 0;
  @@ -91,6 +91,8 @@
       /** The current iterator index */
   	protected int index = 0;
       
  +    // Constructors
  +    // ----------------------------------------------------------------------
       /**
        * Constructor for use with <code>setArray</code>.
        * <p>
  @@ -109,9 +111,9 @@
        * @throws IllegalArgumentException if <code>array</code> is not an array.
        * @throws NullPointerException if <code>array</code> is <code>null</code>
        */
  -    public ArrayIterator(Object array) {
  +    public ArrayIterator(final Object array) {
           super();
  -        setArray( array );
  +        setArray(array);
       }
   
       /**
  @@ -119,15 +121,17 @@
        * specified array from a specific start index.
        *
        * @param array  the array to iterate over.
  -     * @param start  the index to start iterating at.
  +     * @param startIndex  the index to start iterating at.
        * @throws IllegalArgumentException if <code>array</code> is not an array.
        * @throws NullPointerException if <code>array</code> is <code>null</code>
  +     * @throws IndexOutOfBoundsException if the index is invalid
        */
  -    public ArrayIterator(Object array, int start) {
  -        setArray( array );
  -        checkBound(start, "start");
  -        this.startIndex = start;
  -        this.index = start;
  +    public ArrayIterator(final Object array, final int startIndex) {
  +        super();
  +        setArray(array);
  +        checkBound(startIndex, "start");
  +        this.startIndex = startIndex;
  +        this.index = startIndex;
       }
   
       /**
  @@ -135,80 +139,87 @@
        * in the specified array.
        *
        * @param array  the array to iterate over.
  -     * @param start  the index to start iterating at.
  -     * @param end  the index to finish iterating at.
  +     * @param startIndex  the index to start iterating at.
  +     * @param endIndex  the index to finish iterating at.
        * @throws IllegalArgumentException if <code>array</code> is not an array.
        * @throws NullPointerException if <code>array</code> is <code>null</code>
  +     * @throws IndexOutOfBoundsException if either index is invalid
        */
  -    public ArrayIterator(Object array, int start, int end) {
  -        setArray( array );
  -        checkBound(start, "start");
  -        checkBound(end, "end");
  -        if (end < start) {
  +    public ArrayIterator(final Object array, final int startIndex, final int endIndex)
{
  +        super();
  +        setArray(array);
  +        checkBound(startIndex, "start");
  +        checkBound(endIndex, "end");
  +        if (endIndex < startIndex) {
               throw new IllegalArgumentException("End index must not be less than start index.");
           }
  -        this.startIndex = start;
  -        this.endIndex = end;
  -        this.index = start;
  +        this.startIndex = startIndex;
  +        this.endIndex = endIndex;
  +        this.index = startIndex;
       }
   
  -    protected void checkBound(int bound, String type ) {
  +    /**
  +     * Checks whether the index is valid or not.
  +     * 
  +     * @param bound  the index to check
  +     * @param type  the index type (for error messges)
  +     * @throws IndexOutOfBoundsException if the index is invalid
  +     */
  +    protected void checkBound(final int bound, final String type ) {
           if (bound > this.endIndex) {
               throw new ArrayIndexOutOfBoundsException(
  -              "Attempt to make an ArrayIterator that "+type+
  +              "Attempt to make an ArrayIterator that " + type +
                 "s beyond the end of the array. "
               );
           }
           if (bound < 0) {
               throw new ArrayIndexOutOfBoundsException(
  -              "Attempt to make an ArrayIterator that "+type+
  +              "Attempt to make an ArrayIterator that " + type +
                 "s before the start of the array. "
               );
           }
       }
   
       // Iterator interface
  -    //-------------------------------------------------------------------------
  -
  +    //-----------------------------------------------------------------------
       /**
  -     *  Returns true if there are more elements to return from the array.
  +     * Returns true if there are more elements to return from the array.
        *
  -     *  @return true if there is a next element to return
  +     * @return true if there is a next element to return
        */
       public boolean hasNext() {
           return (index < endIndex);
       }
   
       /**
  -     *  Returns the next element in the array.
  +     * Returns the next element in the array.
        *
  -     *  @return the next element in the array
  -     *  @throws NoSuchElementException if all the elements in the array
  -     *    have already been returned
  +     * @return the next element in the array
  +     * @throws NoSuchElementException if all the elements in the array
  +     *  have already been returned
        */
       public Object next() {
           if (hasNext() == false) {
               throw new NoSuchElementException();
           }
  -        return Array.get( array, index++ );
  +        return Array.get(array, index++);
       }
   
       /**
  -     *  Throws {@link UnsupportedOperationException}.
  +     * Throws {@link UnsupportedOperationException}.
        *
  -     *  @throws UnsupportedOperationException always
  +     * @throws UnsupportedOperationException always
        */
       public void remove() {
  -        throw new UnsupportedOperationException( "remove() method is not supported" );
  +        throw new UnsupportedOperationException("remove() method is not supported");
       }
   
       // Properties
  -    //-------------------------------------------------------------------------
  -
  +    //-----------------------------------------------------------------------
       /**
  -     *  Retrieves the array that this iterator is iterating over. 
  +     * Gets the array that this iterator is iterating over. 
        *
  -     *  @return the array this iterator iterates over, or <code>null</code>
if
  +     * @return the array this iterator iterates over, or <code>null</code>
if
        *  the no-arg constructor was used and {@link #setArray(Object)} has never
        *  been called with a valid array.
        */
  @@ -217,40 +228,25 @@
       }
       
       /**
  -     *  Changes the array that the ArrayIterator should iterate over.  If an
  -     *  array has previously been set (using the single-arg constructor or this
  -     *  method), that array along with the current iterator position within
  -     *  that array is discarded in favor of the argument to this method.  This
  -     *  method can be used in combination with {@link #getArray()} to "reset"
  -     *  the iterator to the beginning of the array:
  -     *
  -     *  <pre>
  -     *    ArrayIterator iterator = ...
  -     *    ...
  -     *    iterator.setArray(iterator.getArray());
  -     *  </pre>
  -     *
  -     *  Note: Using i.setArray(i.getArray()) may throw a NullPointerException
  -     *  if no array has ever been set for the iterator (see {@link
  -     *  #getArray()})
  +     * Sets the array that the ArrayIterator should iterate over.
        * <p>
  -     * The {@link #reset()} method is a better choice for resetting the iterator.
  -     *
  -     *  @param array the array that the iterator should iterate over.
  -     *
  -     *  @exception IllegalArgumentException if <code>array</code> is not an
  -     *  array.
  +     * If an array has previously been set (using the single-arg constructor
  +     * or this method) then that array is discarded in favour of this one.
  +     * Iteration is restarted at the start of the new array.
  +     * Although this can be used to reset iteration, the {@link #reset()} method
  +     * is a more effective choice.
        *
  -     *  @exception NullPointerException 
  -     *  if <code>array</code> is <code>null</code>
  +     * @param array the array that the iterator should iterate over.
  +     * @throws IllegalArgumentException if <code>array</code> is not an array.
  +     * @throws NullPointerException if <code>array</code> is <code>null</code>
        */
  -    public void setArray( Object array ) {
  +    public void setArray(final Object array) {
           // Array.getLength throws IllegalArgumentException if the object is not
           // an array or NullPointerException if the object is null.  This call
           // is made before saving the array and resetting the index so that the
           // array iterator remains in a consistent state if the argument is not
           // an array or is null.
  -        this.endIndex = Array.getLength( array );
  +        this.endIndex = Array.getLength(array);
           this.startIndex = 0;
           this.array = array;
           this.index = 0;
  
  
  

Mime
View raw message