1. /*

  2.  * @(#)AbstractSequentialList.java	1.21 00/02/02

  3.  *

  4.  * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.util;

  12. 

  13. /**

  14.  * This class provides a skeletal implementation of the <tt>List</tt>

  15.  * interface to minimize the effort required to implement this interface

  16.  * backed by a "sequential access" data store (such as a linked list).  For

  17.  * random access data (such as an array), <tt>AbstractList</tt> should be used

  18.  * in preference to this class.<p>

  19.  *

  20.  * This class is the opposite of the <tt>AbstractList</tt> class in the sense

  21.  * that it implements the "random access" methods (<tt>get(int index)</tt>,

  22.  * <tt>set(int index, Object element)</tt>, <tt>set(int index, Object

  23.  * element)</tt>, <tt>add(int index, Object element)</tt> and <tt>remove(int

  24.  * index)</tt>) on top of the list's list iterator, instead of the other way

  25.  * around.<p>

  26.  *

  27.  * To implement a list the programmer needs only to extend this class and

  28.  * provide implementations for the <tt>listIterator</tt> and <tt>size</tt>

  29.  * methods.  For an unmodifiable list, the programmer need only implement the

  30.  * list iterator's <tt>hasNext</tt>, <tt>next</tt>, <tt>hasPrevious</tt>,

  31.  * <tt>previous</tt> and <tt>index</tt> methods.<p>

  32.  *

  33.  * For a modifiable list the programmer should additionally implement the list

  34.  * iterator's <tt>set</tt> method.  For a variable-size list the programmer

  35.  * should additionally implement the list iterator's <tt>remove</tt> and

  36.  * <tt>add</tt> methods.<p>

  37.  *

  38.  * The programmer should generally provide a void (no argument) and collection

  39.  * constructor, as per the recommendation in the <tt>Collection</tt> interface

  40.  * specification.

  41.  *

  42.  * @author  Josh Bloch

  43.  * @version 1.21, 02/02/00

  44.  * @see Collection

  45.  * @see List

  46.  * @see AbstractList

  47.  * @see AbstractCollection

  48.  * @since 1.2

  49.  */

  50. 

  51. public abstract class AbstractSequentialList extends AbstractList {

  52.     /**

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

  54.      * implicit.)

  55.      */

  56.     protected AbstractSequentialList() {

  57.     }

  58. 

  59.     /**

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

  61.      *

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

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

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

  65.      *

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

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

  68.      * 		  IndexOutOfBoundsException if the specified index is out of

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

  70.      */

  71.     public Object get(int index) {

  72. 	ListIterator e = listIterator(index);

  73. 	try {

  74. 	    return(e.next());

  75. 	} catch(NoSuchElementException exc) {

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

  77. 	}

  78.     }

  79. 

  80.     /**

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

  82.      * specified element. <p>

  83.      *

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

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

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

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

  88.      *

  89.      * Note that this implementation will throw an

  90.      * UnsupportedOperationException if list iterator does not implement

  91.      * the set operation.

  92.      *

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

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

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

  96.      * @throws    UnsupportedOperationException set is not supported

  97.      *		  by this list.

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

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

  100.      * @throws    ClassCastException class of the specified element

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

  102.      * @throws    IllegalArgumentException some aspect of the specified

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

  104.      * @throws    IndexOutOfBoundsException index out of range

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

  106.      * @throws    IllegalArgumentException fromIndex > toIndex.

  107.      */

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

  109. 	ListIterator e = listIterator(index);

  110. 	try {

  111. 	    Object oldVal = e.next();

  112. 	    e.set(element);

  113. 	    return oldVal;

  114. 	} catch(NoSuchElementException exc) {

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

  116. 	}

  117.     }

  118. 

  119.     /**

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

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

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

  123.      *

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

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

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

  127.      *

  128.      * Note that this implementation will throw an

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

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

  131.      *

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

  133.      * @param element element to be inserted.

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

  135.      *		  not supported by this list.

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

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

  138.      * 		  <tt>null</tt>.

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

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

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

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

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

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

  145.      */

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

  147. 	ListIterator e = listIterator(index);

  148. 	e.add(element);

  149.     }

  150. 

  151.     /**

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

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

  154.      *

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

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

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

  158.      *

  159.      * Note that this implementation will throw an

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

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

  162.      *

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

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

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

  166.      *		  is not supported by this list.

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

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

  169.      */

  170.     public Object remove(int index) {

  171. 	ListIterator e = listIterator(index);

  172. 	Object outCast;

  173. 	try {

  174. 	    outCast = e.next();

  175. 	} catch(NoSuchElementException exc) {

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

  177. 	}

  178. 	e.remove();

  179. 	return(outCast);

  180.     }

  181. 

  182. 

  183.     // Bulk Operations

  184. 

  185.     /**

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

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

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

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

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

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

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

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

  194.      * Optional operation.<p>

  195.      *

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

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

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

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

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

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

  202.      *

  203.      * Note that this implementation will throw an

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

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

  206.      * operation.

  207.      *

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

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

  210.      *		    collection.

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

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

  213.      *		  is not supported by this list.

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

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

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

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

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

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

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

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

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

  223.      */

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

  225. 	boolean modified = false;

  226. 	ListIterator e1 = listIterator(index);

  227. 	Iterator e2 = c.iterator();

  228. 	while (e2.hasNext()) {

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

  230. 	    modified = true;

  231. 	}

  232. 	return modified;

  233.     }

  234. 

  235. 

  236.     // Iterators

  237. 

  238.     /**

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

  240.      * sequence).<p> 

  241.      *

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

  243.      *

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

  245.      */

  246.     public Iterator iterator() {

  247.         return listIterator();

  248.     }

  249. 

  250.     /**

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

  252.      * sequence).

  253.      *

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

  255.      *      sequence).

  256.      */

  257.     public abstract ListIterator listIterator(int index);

  258. }