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