KickJava   Java API By Example, From Geeks To Geeks.

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


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.util.ListIterator JavaDoc;
19 import java.util.NoSuchElementException JavaDoc;
20
21 import org.apache.commons.collections.ResettableListIterator;
22
23 /**
24  * Implements a {@link ListIterator} over an array of objects.
25  * <p>
26  * This iterator does not support {@link #add} or {@link #remove}, as the object array
27  * cannot be structurally modified. The {@link #set} method is supported however.
28  * <p>
29  * The iterator implements a {@link #reset} method, allowing the reset of the iterator
30  * back to the start if required.
31  *
32  * @see org.apache.commons.collections.iterators.ObjectArrayIterator
33  * @see java.util.Iterator
34  * @see java.util.ListIterator
35  *
36  * @since Commons Collections 3.0
37  * @version $Revision: 1.13 $ $Date: 2004/02/18 00:59:50 $
38  *
39  * @author Neil O'Toole
40  * @author Stephen Colebourne
41  * @author Phil Steitz
42  */
43 public class ObjectArrayListIterator extends ObjectArrayIterator
44         implements ListIterator JavaDoc, ResettableListIterator {
45
46     /**
47      * Holds the index of the last item returned by a call to <code>next()</code>
48      * or <code>previous()</code>. This is set to <code>-1</code> if neither method
49      * has yet been invoked. <code>lastItemIndex</code> is used to to implement the
50      * {@link #set} method.
51      */
52     protected int lastItemIndex = -1;
53
54     /**
55      * Constructor for use with <code>setArray</code>.
56      * <p>
57      * Using this constructor, the iterator is equivalent to an empty iterator
58      * until {@link #setArray} is called to establish the array to iterate over.
59      */
60     public ObjectArrayListIterator() {
61         super();
62     }
63
64     /**
65      * Constructs an ObjectArrayListIterator that will iterate over the values in the
66      * specified array.
67      *
68      * @param array the array to iterate over
69      * @throws NullPointerException if <code>array</code> is <code>null</code>
70      */
71     public ObjectArrayListIterator(Object JavaDoc[] array) {
72         super(array);
73     }
74
75     /**
76      * Constructs an ObjectArrayListIterator that will iterate over the values in the
77      * specified array from a specific start index.
78      *
79      * @param array the array to iterate over
80      * @param start the index to start iterating at
81      * @throws NullPointerException if <code>array</code> is <code>null</code>
82      * @throws IndexOutOfBoundsException if the start index is out of bounds
83      */
84     public ObjectArrayListIterator(Object JavaDoc[] array, int start) {
85         super(array, start);
86     }
87     
88     /**
89      * Construct an ObjectArrayListIterator that will iterate over a range of values
90      * in the specified array.
91      *
92      * @param array the array to iterate over
93      * @param start the index to start iterating at
94      * @param end the index (exclusive) to finish iterating at
95      * @throws IndexOutOfBoundsException if the start or end index is out of bounds
96      * @throws IllegalArgumentException if end index is before the start
97      * @throws NullPointerException if <code>array</code> is <code>null</code>
98      */
99     public ObjectArrayListIterator(Object JavaDoc[] array, int start, int end) {
100         super(array, start, end);
101     }
102
103     // ListIterator interface
104 //-------------------------------------------------------------------------
105
106     /**
107      * Returns true if there are previous elements to return from the array.
108      *
109      * @return true if there is a previous element to return
110      */
111     public boolean hasPrevious() {
112         return (this.index > this.startIndex);
113     }
114
115     /**
116      * Gets the previous element from the array.
117      *
118      * @return the previous element
119      * @throws NoSuchElementException if there is no previous element
120      */
121     public Object JavaDoc previous() {
122         if (hasPrevious() == false) {
123             throw new NoSuchElementException JavaDoc();
124         }
125         this.lastItemIndex = --this.index;
126         return this.array[this.index];
127     }
128
129     /**
130      * Gets the next element from the array.
131      *
132      * @return the next element
133      * @throws NoSuchElementException if there is no next element
134      */
135     public Object JavaDoc next() {
136         if (hasNext() == false) {
137             throw new NoSuchElementException JavaDoc();
138         }
139         this.lastItemIndex = this.index;
140         return this.array[this.index++];
141     }
142
143     /**
144      * Gets the next index to be retrieved.
145      *
146      * @return the index of the item to be retrieved next
147      */
148     public int nextIndex() {
149         return this.index - this.startIndex;
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     public int previousIndex() {
158         return this.index - this.startIndex - 1;
159     }
160
161     /**
162      * This iterator does not support modification of its backing array's size, and so will
163      * always throw an {@link UnsupportedOperationException} when this method is invoked.
164      *
165      * @param obj the object to add
166      * @throws UnsupportedOperationException always thrown.
167      */
168     public void add(Object JavaDoc obj) {
169         throw new UnsupportedOperationException JavaDoc("add() method is not supported");
170     }
171
172     /**
173      * Sets the element under the cursor.
174      * <p>
175      * This method sets the element that was returned by the last call
176      * to {@link #next()} of {@link #previous()}.
177      *
178      * <b>Note:</b> {@link ListIterator} implementations that support <code>add()</code>
179      * and <code>remove()</code> only allow <code>set()</code> to be called once per call
180      * to <code>next()</code> or <code>previous</code> (see the {@link ListIterator}
181      * javadoc for more details). Since this implementation does not support
182      * <code>add()</code> or <code>remove()</code>, <code>set()</code> may be
183      * called as often as desired.
184      *
185      * @param obj the object to set into the array
186      * @throws IllegalStateException if next() has not yet been called.
187      * @throws ClassCastException if the object type is unsuitable for the array
188      */
189     public void set(Object JavaDoc obj) {
190         if (this.lastItemIndex == -1) {
191             throw new IllegalStateException JavaDoc("must call next() or previous() before a call to set()");
192         }
193
194         this.array[this.lastItemIndex] = obj;
195     }
196
197     /**
198      * Resets the iterator back to the start index.
199      */
200     public void reset() {
201         super.reset();
202         this.lastItemIndex = -1;
203     }
204
205 }
206
Popular Tags