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 */ 017package org.apache.commons.collections4.iterators; 018 019import java.util.NoSuchElementException; 020 021import org.apache.commons.collections4.ResettableListIterator; 022 023/** 024 * Implements a {@link java.util.ListIterator} over an array of objects. 025 * <p> 026 * This iterator does not support {@link #add} or {@link #remove}, as the object array 027 * cannot be structurally modified. The {@link #set} method is supported however. 028 * </p> 029 * <p> 030 * The iterator implements a {@link #reset} method, allowing the reset of the iterator 031 * back to the start if required. 032 * </p> 033 * 034 * @param <E> the type of elements returned by this iterator. 035 * @see org.apache.commons.collections4.iterators.ObjectArrayIterator 036 * @see java.util.Iterator 037 * @see java.util.ListIterator 038 * @since 3.0 039 */ 040public class ObjectArrayListIterator<E> extends ObjectArrayIterator<E> 041 implements ResettableListIterator<E> { 042 043 /** 044 * Holds the index of the last item returned by a call to {@code next()} 045 * or {@code previous()}. This is set to {@code -1} if neither method 046 * has yet been invoked. {@code lastItemIndex} is used to implement the 047 * {@link #set} method. 048 */ 049 private int lastItemIndex = -1; 050 051 /** 052 * Constructs an ObjectArrayListIterator that will iterate over the values in the 053 * specified array. 054 * 055 * @param array the array to iterate over 056 * @throws NullPointerException if {@code array} is {@code null} 057 */ 058 public ObjectArrayListIterator(final E... array) { 059 super(array); 060 } 061 062 /** 063 * Constructs an ObjectArrayListIterator that will iterate over the values in the 064 * specified array from a specific start index. 065 * 066 * @param array the array to iterate over 067 * @param start the index to start iterating at 068 * @throws NullPointerException if {@code array} is {@code null} 069 * @throws IndexOutOfBoundsException if the start index is out of bounds 070 */ 071 public ObjectArrayListIterator(final E[] array, final int start) { 072 super(array, start); 073 } 074 075 /** 076 * Constructs an ObjectArrayListIterator that will iterate over a range of values 077 * in the specified array. 078 * 079 * @param array the array to iterate over 080 * @param start the index to start iterating at 081 * @param end the index (exclusive) to finish iterating at 082 * @throws IndexOutOfBoundsException if the start or end index is out of bounds 083 * @throws IllegalArgumentException if end index is before the start 084 * @throws NullPointerException if {@code array} is {@code null} 085 */ 086 public ObjectArrayListIterator(final E[] array, final int start, final int end) { 087 super(array, start, end); 088 } 089 090 /** 091 * This iterator does not support modification of its backing array's size, and so will 092 * always throw an {@link UnsupportedOperationException} when this method is invoked. 093 * 094 * @param obj the object to add 095 * @throws UnsupportedOperationException always thrown. 096 */ 097 @Override 098 public void add(final E obj) { 099 throw new UnsupportedOperationException("add() method is not supported"); 100 } 101 102 /** 103 * Returns true if there are previous elements to return from the array. 104 * 105 * @return true if there is a previous element to return 106 */ 107 @Override 108 public boolean hasPrevious() { 109 return index > getStartIndex(); 110 } 111 112 /** 113 * Gets the next element from the array. 114 * 115 * @return the next element 116 * @throws NoSuchElementException if there is no next element 117 */ 118 @Override 119 public E next() { 120 if (!hasNext()) { 121 throw new NoSuchElementException(); 122 } 123 lastItemIndex = index; 124 return array[index++]; 125 } 126 127 /** 128 * Gets the next index to be retrieved. 129 * 130 * @return the index of the item to be retrieved next 131 */ 132 @Override 133 public int nextIndex() { 134 return index - getStartIndex(); 135 } 136 137 /** 138 * Gets the previous element from the array. 139 * 140 * @return the previous element 141 * @throws NoSuchElementException if there is no previous element 142 */ 143 @Override 144 public E previous() { 145 if (!hasPrevious()) { 146 throw new NoSuchElementException(); 147 } 148 lastItemIndex = --index; 149 return array[index]; 150 } 151 152 /** 153 * Gets the index of the item to be retrieved if {@link #previous()} is called. 154 * 155 * @return the index of the item to be retrieved next 156 */ 157 @Override 158 public int previousIndex() { 159 return index - getStartIndex() - 1; 160 } 161 162 /** 163 * Resets the iterator back to the start index. 164 */ 165 @Override 166 public void reset() { 167 super.reset(); 168 lastItemIndex = -1; 169 } 170 171 /** 172 * Sets the element under the cursor. 173 * <p> 174 * This method sets the element that was returned by the last call 175 * to {@link #next()} of {@link #previous()}. 176 * </p> 177 * <p> 178 * <strong>Note:</strong> {@link java.util.ListIterator} implementations that support {@code add()} 179 * and {@code remove()} only allow {@code set()} to be called once per call 180 * to {@code next()} or {@code previous} (see the {@link java.util.ListIterator} 181 * Javadoc for more details). Since this implementation does not support 182 * {@code add()} or {@code remove()}, {@code set()} may be 183 * called as often as desired. 184 * </p> 185 * 186 * @param obj the object to set into the array 187 * @throws IllegalStateException if next() has not yet been called. 188 * @throws ClassCastException if the object type is unsuitable for the array 189 */ 190 @Override 191 public void set(final E obj) { 192 if (lastItemIndex == -1) { 193 throw new IllegalStateException("must call next() or previous() before a call to set()"); 194 } 195 array[lastItemIndex] = obj; 196 } 197 198}