1. /*

  2.  * @(#)AbstractSequentialList.java	1.15 01/11/29

  3.  *

  4.  * Copyright 2002 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.

  38.  *

  39.  * @author  Josh Bloch

  40.  * @version 1.15 11/29/01

  41.  * @see Collection

  42.  * @see List

  43.  * @see AbstractList

  44.  * @see AbstractCollection

  45.  * @since JDK1.2

  46.  */

  47. 

  48. public abstract class AbstractSequentialList extends AbstractList {

  49.     /**

  50.      * Sole constructor.  (For invocation by subclass constructors, typically

  51.      * implicit.)

  52.      */

  53.     protected AbstractSequentialList() {

  54.     }

  55. 

  56.     /**

  57.      * Returns the element at the specified position in this list. <p>

  58.      *

  59.      * This implementation first gets a list iterator pointing to the indexed

  60.      * element (with <tt>listIterator(index)</tt>).  Then, it gets the element

  61.      * using <tt>ListIterator.next</tt> and returns it.

  62.      *

  63.      * @return the element at the specified position in this list.  * @param

  64.      * 		  index index of element to return.  * @throws

  65.      * 		  IndexOutOfBoundsException if the specified index is out of

  66.      * 		  range (<tt>index < 0 || index >= size()</tt>).

  67.      */

  68.     public Object get(int index) {

  69. 	ListIterator e = listIterator(index);

  70. 	try {

  71. 	    return(e.next());

  72. 	} catch(NoSuchElementException exc) {

  73. 	    throw(new IndexOutOfBoundsException("Index: "+index));

  74. 	}

  75.     }

  76. 

  77.     /**

  78.      * Replaces the element at the specified position in this list with the

  79.      * specified element. <p>

  80.      *

  81.      * This implementation first gets a list iterator pointing to the

  82.      * indexed element (with <tt>listIterator(index)</tt>).  Then, it gets

  83.      * the current element using <tt>ListIterator.next</tt> and replaces it

  84.      * with <tt>ListIterator.set</tt>.<p>

  85.      *

  86.      * Note that this implementation will throw an

  87.      * UnsupportedOperationException if list iterator does not implement

  88.      * the set operation.

  89.      *

  90.      * @param index index of element to replace.

  91.      * @param element element to be stored at the specified position.

  92.      * @return the element previously at the specified position.

  93.      * @throws    UnsupportedOperationException set is not supported

  94.      *		  by this list.

  95.      * @throws    NullPointerException this list does not permit null

  96.      * 		  elements and one of the elements of <code>c</code> is null.

  97.      * @throws    ClassCastException class of the specified element

  98.      * 		  prevents it from being added to this list.

  99.      * @throws    IllegalArgumentException some aspect of the specified

  100.      *		  element prevents it from being added to this list.

  101.      * @throws    IndexOutOfBoundsException index out of range

  102.      *		  <tt>(index < 0 || index >= size()</tt>).

  103.      * @throws    IllegalArgumentException fromIndex > toIndex.

  104.      */

  105.     public Object set(int index, Object element) {

  106. 	ListIterator e = listIterator(index);

  107. 	try {

  108. 	    Object oldVal = e.next();

  109. 	    e.set(element);

  110. 	    return oldVal;

  111. 	} catch(NoSuchElementException exc) {

  112. 	    throw(new IndexOutOfBoundsException("Index: "+index));

  113. 	}

  114.     }

  115. 

  116.     /**

  117.      * Inserts the specified element at the specified position in this list.

  118.      * Shifts the element currently at that position (if any) and any

  119.      * subsequent elements to the right (adds one to their indices).<p>

  120.      *

  121.      * This implementation first gets a list iterator pointing to the

  122.      * indexed element (with <tt>listIterator(index)</tt>).  Then, it inserts

  123.      * the specified element with <tt>ListIterator.add</tt>.<p>

  124.      *

  125.      * Note that this implementation will throw an

  126.      * <tt>UnsupportedOperationException</tt> if list iterator does not

  127.      * implement the <tt>add</tt> operation.

  128.      *

  129.      * @param index index at which the specified element is to be inserted.

  130.      * @param element element to be inserted.

  131.      * @throws UnsupportedOperationException if the <tt>add</tt> operation is

  132.      *		  not supported by this list.

  133.      * @throws NullPointerException this list does not permit <tt>null</tt>

  134.      * 		  elements and one of the elements of <code>c</code> is

  135.      * 		  <tt>null</tt>.

  136.      * @throws    ClassCastException if the class of the specified element

  137.      * 		  prevents it from being added to this list.

  138.      * @throws    IllegalArgumentException if some aspect of the specified

  139.      *		  element prevents it from being added to this list.

  140.      * @throws IndexOutOfBoundsException if the specified index is out of

  141.      *            range (<tt>index < 0 || index > size()</tt>).

  142.      */

  143.     public void add(int index, Object element) {

  144. 	ListIterator e = listIterator(index);

  145. 	e.add(element);

  146.     }

  147. 

  148.     /**

  149.      * Removes the element at the specified position in this list.  Shifts any

  150.      * subsequent elements to the left (subtracts one from their indices).<p>

  151.      *

  152.      * This implementation first gets a list iterator pointing to the

  153.      * indexed element (with <tt>listIterator(index)</tt>).  Then, it removes

  154.      * the element with <tt>ListIterator.remove</tt>.<p>

  155.      *

  156.      * Note that this implementation will throw an

  157.      * <tt>UnsupportedOperationException</tt> if list iterator does not

  158.      * implement the <tt>remove</tt> operation.

  159.      *

  160.      * @param the index of the element to be removed from the List.

  161.      * @return the element that was removed from the list.

  162.      * @throws UnsupportedOperationException if the <tt>remove</tt> operation

  163.      *		  is not supported by this list.

  164.      * @throws IndexOutOfBoundsException if the specified index is out of

  165.      * 		  range (index < 0 || index >= size()).

  166.      */

  167.     public Object remove(int index) {

  168. 	ListIterator e = listIterator(index);

  169. 	Object outCast;

  170. 	try {

  171. 	    outCast = e.next();

  172. 	} catch(NoSuchElementException exc) {

  173. 	    throw(new IndexOutOfBoundsException("Index: "+index));

  174. 	}

  175. 	e.remove();

  176. 	return(outCast);

  177.     }

  178. 

  179. 

  180.     // Bulk Operations

  181. 

  182.     /**

  183.      * Inserts all of the elements in in the specified collection into this

  184.      * list at the specified position.  Shifts the element currently at that

  185.      * position (if any) and any subsequent elements to the right (increases

  186.      * their indices).  The new elements will appear in the list in the order

  187.      * that they are returned by the specified collection's iterator.  The

  188.      * behavior of this operation is unspecified if the specified collection

  189.      * is modified while the operation is in progress.  (Note that this will

  190.      * occur if the specified collection is this list, and it's nonempty.)

  191.      * Optional operation.<p>

  192.      *

  193.      * This implementation gets an iterator over the specified collection and

  194.      * a list iterator over this list pointing to the indexed element (with

  195.      * <tt>listIterator(index)</tt>).  Then, it iterates over the specified

  196.      * collection, inserting the elements obtained from the iterator into this

  197.      * list, one at a time, using <tt>ListIterator.add</tt> followed by

  198.      * <tt>ListIterator.next</tt> (to skip over the added element).<p>

  199.      *

  200.      * Note that this implementation will throw an

  201.      * <tt>UnsupportedOperationException</tt> if the list iterator returned by

  202.      * the <tt>listIterator</tt> method does not implement the <tt>add</tt>

  203.      * operation.

  204.      *

  205.      * @return <tt>true</tt> if this list changed as a result of the call.

  206.      * @param index index at which to insert first element from the specified

  207.      *		    collection.

  208.      * @param c elements to be inserted into this list.

  209.      * @throws UnsupportedOperationException if the <tt>addAll</tt> operation

  210.      *		  is not supported by this list.

  211.      * @throws NullPointerException this list does not permit <tt>null</tt>

  212.      * 		  elements and one of the elements of the specified collection

  213.      * 		  is <tt>null</tt>.

  214.      * @throws    ClassCastException if the class of the specified element

  215.      * 		  prevents it from being added to this list.

  216.      * @throws    IllegalArgumentException if some aspect of the specified

  217.      *		  element prevents it from being added to this list.

  218.      * @throws IndexOutOfBoundsException if the specified index is out of

  219.      *            range (<tt>index < 0 || index > size()</tt>).

  220.      */

  221.     public boolean addAll(int index, Collection c) {

  222. 	boolean modified = false;

  223. 	ListIterator e1 = listIterator(index);

  224. 	Iterator e2 = c.iterator();

  225. 	while (e2.hasNext()) {

  226. 	    e1.add(e2.next());

  227. 	    e1.next();	// Skip over the element that we just added

  228. 	    modified = true;

  229. 	}

  230. 	return modified;

  231.     }

  232. 

  233. 

  234.     // Iterators

  235. 

  236.     /**

  237.      * Returns an iterator over the elements in this list (in proper

  238.      * sequence).<p> 

  239.      *

  240.      * This implementation merely returns a list iterator over the list.

  241.      *

  242.      * @return an iterator over the elements in this list (in proper sequence).

  243.      */

  244.     public Iterator iterator() {

  245.         return listIterator();

  246.     }

  247. 

  248.     /**

  249.      * Returns a list iterator over the elements in this list (in proper

  250.      * sequence).

  251.      *

  252.      * @return a list iterator over the elements in this list (in proper

  253.      *      sequence).

  254.      */

  255.     public abstract ListIterator listIterator(int index);

  256. }