001: /*
002: * Copyright 1999-2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.collections.iterators;
017:
018: import java.util.Iterator;
019: import java.util.NoSuchElementException;
020:
021: import org.apache.commons.collections.ResettableIterator;
022:
023: /**
024: * An {@link Iterator} over an array of objects.
025: * <p>
026: * This iterator does not support {@link #remove}, as the object array cannot be
027: * structurally modified.
028: * <p>
029: * The iterator implements a {@link #reset} method, allowing the reset of the iterator
030: * back to the start if required.
031: *
032: * @since Commons Collections 3.0
033: * @version $Revision: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $
034: *
035: * @author James Strachan
036: * @author Mauricio S. Moura
037: * @author Michael A. Smith
038: * @author Neil O'Toole
039: * @author Stephen Colebourne
040: * @author Phil Steitz
041: */
042: public class ObjectArrayIterator implements Iterator,
043: ResettableIterator {
044:
045: /** The array */
046: protected Object[] array = null;
047: /** The start index to loop from */
048: protected int startIndex = 0;
049: /** The end index to loop to */
050: protected int endIndex = 0;
051: /** The current iterator index */
052: protected int index = 0;
053:
054: /**
055: * Constructor for use with <code>setArray</code>.
056: * <p>
057: * Using this constructor, the iterator is equivalent to an empty iterator
058: * until {@link #setArray} is called to establish the array to iterate over.
059: */
060: public ObjectArrayIterator() {
061: super ();
062: }
063:
064: /**
065: * Constructs an ObjectArrayIterator that will iterate over the values in the
066: * specified array.
067: *
068: * @param array the array to iterate over
069: * @throws NullPointerException if <code>array</code> is <code>null</code>
070: */
071: public ObjectArrayIterator(Object[] array) {
072: this (array, 0, array.length);
073: }
074:
075: /**
076: * Constructs an ObjectArrayIterator that will iterate over the values in the
077: * specified array from a specific start index.
078: *
079: * @param array the array to iterate over
080: * @param start the index to start iterating at
081: * @throws NullPointerException if <code>array</code> is <code>null</code>
082: * @throws IndexOutOfBoundsException if the start index is out of bounds
083: */
084: public ObjectArrayIterator(Object array[], int start) {
085: this (array, start, array.length);
086: }
087:
088: /**
089: * Construct an ObjectArrayIterator that will iterate over a range of values
090: * in the specified array.
091: *
092: * @param array the array to iterate over
093: * @param start the index to start iterating at
094: * @param end the index (exclusive) to finish iterating at
095: * @throws IndexOutOfBoundsException if the start or end index is out of bounds
096: * @throws IllegalArgumentException if end index is before the start
097: * @throws NullPointerException if <code>array</code> is <code>null</code>
098: */
099: public ObjectArrayIterator(Object array[], int start, int end) {
100: super ();
101: if (start < 0) {
102: throw new ArrayIndexOutOfBoundsException(
103: "Start index must not be less than zero");
104: }
105: if (end > array.length) {
106: throw new ArrayIndexOutOfBoundsException(
107: "End index must not be greater than the array length");
108: }
109: if (start > array.length) {
110: throw new ArrayIndexOutOfBoundsException(
111: "Start index must not be greater than the array length");
112: }
113: if (end < start) {
114: throw new IllegalArgumentException(
115: "End index must not be less than start index");
116: }
117: this .array = array;
118: this .startIndex = start;
119: this .endIndex = end;
120: this .index = start;
121: }
122:
123: // Iterator interface
124: //-------------------------------------------------------------------------
125:
126: /**
127: * Returns true if there are more elements to return from the array.
128: *
129: * @return true if there is a next element to return
130: */
131: public boolean hasNext() {
132: return (this .index < this .endIndex);
133: }
134:
135: /**
136: * Returns the next element in the array.
137: *
138: * @return the next element in the array
139: * @throws NoSuchElementException if all the elements in the array
140: * have already been returned
141: */
142: public Object next() {
143: if (hasNext() == false) {
144: throw new NoSuchElementException();
145: }
146: return this .array[this .index++];
147: }
148:
149: /**
150: * Throws {@link UnsupportedOperationException}.
151: *
152: * @throws UnsupportedOperationException always
153: */
154: public void remove() {
155: throw new UnsupportedOperationException(
156: "remove() method is not supported for an ObjectArrayIterator");
157: }
158:
159: // Properties
160: //-------------------------------------------------------------------------
161:
162: /**
163: * Gets the array that this iterator is iterating over.
164: *
165: * @return the array this iterator iterates over, or <code>null</code> if
166: * the no-arg constructor was used and {@link #setArray} has never
167: * been called with a valid array.
168: */
169: public Object[] getArray() {
170: return this .array;
171: }
172:
173: /**
174: * Sets the array that the ArrayIterator should iterate over.
175: * <p>
176: * This method may only be called once, otherwise an IllegalStateException
177: * will occur.
178: * <p>
179: * The {@link #reset} method can be used to reset the iterator if required.
180: *
181: * @param array the array that the iterator should iterate over
182: * @throws IllegalStateException if the <code>array</code> was set in the constructor
183: * @throws NullPointerException if <code>array</code> is <code>null</code>
184: */
185: public void setArray(Object[] array) {
186: if (this .array != null) {
187: throw new IllegalStateException(
188: "The array to iterate over has already been set");
189: }
190: this .array = array;
191: this .startIndex = 0;
192: this .endIndex = array.length;
193: this .index = 0;
194: }
195:
196: /**
197: * Gets the start index to loop from.
198: *
199: * @return the start index
200: */
201: public int getStartIndex() {
202: return this .startIndex;
203: }
204:
205: /**
206: * Gets the end index to loop to.
207: *
208: * @return the end index
209: */
210: public int getEndIndex() {
211: return this .endIndex;
212: }
213:
214: /**
215: * Resets the iterator back to the start index.
216: */
217: public void reset() {
218: this.index = this.startIndex;
219: }
220:
221: }
|