001    package com.softnetConsult.utils.collections;
002    
003    import java.util.Iterator;
004    import java.util.NoSuchElementException;
005    
006    /**
007     * Implements an iterator over an array.
008     * 
009     * <p style="font-size:smaller;">This product includes software developed by the
010     *    <strong>SoftNet-Consult Java Utility Library</strong> project and its contributors.<br />
011     *    (<a href="http://java-tools.sourceforge.net" target="_blank">http://java-tools.sourceforge.net</a>)<br />
012     *    Copyright (c) 2007-2008 SoftNet-Consult.<br />
013     *    Copyright (c) 2007-2008 G. Paperin.<br />
014     *    All rights reserved.
015     * </p>
016     * <p style="font-size:smaller;">File: AttayIterator.java<br />
017     *    Library API version: {@value com.softnetConsult.utils.APIProperties#apiVersion}<br />
018     *    Java compliance version: {@value com.softnetConsult.utils.APIProperties#javaComplianceVersion}
019     * </p>
020     * <p style="font-size:smaller;">Redistribution and use in source and binary forms, with or
021     *    without modification, are permitted provided that the following terms and conditions are met:
022     * </p>
023     * <p style="font-size:smaller;">1. Redistributions of source code must retain the above
024     *    acknowledgement of the SoftNet-Consult Java Utility Library project, the above copyright
025     *    notice, this list of conditions and the following disclaimer.<br />
026     *    2. Redistributions in binary form must reproduce the above acknowledgement of the
027     *    SoftNet-Consult Java Utility Library project, the above copyright notice, this list of
028     *    conditions and the following disclaimer in the documentation and/or other materials
029     *    provided with the distribution.<br />
030     *    3. All advertising materials mentioning features or use of this software or any derived
031     *    software must display the following acknowledgement:<br />
032     *    <em>This product includes software developed by the SoftNet-Consult Java Utility Library
033     *    project and its contributors.</em>
034     * </p>
035     * <p style="font-size:smaller;">THIS SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY
036     *    OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
037     *    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT SHALL
038     *    THE AUTHORS, CONTRIBUTORS OR COPYRIGHT  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
039     *    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  FROM, OUT OF OR
040     *    IN CONNECTION WITH THE SOFTWARE OR THE USE OR  OTHER DEALINGS IN THE SOFTWARE.
041     * </p> 
042     * @author Greg Paperin (<a href="http://www.paperin.org" target="_blank">http://www.paperin.org</a>)
043     * @version {@value com.softnetConsult.utils.APIProperties#apiVersion}
044     *
045     * @param <ET> Type of objects over which this iterator iterates.
046     */
047    public class ArrayIterator<ET> implements Iterator<ET> {
048    
049    /**
050     * Array being iterated.
051     */
052    private ET[] array = null;
053    
054    /**
055     * Cursor into the array.
056     */
057    private int cursor = -1;
058    
059    
060    /**
061     * Creates an array iterator over the specified array.
062     * 
063     * @param <AET> The array may contain objects of any class which is a subclass
064     * to the parameter type of this iterator.
065     * @param array Array to be iterated.
066     */
067    public <AET extends ET> ArrayIterator(AET[] array) {
068            if (null == array)
069                    throw new NullPointerException("Cannot create an iterator on a null-array.");
070            this.array = array;
071            this.cursor = 0;
072    }
073    
074    /**
075     * Returns {@code true} if this iteration has more elements.
076     * 
077     * @return {@code true} if {@code next()} would return an element rather than throwing an exception,
078     * {@code false} otherwise.
079     */
080    public boolean hasNext() {      
081            if (cursor < array.length)
082                    return true;
083            return false;
084    }
085    
086    /**
087     * Returns the next element in this iteration.
088     * 
089     * @return The next element in this iteration.
090     * @throws NoSuchElementException If this iteration has no more elements.
091     */
092    public ET next() {      
093            if (cursor < 0 || array.length <= cursor)
094                    throw new NoSuchElementException("Array element index " + cursor + " is illegal, "
095                                                                               + "this iterator's array has " + array.length + " elements");
096            return array[cursor++];
097    }
098    
099    /**
100     * Removing of array elements is obviously not supported.
101     * 
102     * @throws UnsupportedOperationException is always thrown.
103     */
104    public void remove() {
105            throw new UnsupportedOperationException("Cannot remove elements from an array");
106    }
107    
108    /**
109     * Resets the internal cursor of this iterator to point to the start of the unederlying array.
110     * This method allows traversing an array several times using the same iterator.
111     */
112    public void restart() {
113            cursor = 0;
114    }
115    
116    } // public class ArrayIterator<ET>