1. /*

  2.  * @(#)AbstractSequentialList.java	1.27 03/01/23

  3.  *

  4.  * Copyright 2003 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.  * @version 1.27, 01/23/03

  45.  * @see Collection

  46.  * @see List

  47.  * @see AbstractList

  48.  * @see AbstractCollection

  49.  * @since 1.2

  50.  */

  51. 

  52. public abstract class AbstractSequentialList extends AbstractList {

  53.     /**

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

  55.      * implicit.)

  56.      */

  57.     protected AbstractSequentialList() {

  58.     }

  59. 

  60.     /**

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

  62.      *

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

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

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

  66.      * @param index index of element to return.

  67.      *

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

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

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

  71.      */

  72.     public Object get(int index) {

  73. 	ListIterator e = listIterator(index);

  74. 	try {

  75. 	    return(e.next());

  76. 	} catch(NoSuchElementException exc) {

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

  78. 	}

  79.     }

  80. 

  81.     /**

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

  83.      * specified element. <p>

  84.      *

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

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

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

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

  89.      *

  90.      * Note that this implementation will throw an

  91.      * UnsupportedOperationException if list iterator does not implement

  92.      * the set operation.

  93.      *

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

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

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

  97.      * @throws    UnsupportedOperationException set is not supported

  98.      *		  by this list.

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

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

  101.      * @throws    ClassCastException class of the specified element

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

  103.      * @throws    IllegalArgumentException some aspect of the specified

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

  105.      * @throws    IndexOutOfBoundsException index out of range

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

  107.      * @throws    IllegalArgumentException fromIndex > toIndex.

  108.      */

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

  110. 	ListIterator e = listIterator(index);

  111. 	try {

  112. 	    Object oldVal = e.next();

  113. 	    e.set(element);

  114. 	    return oldVal;

  115. 	} catch(NoSuchElementException exc) {

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

  117. 	}

  118.     }

  119. 

  120.     /**

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

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

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

  124.      *

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

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

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

  128.      *

  129.      * Note that this implementation will throw an

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

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

  132.      *

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

  134.      * @param element element to be inserted.

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

  136.      *		  not supported by this list.

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

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

  139.      * 		  <tt>null</tt>.

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

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

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

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

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

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

  146.      */

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

  148. 	ListIterator e = listIterator(index);

  149. 	e.add(element);

  150.     }

  151. 

  152.     /**

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

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

  155.      *

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

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

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

  159.      *

  160.      * Note that this implementation will throw an

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

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

  163.      *

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

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

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

  167.      *		  is not supported by this list.

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

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

  170.      */

  171.     public Object remove(int index) {

  172. 	ListIterator e = listIterator(index);

  173. 	Object outCast;

  174. 	try {

  175. 	    outCast = e.next();

  176. 	} catch(NoSuchElementException exc) {

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

  178. 	}

  179. 	e.remove();

  180. 	return(outCast);

  181.     }

  182. 

  183. 

  184.     // Bulk Operations

  185. 

  186.     /**

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

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

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

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

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

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

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

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

  195.      * Optional operation.<p>

  196.      *

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

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

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

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

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

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

  203.      *

  204.      * Note that this implementation will throw an

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

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

  207.      * operation.

  208.      *

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

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

  211.      *		    collection.

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

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

  214.      *		  is not supported by this list.

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

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

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

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

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

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

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

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

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

  224.      * @throws NullPointerException if the specified collection is null.

  225.      */

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

  227. 	boolean modified = false;

  228. 	ListIterator e1 = listIterator(index);

  229. 	Iterator e2 = c.iterator();

  230. 	while (e2.hasNext()) {

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

  232. 	    modified = true;

  233. 	}

  234. 	return modified;

  235.     }

  236. 

  237. 

  238.     // Iterators

  239. 

  240.     /**

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

  242.      * sequence).<p> 

  243.      *

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

  245.      *

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

  247.      */

  248.     public Iterator iterator() {

  249.         return listIterator();

  250.     }

  251. 

  252.     /**

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

  254.      * sequence).

  255.      *

  256.      * @param  index index of first element to be returned from the list 

  257.      *		iterator (by a call to the <code>next</code> method)

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

  259.      *      sequence).

  260.      */

  261.     public abstract ListIterator listIterator(int index);

  262. }