KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > util > AbstractSequentialList


1 /*
2  * @(#)AbstractSequentialList.java 1.33 04/02/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.util;
9
10 /**
11  * This class provides a skeletal implementation of the <tt>List</tt>
12  * interface to minimize the effort required to implement this interface
13  * backed by a "sequential access" data store (such as a linked list). For
14  * random access data (such as an array), <tt>AbstractList</tt> should be used
15  * in preference to this class.<p>
16  *
17  * This class is the opposite of the <tt>AbstractList</tt> class in the sense
18  * that it implements the "random access" methods (<tt>get(int index)</tt>,
19  * <tt>set(int index, Object element)</tt>, <tt>set(int index, Object
20  * element)</tt>, <tt>add(int index, Object element)</tt> and <tt>remove(int
21  * index)</tt>) on top of the list's list iterator, instead of the other way
22  * around.<p>
23  *
24  * To implement a list the programmer needs only to extend this class and
25  * provide implementations for the <tt>listIterator</tt> and <tt>size</tt>
26  * methods. For an unmodifiable list, the programmer need only implement the
27  * list iterator's <tt>hasNext</tt>, <tt>next</tt>, <tt>hasPrevious</tt>,
28  * <tt>previous</tt> and <tt>index</tt> methods.<p>
29  *
30  * For a modifiable list the programmer should additionally implement the list
31  * iterator's <tt>set</tt> method. For a variable-size list the programmer
32  * should additionally implement the list iterator's <tt>remove</tt> and
33  * <tt>add</tt> methods.<p>
34  *
35  * The programmer should generally provide a void (no argument) and collection
36  * constructor, as per the recommendation in the <tt>Collection</tt> interface
37  * specification.<p>
38  *
39  * This class is a member of the
40  * <a HREF="{@docRoot}/../guide/collections/index.html">
41  * Java Collections Framework</a>.
42  *
43  * @author Josh Bloch
44  * @author Neal Gafter
45  * @version 1.33, 02/19/04
46  * @see Collection
47  * @see List
48  * @see AbstractList
49  * @see AbstractCollection
50  * @since 1.2
51  */

