/* * @(#)AbstractSequentialList.java 1.33 04/02/19 * * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package java.util; /** * This class provides a skeletal implementation of the List * interface to minimize the effort required to implement this interface * backed by a "sequential access" data store (such as a linked list). For * random access data (such as an array), AbstractList should be used * in preference to this class.

* * This class is the opposite of the AbstractList class in the sense * that it implements the "random access" methods (get(int index), * set(int index, Object element), set(int index, Object * element), add(int index, Object element) and remove(int * index)) on top of the list's list iterator, instead of the other way * around.

* * To implement a list the programmer needs only to extend this class and * provide implementations for the listIterator and size * methods. For an unmodifiable list, the programmer need only implement the * list iterator's hasNext, next, hasPrevious, * previous and index methods.

* * For a modifiable list the programmer should additionally implement the list * iterator's set method. For a variable-size list the programmer * should additionally implement the list iterator's remove and * add methods.

* * The programmer should generally provide a void (no argument) and collection * constructor, as per the recommendation in the Collection interface * specification.

* * This class is a member of the * * Java Collections Framework. * * @author Josh Bloch * @author Neal Gafter * @version 1.33, 02/19/04 * @see Collection * @see List * @see AbstractList * @see AbstractCollection * @since 1.2 */ public abstract class AbstractSequentialList extends AbstractList { /** * Sole constructor. (For invocation by subclass constructors, typically * implicit.) */ protected AbstractSequentialList() { } /** * Returns the element at the specified position in this list.

* * This implementation first gets a list iterator pointing to the indexed * element (with listIterator(index)). Then, it gets the element * using ListIterator.next and returns it. * @param index index of element to return. * * @return the element at the specified position in this list. * @throws IndexOutOfBoundsException if the specified index is out of * range (index < 0 || index >= size()). */ public E get(int index) { ListIterator e = listIterator(index); try { return(e.next()); } catch(NoSuchElementException exc) { throw(new IndexOutOfBoundsException("Index: "+index)); } } /** * Replaces the element at the specified position in this list with the * specified element.

* * This implementation first gets a list iterator pointing to the * indexed element (with listIterator(index)). Then, it gets * the current element using ListIterator.next and replaces it * with ListIterator.set.

* * Note that this implementation will throw an * UnsupportedOperationException if list iterator does not implement * the set operation. * * @param index index of element to replace. * @param element element to be stored at the specified position. * @return the element previously at the specified position. * @throws UnsupportedOperationException set is not supported * by this list. * @throws NullPointerException this list does not permit null * elements and one of the elements of c is null. * @throws ClassCastException class of the specified element * prevents it from being added to this list. * @throws IllegalArgumentException some aspect of the specified * element prevents it from being added to this list. * @throws IndexOutOfBoundsException index out of range * (index < 0 || index >= size()). * @throws IllegalArgumentException fromIndex > toIndex. */ public E set(int index, E element) { ListIterator e = listIterator(index); try { E oldVal = e.next(); e.set(element); return oldVal; } catch(NoSuchElementException exc) { throw(new IndexOutOfBoundsException("Index: "+index)); } } /** * Inserts the specified element at the specified position in this list. * Shifts the element currently at that position (if any) and any * subsequent elements to the right (adds one to their indices).

* * This implementation first gets a list iterator pointing to the * indexed element (with listIterator(index)). Then, it inserts * the specified element with ListIterator.add.

* * Note that this implementation will throw an * UnsupportedOperationException if list iterator does not * implement the add operation. * * @param index index at which the specified element is to be inserted. * @param element element to be inserted. * @throws UnsupportedOperationException if the add operation is * not supported by this list. * @throws NullPointerException this list does not permit null * elements and one of the elements of c is * null. * @throws ClassCastException if the class of the specified element * prevents it from being added to this list. * @throws IllegalArgumentException if some aspect of the specified * element prevents it from being added to this list. * @throws IndexOutOfBoundsException if the specified index is out of * range (index < 0 || index > size()). */ public void add(int index, E element) { ListIterator e = listIterator(index); e.add(element); } /** * Removes the element at the specified position in this list. Shifts any * subsequent elements to the left (subtracts one from their indices).

* * This implementation first gets a list iterator pointing to the * indexed element (with listIterator(index)). Then, it removes * the element with ListIterator.remove.

* * Note that this implementation will throw an * UnsupportedOperationException if list iterator does not * implement the remove operation. * * @param index index of the element to be removed from the List. * @return the element that was removed from the list. * @throws UnsupportedOperationException if the remove operation * is not supported by this list. * @throws IndexOutOfBoundsException if the specified index is out of * range (index < 0 || index >= size()). */ public E remove(int index) { ListIterator e = listIterator(index); E outCast; try { outCast = e.next(); } catch(NoSuchElementException exc) { throw(new IndexOutOfBoundsException("Index: "+index)); } e.remove(); return(outCast); } // Bulk Operations /** * Inserts all of the elements in the specified collection into this * list at the specified position. Shifts the element currently at that * position (if any) and any subsequent elements to the right (increases * their indices). The new elements will appear in the list in the order * that they are returned by the specified collection's iterator. The * behavior of this operation is unspecified if the specified collection * is modified while the operation is in progress. (Note that this will * occur if the specified collection is this list, and it's nonempty.) * Optional operation.

* * This implementation gets an iterator over the specified collection and * a list iterator over this list pointing to the indexed element (with * listIterator(index)). Then, it iterates over the specified * collection, inserting the elements obtained from the iterator into this * list, one at a time, using ListIterator.add followed by * ListIterator.next (to skip over the added element).

* * Note that this implementation will throw an * UnsupportedOperationException if the list iterator returned by * the listIterator method does not implement the add * operation. * * @return true if this list changed as a result of the call. * @param index index at which to insert first element from the specified * collection. * @param c elements to be inserted into this list. * @throws UnsupportedOperationException if the addAll operation * is not supported by this list. * @throws NullPointerException this list does not permit null * elements and one of the elements of the specified collection * is null. * @throws ClassCastException if the class of the specified element * prevents it from being added to this list. * @throws IllegalArgumentException if some aspect of the specified * element prevents it from being added to this list. * @throws IndexOutOfBoundsException if the specified index is out of * range (index < 0 || index > size()). * @throws NullPointerException if the specified collection is null. */ public boolean addAll(int index, Collection c) { boolean modified = false; ListIterator e1 = listIterator(index); Iterator e2 = c.iterator(); while (e2.hasNext()) { e1.add(e2.next()); modified = true; } return modified; } // Iterators /** * Returns an iterator over the elements in this list (in proper * sequence).

* * This implementation merely returns a list iterator over the list. * * @return an iterator over the elements in this list (in proper sequence). */ public Iterator iterator() { return listIterator(); } /** * Returns a list iterator over the elements in this list (in proper * sequence). * * @param index index of first element to be returned from the list * iterator (by a call to the next method) * @return a list iterator over the elements in this list (in proper * sequence). */ public abstract ListIterator listIterator(int index); }