001: /*
002: * @(#)AbstractSequentialList.java 1.28 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.util;
029:
030: /**
031: * This class provides a skeletal implementation of the <tt>List</tt>
032: * interface to minimize the effort required to implement this interface
033: * backed by a "sequential access" data store (such as a linked list). For
034: * random access data (such as an array), <tt>AbstractList</tt> should be used
035: * in preference to this class.<p>
036: *
037: * This class is the opposite of the <tt>AbstractList</tt> class in the sense
038: * that it implements the "random access" methods (<tt>get(int index)</tt>,
039: * <tt>set(int index, Object element)</tt>, <tt>set(int index, Object
040: * element)</tt>, <tt>add(int index, Object element)</tt> and <tt>remove(int
041: * index)</tt>) on top of the list's list iterator, instead of the other way
042: * around.<p>
043: *
044: * To implement a list the programmer needs only to extend this class and
045: * provide implementations for the <tt>listIterator</tt> and <tt>size</tt>
046: * methods. For an unmodifiable list, the programmer need only implement the
047: * list iterator's <tt>hasNext</tt>, <tt>next</tt>, <tt>hasPrevious</tt>,
048: * <tt>previous</tt> and <tt>index</tt> methods.<p>
049: *
050: * For a modifiable list the programmer should additionally implement the list
051: * iterator's <tt>set</tt> method. For a variable-size list the programmer
052: * should additionally implement the list iterator's <tt>remove</tt> and
053: * <tt>add</tt> methods.<p>
054: *
055: * The programmer should generally provide a void (no argument) and collection
056: * constructor, as per the recommendation in the <tt>Collection</tt> interface
057: * specification.<p>
058: *
059: * This class is a member of the
060: * <a href="{@docRoot}/../guide/collections/index.html">
061: * Java Collections Framework</a>.
062: *
063: * @author Josh Bloch
064: * @version 1.21, 02/02/00
065: * @see Collection
066: * @see List
067: * @see AbstractList
068: * @see AbstractCollection
069: * @since 1.2
070: */
071:
072: public abstract class AbstractSequentialList extends AbstractList {
073: /**
074: * Sole constructor. (For invocation by subclass constructors, typically
075: * implicit.)
076: */
077: protected AbstractSequentialList() {
078: }
079:
080: /**
081: * Returns the element at the specified position in this list. <p>
082: *
083: * This implementation first gets a list iterator pointing to the indexed
084: * element (with <tt>listIterator(index)</tt>). Then, it gets the element
085: * using <tt>ListIterator.next</tt> and returns it.
086: * @param index index of element to return.
087: *
088: * @return the element at the specified position in this list.
089: * @throws IndexOutOfBoundsException if the specified index is out of
090: * range (<tt>index < 0 || index >= size()</tt>).
091: */
092: public Object get(int index) {
093: ListIterator e = listIterator(index);
094: try {
095: return (e.next());
096: } catch (NoSuchElementException exc) {
097: throw (new IndexOutOfBoundsException("Index: " + index));
098: }
099: }
100:
101: /**
102: * Replaces the element at the specified position in this list with the
103: * specified element. <p>
104: *
105: * This implementation first gets a list iterator pointing to the
106: * indexed element (with <tt>listIterator(index)</tt>). Then, it gets
107: * the current element using <tt>ListIterator.next</tt> and replaces it
108: * with <tt>ListIterator.set</tt>.<p>
109: *
110: * Note that this implementation will throw an
111: * UnsupportedOperationException if list iterator does not implement
112: * the set operation.
113: *
114: * @param index index of element to replace.
115: * @param element element to be stored at the specified position.
116: * @return the element previously at the specified position.
117: * @throws UnsupportedOperationException set is not supported
118: * by this list.
119: * @throws NullPointerException this list does not permit null
120: * elements and one of the elements of <code>c</code> is null.
121: * @throws ClassCastException class of the specified element
122: * prevents it from being added to this list.
123: * @throws IllegalArgumentException some aspect of the specified
124: * element prevents it from being added to this list.
125: * @throws IndexOutOfBoundsException index out of range
126: * <tt>(index < 0 || index >= size()</tt>).
127: * @throws IllegalArgumentException fromIndex > toIndex.
128: */
129: public Object set(int index, Object element) {
130: ListIterator e = listIterator(index);
131: try {
132: Object oldVal = e.next();
133: e.set(element);
134: return oldVal;
135: } catch (NoSuchElementException exc) {
136: throw (new IndexOutOfBoundsException("Index: " + index));
137: }
138: }
139:
140: /**
141: * Inserts the specified element at the specified position in this list.
142: * Shifts the element currently at that position (if any) and any
143: * subsequent elements to the right (adds one to their indices).<p>
144: *
145: * This implementation first gets a list iterator pointing to the
146: * indexed element (with <tt>listIterator(index)</tt>). Then, it inserts
147: * the specified element with <tt>ListIterator.add</tt>.<p>
148: *
149: * Note that this implementation will throw an
150: * <tt>UnsupportedOperationException</tt> if list iterator does not
151: * implement the <tt>add</tt> operation.
152: *
153: * @param index index at which the specified element is to be inserted.
154: * @param element element to be inserted.
155: * @throws UnsupportedOperationException if the <tt>add</tt> operation is
156: * not supported by this list.
157: * @throws NullPointerException this list does not permit <tt>null</tt>
158: * elements and one of the elements of <code>c</code> is
159: * <tt>null</tt>.
160: * @throws ClassCastException if the class of the specified element
161: * prevents it from being added to this list.
162: * @throws IllegalArgumentException if some aspect of the specified
163: * element prevents it from being added to this list.
164: * @throws IndexOutOfBoundsException if the specified index is out of
165: * range (<tt>index < 0 || index > size()</tt>).
166: */
167: public void add(int index, Object element) {
168: ListIterator e = listIterator(index);
169: e.add(element);
170: }
171:
172: /**
173: * Removes the element at the specified position in this list. Shifts any
174: * subsequent elements to the left (subtracts one from their indices).<p>
175: *
176: * This implementation first gets a list iterator pointing to the
177: * indexed element (with <tt>listIterator(index)</tt>). Then, it removes
178: * the element with <tt>ListIterator.remove</tt>.<p>
179: *
180: * Note that this implementation will throw an
181: * <tt>UnsupportedOperationException</tt> if list iterator does not
182: * implement the <tt>remove</tt> operation.
183: *
184: * @param index index of the element to be removed from the List.
185: * @return the element that was removed from the list.
186: * @throws UnsupportedOperationException if the <tt>remove</tt> operation
187: * is not supported by this list.
188: * @throws IndexOutOfBoundsException if the specified index is out of
189: * range (index < 0 || index >= size()).
190: */
191: public Object remove(int index) {
192: ListIterator e = listIterator(index);
193: Object outCast;
194: try {
195: outCast = e.next();
196: } catch (NoSuchElementException exc) {
197: throw (new IndexOutOfBoundsException("Index: " + index));
198: }
199: e.remove();
200: return (outCast);
201: }
202:
203: // Bulk Operations
204:
205: /**
206: * Inserts all of the elements in in the specified collection into this
207: * list at the specified position. Shifts the element currently at that
208: * position (if any) and any subsequent elements to the right (increases
209: * their indices). The new elements will appear in the list in the order
210: * that they are returned by the specified collection's iterator. The
211: * behavior of this operation is unspecified if the specified collection
212: * is modified while the operation is in progress. (Note that this will
213: * occur if the specified collection is this list, and it's nonempty.)
214: * Optional operation.<p>
215: *
216: * This implementation gets an iterator over the specified collection and
217: * a list iterator over this list pointing to the indexed element (with
218: * <tt>listIterator(index)</tt>). Then, it iterates over the specified
219: * collection, inserting the elements obtained from the iterator into this
220: * list, one at a time, using <tt>ListIterator.add</tt> followed by
221: * <tt>ListIterator.next</tt> (to skip over the added element).<p>
222: *
223: * Note that this implementation will throw an
224: * <tt>UnsupportedOperationException</tt> if the list iterator returned by
225: * the <tt>listIterator</tt> method does not implement the <tt>add</tt>
226: * operation.
227: *
228: * @return <tt>true</tt> if this list changed as a result of the call.
229: * @param index index at which to insert first element from the specified
230: * collection.
231: * @param c elements to be inserted into this list.
232: * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
233: * is not supported by this list.
234: * @throws NullPointerException this list does not permit <tt>null</tt>
235: * elements and one of the elements of the specified collection
236: * is <tt>null</tt>.
237: * @throws ClassCastException if the class of the specified element
238: * prevents it from being added to this list.
239: * @throws IllegalArgumentException if some aspect of the specified
240: * element prevents it from being added to this list.
241: * @throws IndexOutOfBoundsException if the specified index is out of
242: * range (<tt>index < 0 || index > size()</tt>).
243: * @throws NullPointerException if the specified collection is null.
244: */
245: public boolean addAll(int index, Collection c) {
246: boolean modified = false;
247: ListIterator e1 = listIterator(index);
248: Iterator e2 = c.iterator();
249: while (e2.hasNext()) {
250: e1.add(e2.next());
251: modified = true;
252: }
253: return modified;
254: }
255:
256: // Iterators
257:
258: /**
259: * Returns an iterator over the elements in this list (in proper
260: * sequence).<p>
261: *
262: * This implementation merely returns a list iterator over the list.
263: *
264: * @return an iterator over the elements in this list (in proper sequence).
265: */
266: public Iterator iterator() {
267: return listIterator();
268: }
269:
270: /**
271: * Returns a list iterator over the elements in this list (in proper
272: * sequence).
273: *
274: * @param index index of first element to be returned from the list
275: * iterator (by a call to the <code>next</code> method)
276: * @return a list iterator over the elements in this list (in proper
277: * sequence).
278: */
279: public abstract ListIterator listIterator(int index);
280: }
|