1 /*

     2  * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.util;

    27 

    28 /**

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

    30  * interface to minimize the effort required to implement this interface

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

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

    33  * in preference to this class.<p>

    34  *

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

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

    37  * <tt>set(int index, E element)</tt>, <tt>add(int index, E element)</tt> and

    38  * <tt>remove(int index)</tt>) on top of the list's list iterator, instead of

    39  * the other way around.<p>

    40  *

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

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

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

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

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

    46  *

    47  * For a modifiable list the programmer should additionally implement the list

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

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

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

    51  *

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

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

    54  * specification.<p>

    55  *

    56  * This class is a member of the

    57  * <a href="{@docRoot}/../technotes/guides/collections/index.html">

    58  * Java Collections Framework</a>.

    59  *

    60  * @author  Josh Bloch

    61  * @author  Neal Gafter

    62  * @see Collection

    63  * @see List

    64  * @see AbstractList

    65  * @see AbstractCollection

    66  * @since 1.2

    67  */

    68 

    69 public abstract class AbstractSequentialList<E> extends AbstractList<E> {

    70     /**

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

    72      * implicit.)

    73      */

    74     protected AbstractSequentialList() {

    75     }

    76 

    77     /**

    78      * Returns the element at the specified position in this list.

    79      *

    80      * <p>This implementation first gets a list iterator pointing to the

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

    82      * the element using <tt>ListIterator.next</tt> and returns it.

    83      *

    84      * @throws IndexOutOfBoundsException {@inheritDoc}

    85      */

    86     public E get(int index) {

    87         try {

    88             return listIterator(index).next();

    89         } catch (NoSuchElementException exc) {

    90             throw new IndexOutOfBoundsException("Index: "+index);

    91         }

    92     }

    93 

    94     /**

    95      * Replaces the element at the specified position in this list with the

    96      * specified element (optional operation).

    97      *

    98      * <p>This implementation first gets a list iterator pointing to the

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

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

   101      * with <tt>ListIterator.set</tt>.

   102      *

   103      * <p>Note that this implementation will throw an

   104      * <tt>UnsupportedOperationException</tt> if the list iterator does not

   105      * implement the <tt>set</tt> operation.

   106      *

   107      * @throws UnsupportedOperationException {@inheritDoc}

   108      * @throws ClassCastException            {@inheritDoc}

   109      * @throws NullPointerException          {@inheritDoc}

   110      * @throws IllegalArgumentException      {@inheritDoc}

   111      * @throws IndexOutOfBoundsException     {@inheritDoc}

   112      */

   113     public E set(int index, E element) {

   114         try {

   115             ListIterator<E> e = listIterator(index);

   116             E oldVal = e.next();

   117             e.set(element);

   118             return oldVal;

   119         } catch (NoSuchElementException exc) {

   120             throw new IndexOutOfBoundsException("Index: "+index);

   121         }

   122     }

   123 

   124     /**

   125      * Inserts the specified element at the specified position in this list

   126      * (optional operation).  Shifts the element currently at that position

   127      * (if any) and any subsequent elements to the right (adds one to their

   128      * indices).

   129      *

   130      * <p>This implementation first gets a list iterator pointing to the

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

   132      * inserts the specified element with <tt>ListIterator.add</tt>.

   133      *

   134      * <p>Note that this implementation will throw an

   135      * <tt>UnsupportedOperationException</tt> if the list iterator does not

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

   137      *

   138      * @throws UnsupportedOperationException {@inheritDoc}

   139      * @throws ClassCastException            {@inheritDoc}

   140      * @throws NullPointerException          {@inheritDoc}

   141      * @throws IllegalArgumentException      {@inheritDoc}

   142      * @throws IndexOutOfBoundsException     {@inheritDoc}

   143      */

   144     public void add(int index, E element) {

   145         try {

   146             listIterator(index).add(element);

   147         } catch (NoSuchElementException exc) {

   148             throw new IndexOutOfBoundsException("Index: "+index);

   149         }

   150     }

   151 

   152     /**

   153      * Removes the element at the specified position in this list (optional

   154      * operation).  Shifts any subsequent elements to the left (subtracts one

   155      * from their indices).  Returns the element that was removed from the

   156      * list.

   157      *

   158      * <p>This implementation first gets a list iterator pointing to the

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

   160      * the element with <tt>ListIterator.remove</tt>.

   161      *

   162      * <p>Note that this implementation will throw an

   163      * <tt>UnsupportedOperationException</tt> if the list iterator does not

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

   165      *

   166      * @throws UnsupportedOperationException {@inheritDoc}

   167      * @throws IndexOutOfBoundsException     {@inheritDoc}

   168      */

   169     public E remove(int index) {

   170         try {

   171             ListIterator<E> e = listIterator(index);

   172             E outCast = e.next();

   173             e.remove();

   174             return outCast;

   175         } catch (NoSuchElementException exc) {

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

   177         }

   178     }

   179 

   180 

   181     // Bulk Operations

   182 

   183     /**

   184      * Inserts all of the elements in the specified collection into this

   185      * list at the specified position (optional operation).  Shifts the

   186      * element currently at that position (if any) and any subsequent

   187      * elements to the right (increases their indices).  The new elements

   188      * will appear in this list in the order that they are returned by the

   189      * specified collection's iterator.  The behavior of this operation is

   190      * undefined if the specified collection is modified while the

   191      * operation is in progress.  (Note that this will occur if the specified

   192      * collection is this list, and it's nonempty.)

   193      *

   194      * <p>This implementation gets an iterator over the specified collection and

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

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

   197      * collection, inserting the elements obtained from the iterator into this

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

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

   200      *

   201      * <p>Note that this implementation will throw an

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

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

   204      * operation.

   205      *

   206      * @throws UnsupportedOperationException {@inheritDoc}

   207      * @throws ClassCastException            {@inheritDoc}

   208      * @throws NullPointerException          {@inheritDoc}

   209      * @throws IllegalArgumentException      {@inheritDoc}

   210      * @throws IndexOutOfBoundsException     {@inheritDoc}

   211      */

   212     public boolean addAll(int index, Collection<? extends E> c) {

   213         try {

   214             boolean modified = false;

   215             ListIterator<E> e1 = listIterator(index);

   216             for (E e : c) {

   217                 e1.add(e);

   218                 modified = true;

   219             }

   220             return modified;

   221         } catch (NoSuchElementException exc) {

   222             throw new IndexOutOfBoundsException("Index: "+index);

   223         }

   224     }

   225 

   226 

   227     // Iterators

   228 

   229     /**

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

   231      * sequence).<p>

   232      *

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

   234      *

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

   236      */

   237     public Iterator<E> iterator() {

   238         return listIterator();

   239     }

   240 

   241     /**

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

   243      * sequence).

   244      *

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

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

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

   248      *         sequence)

   249      * @throws IndexOutOfBoundsException {@inheritDoc}

   250      */

   251     public abstract ListIterator<E> listIterator(int index);

   252 }