KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > iterators > ArrayListIterator


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections.iterators;
17
18 import java.lang.reflect.Array JavaDoc;
19 import java.util.ListIterator JavaDoc;
20 import java.util.NoSuchElementException JavaDoc;
21
22 import org.apache.commons.collections.ResettableListIterator;
23
24 /**
25  * Implements a {@link ListIterator} over an array.
26  * <p>
27  * The array can be either an array of object or of primitives. If you know
28  * that you have an object array, the {@link ObjectArrayListIterator}
29  * class is a better choice, as it will perform better.
30  *
31  * <p>
32  * This iterator does not support {@link #add(Object)} or {@link #remove()}, as the array
33  * cannot be changed in size. The {@link #set(Object)} method is supported however.
34  *
35  * @see org.apache.commons.collections.iterators.ArrayIterator
36  * @see java.util.Iterator
37  * @see java.util.ListIterator
38  *
39  * @since Commons Collections 3.0
40  * @version $Revision: 1.12 $ $Date: 2004/02/18 00:59:50 $
41  *
42  * @author Neil O'Toole
43  * @author Stephen Colebourne
44  * @author Phil Steitz
45  */
46 public class ArrayListIterator extends ArrayIterator
47         implements ListIterator JavaDoc, ResettableListIterator {
48
49     /**
50      * Holds the index of the last item returned by a call to <code>next()</code>
51      * or <code>previous()</code>. This is set to <code>-1</code> if neither method
52      * has yet been invoked. <code>lastItemIndex</code> is used to to implement
53      * the {@link #set} method.
54      *
55      */
56     protected int lastItemIndex = -1;
57
58     // Constructors
59 // ----------------------------------------------------------------------
60 /**
61      * Constructor for use with <code>setArray</code>.
62      * <p>
63      * Using this constructor, the iterator is equivalent to an empty iterator
64      * until {@link #setArray(Object)} is called to establish the array to iterate over.
65      */
66     public ArrayListIterator() {
67         super();
68     }
69
70     /**
71      * Constructs an ArrayListIterator that will iterate over the values in the
72      * specified array.
73      *
74      * @param array the array to iterate over
75      * @throws IllegalArgumentException if <code>array</code> is not an array.
76      * @throws NullPointerException if <code>array</code> is <code>null</code>
77      */
78     public ArrayListIterator(Object JavaDoc array) {
79         super(array);
80     }
81
82     /**
83      * Constructs an ArrayListIterator that will iterate over the values in the
84      * specified array from a specific start index.
85      *
86      * @param array the array to iterate over
87      * @param startIndex the index to start iterating at
88      * @throws IllegalArgumentException if <code>array</code> is not an array.
89      * @throws NullPointerException if <code>array</code> is <code>null</code>
90      * @throws IndexOutOfBoundsException if the start index is out of bounds
91      */
92     public ArrayListIterator(Object JavaDoc array, int startIndex) {
93         super(array, startIndex);
94         this.startIndex = startIndex;
95     }
96
97     /**
98      * Construct an ArrayListIterator that will iterate over a range of values
99      * in the specified array.
100      *
101      * @param array the array to iterate over
102      * @param startIndex the index to start iterating at
103      * @param endIndex the index (exclusive) to finish iterating at
104      * @throws IllegalArgumentException if <code>array</code> is not an array.
105      * @throws IndexOutOfBoundsException if the start or end index is out of bounds
106      * @throws IllegalArgumentException if end index is before the start
107      * @throws NullPointerException if <code>array</code> is <code>null</code>
108      */
109     public ArrayListIterator(Object JavaDoc array, int startIndex, int endIndex) {
110         super(array, startIndex, endIndex);
111         this.startIndex = startIndex;
112     }
113
114     // ListIterator interface
115 //-----------------------------------------------------------------------
116 /**
117      * Returns true if there are previous elements to return from the array.
118      *
119      * @return true if there is a previous element to return
120      */
121     public boolean hasPrevious() {
122         return (this.index > this.startIndex);
123     }
124
125     /**
126      * Gets the previous element from the array.
127      *
128      * @return the previous element
129      * @throws NoSuchElementException if there is no previous element
130      */
131     public Object JavaDoc previous() {
132         if (hasPrevious() == false) {
133             throw new NoSuchElementException JavaDoc();
134         }
135         this.lastItemIndex = --this.index;
136         return Array.get(this.array, this.index);
137     }
138
139     /**
140      * Gets the next element from the array.
141      *
142      * @return the next element
143      * @throws NoSuchElementException if there is no next element
144      */
145     public Object JavaDoc next() {
146         if (hasNext() == false) {
147             throw new NoSuchElementException JavaDoc();
148         }
149         this.lastItemIndex = this.index;
150         return Array.get(this.array, this.index++);
151     }
152
153     /**
154      * Gets the next index to be retrieved.
155      *
156      * @return the index of the item to be retrieved next
157      */
158     public int nextIndex() {
159         return this.index - this.startIndex;
160     }
161
162     /**
163      * Gets the index of the item to be retrieved if {@link #previous()} is called.
164      *
165      * @return the index of the item to be retrieved next
166      */
167     public int previousIndex() {
168         return this.index - this.startIndex - 1;
169     }
170
171     /**
172      * This iterator does not support modification of its backing collection, and so will
173      * always throw an {@link UnsupportedOperationException} when this method is invoked.
174      *
175      * @throws UnsupportedOperationException always thrown.
176      * @see java.util.ListIterator#set
177      */
178     public void add(Object JavaDoc o) {
179         throw new UnsupportedOperationException JavaDoc("add() method is not supported");
180     }
181
182     /**
183      * Sets the element under the cursor.
184      * <p>
185      * This method sets the element that was returned by the last call
186      * to {@link #next()} of {@link #previous()}.
187      * <p>
188      * <b>Note:</b> {@link ListIterator} implementations that support
189      * <code>add()</code> and <code>remove()</code> only allow <code>set()</code> to be called
190      * once per call to <code>next()</code> or <code>previous</code> (see the {@link ListIterator}
191      * javadoc for more details). Since this implementation does
192      * not support <code>add()</code> or <code>remove()</code>, <code>set()</code> may be
193      * called as often as desired.
194      *
195      * @see java.util.ListIterator#set
196      */
197     public void set(Object JavaDoc o) {
198         if (this.lastItemIndex == -1) {
199             throw new IllegalStateException JavaDoc("must call next() or previous() before a call to set()");
200         }
201
202         Array.set(this.array, this.lastItemIndex, o);
203     }
204
205     /**
206      * Resets the iterator back to the start index.
207      */
208     public void reset() {
209         super.reset();
210         this.lastItemIndex = -1;
211     }
212
213 }
214
Popular Tags