52
53 public abstract class AbstractSequentialList<E> extends AbstractList JavaDoc<E> {
54     /**
55      * Sole constructor. (For invocation by subclass constructors, typically
56      * implicit.)
57      */

58     protected AbstractSequentialList() {
59     }
60
61     /**
62      * Returns the element at the specified position in this list. <p>
63      *
64      * This implementation first gets a list iterator pointing to the indexed
65      * element (with <tt>listIterator(index)</tt>). Then, it gets the element
66      * using <tt>ListIterator.next</tt> and returns it.
67      * @param index index of element to return.
68      *
69      * @return the element at the specified position in this list.
70      * @throws IndexOutOfBoundsException if the specified index is out of
71      * range (<tt>index &lt; 0 || index &gt;= size()</tt>).
72      */

73     public E get(int index) {
74     ListIterator JavaDoc<E> e = listIterator(index);
75     try {
76         return(e.next());
77     } catch(NoSuchElementException JavaDoc exc) {
78         throw(new IndexOutOfBoundsException JavaDoc("Index: "+index));
79     }
80     }
81
82     /**
83      * Replaces the element at the specified position in this list with the
84      * specified element. <p>
85      *
86      * This implementation first gets a list iterator pointing to the
87      * indexed element (with <tt>listIterator(index)</tt>). Then, it gets
88      * the current element using <tt>ListIterator.next</tt> and replaces it
89      * with <tt>ListIterator.set</tt>.<p>
90      *
91      * Note that this implementation will throw an
92      * UnsupportedOperationException if list iterator does not implement
93      * the set operation.
94      *
95      * @param index index of element to replace.
96      * @param element element to be stored at the specified position.
97      * @return the element previously at the specified position.
98      * @throws UnsupportedOperationException set is not supported
99      * by this list.
100      * @throws NullPointerException this list does not permit null
101      * elements and one of the elements of <code>c</code> is null.
102      * @throws ClassCastException class of the specified element
103      * prevents it from being added to this list.
104      * @throws IllegalArgumentException some aspect of the specified
105      * element prevents it from being added to this list.
106      * @throws IndexOutOfBoundsException index out of range
107      * <tt>(index &lt; 0 || index &gt;= size()</tt>).
108      * @throws IllegalArgumentException fromIndex &gt; toIndex.
109      */

110     public E set(int index, E element) {
111     ListIterator JavaDoc<E> e = listIterator(index);
112     try {
113         E oldVal = e.next();
114         e.set(element);
115         return oldVal;
116     } catch(NoSuchElementException JavaDoc exc) {
117         throw(new IndexOutOfBoundsException JavaDoc("Index: "+index));
118     }
119     }
120
121     /**
122      * Inserts the specified element at the specified position in this list.
123      * Shifts the element currently at that position (if any) and any
124      * subsequent elements to the right (adds one to their indices).<p>
125      *
126      * This implementation first gets a list iterator pointing to the
127      * indexed element (with <tt>listIterator(index)</tt>). Then, it inserts
128      * the specified element with <tt>ListIterator.add</tt>.<p>
129      *
130      * Note that this implementation will throw an
131      * <tt>UnsupportedOperationException</tt> if list iterator does not
132      * implement the <tt>add</tt> operation.
133      *
134      * @param index index at which the specified element is to be inserted.
135      * @param element element to be inserted.
136      * @throws UnsupportedOperationException if the <tt>add</tt> operation is
137      * not supported by this list.
138      * @throws NullPointerException this list does not permit <tt>null</tt>
139      * elements and one of the elements of <code>c</code> is
140      * <tt>null</tt>.
141      * @throws ClassCastException if the class of the specified element
142      * prevents it from being added to this list.
143      * @throws IllegalArgumentException if some aspect of the specified
144      * element prevents it from being added to this list.
145      * @throws IndexOutOfBoundsException if the specified index is out of
146      * range (<tt>index &lt; 0 || index &gt; size()</tt>).
147      */

148     public void add(int index, E element) {
149     ListIterator JavaDoc<E> e = listIterator(index);
150     e.add(element);
151     }
152
153     /**
154      * Removes the element at the specified position in this list. Shifts any
155      * subsequent elements to the left (subtracts one from their indices).<p>
156      *
157      * This implementation first gets a list iterator pointing to the
158      * indexed element (with <tt>listIterator(index)</tt>). Then, it removes
159      * the element with <tt>ListIterator.remove</tt>.<p>
160      *
161      * Note that this implementation will throw an
162      * <tt>UnsupportedOperationException</tt> if list iterator does not
163      * implement the <tt>remove</tt> operation.
164      *
165      * @param index index of the element to be removed from the List.
166      * @return the element that was removed from the list.
167      * @throws UnsupportedOperationException if the <tt>remove</tt> operation
168      * is not supported by this list.
169      * @throws IndexOutOfBoundsException if the specified index is out of
170      * range (index &lt; 0 || index &gt;= size()).
171      */

172     public E remove(int index) {
173     ListIterator JavaDoc<E> e = listIterator(index);
174     E outCast;
175     try {
176         outCast = e.next();
177     } catch(NoSuchElementException JavaDoc exc) {
178         throw(new IndexOutOfBoundsException JavaDoc("Index: "+index));
179     }
180     e.remove();
181     return(outCast);
182     }
183
184
185     // Bulk Operations
186

187     /**
188      * Inserts all of the elements in the specified collection into this
189      * list at the specified position. Shifts the element currently at that
190      * position (if any) and any subsequent elements to the right (increases
191      * their indices). The new elements will appear in the list in the order
192      * that they are returned by the specified collection's iterator. The
193      * behavior of this operation is unspecified if the specified collection
194      * is modified while the operation is in progress. (Note that this will
195      * occur if the specified collection is this list, and it's nonempty.)
196      * Optional operation.<p>
197      *
198      * This implementation gets an iterator over the specified collection and
199      * a list iterator over this list pointing to the indexed element (with
200      * <tt>listIterator(index)</tt>). Then, it iterates over the specified
201      * collection, inserting the elements obtained from the iterator into this
202      * list, one at a time, using <tt>ListIterator.add</tt> followed by
203      * <tt>ListIterator.next</tt> (to skip over the added element).<p>
204      *
205      * Note that this implementation will throw an
206      * <tt>UnsupportedOperationException</tt> if the list iterator returned by
207      * the <tt>listIterator</tt> method does not implement the <tt>add</tt>
208      * operation.
209      *
210      * @return <tt>true</tt> if this list changed as a result of the call.
211      * @param index index at which to insert first element from the specified
212      * collection.
213      * @param c elements to be inserted into this list.
214      * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
215      * is not supported by this list.
216      * @throws NullPointerException this list does not permit <tt>null</tt>
217      * elements and one of the elements of the specified collection
218      * is <tt>null</tt>.
219      * @throws ClassCastException if the class of the specified element
220      * prevents it from being added to this list.
221      * @throws IllegalArgumentException if some aspect of the specified
222      * element prevents it from being added to this list.
223      * @throws IndexOutOfBoundsException if the specified index is out of
224      * range (<tt>index &lt; 0 || index &gt; size()</tt>).
225      * @throws NullPointerException if the specified collection is null.
226      */

227     public boolean addAll(int index, Collection JavaDoc<? extends E> c) {
228     boolean modified = false;
229     ListIterator JavaDoc<E> e1 = listIterator(index);
230     Iterator JavaDoc<? extends E> e2 = c.iterator();
231     while (e2.hasNext()) {
232         e1.add(e2.next());
233         modified = true;
234     }
235     return modified;
236     }
237
238
239     // Iterators
240

241     /**
242      * Returns an iterator over the elements in this list (in proper
243      * sequence).<p>
244      *
245      * This implementation merely returns a list iterator over the list.
246      *
247      * @return an iterator over the elements in this list (in proper sequence).
248      */

249     public Iterator JavaDoc<E> iterator() {
250         return listIterator();
251     }
252
253     /**
254      * Returns a list iterator over the elements in this list (in proper
255      * sequence).
256      *
257      * @param index index of first element to be returned from the list
258      * iterator (by a call to the <code>next</code> method)
259      * @return a list iterator over the elements in this list (in proper
260      * sequence).
261      */

262     public abstract ListIterator JavaDoc<E> listIterator(int index);
263 }
264
Popular Tags