/*

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

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

  *

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

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

  * published by the Free Software Foundation.  Oracle designates this

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

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

  *

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

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

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

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

  * accompanied this code).

  *

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

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

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

  *

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

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

  * questions.

  */

 package java.util;

 /**

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

  * 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), <tt>AbstractList</tt> should be used

  * in preference to this class.<p>

  *

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

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

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

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

  * the other way around.<p>

  *

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

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

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

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

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

  *

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

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

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

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

  *

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

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

  * specification.<p>

  *

  * This class is a member of the

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

  * Java Collections Framework</a>.

  *

  * @author  Josh Bloch

  * @author  Neal Gafter

  * @see Collection

  * @see List

  * @see AbstractList

  * @see AbstractCollection

  * @since 1.2

  */

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

     /**

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

      * implicit.)

      */

     protected AbstractSequentialList() {

     }

     /**

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

      *

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

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

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

      *

      * @throws IndexOutOfBoundsException {@inheritDoc}

      */

     public E get(int index) {

         try {

             return listIterator(index).next();

         } catch (NoSuchElementException exc) {

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

         }

     }

     /**

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

      * specified element (optional operation).

      *

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

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

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

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

      *

      * <p>Note that this implementation will throw an

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

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

      *

      * @throws UnsupportedOperationException {@inheritDoc}

      * @throws ClassCastException            {@inheritDoc}

      * @throws NullPointerException          {@inheritDoc}

      * @throws IllegalArgumentException      {@inheritDoc}

      * @throws IndexOutOfBoundsException     {@inheritDoc}

      */

     public E set(int index, E element) {

         try {

             ListIterator<E> e = listIterator(index);

             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

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

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

      * indices).

      *

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

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

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

      *

      * <p>Note that this implementation will throw an

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

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

      *

      * @throws UnsupportedOperationException {@inheritDoc}

      * @throws ClassCastException            {@inheritDoc}

      * @throws NullPointerException          {@inheritDoc}

      * @throws IllegalArgumentException      {@inheritDoc}

      * @throws IndexOutOfBoundsException     {@inheritDoc}

      */

     public void add(int index, E element) {

         try {

             listIterator(index).add(element);

         } catch (NoSuchElementException exc) {

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

         }

     }

     /**

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

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

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

      * list.

      *

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

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

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

      *

      * <p>Note that this implementation will throw an

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

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

      *

      * @throws UnsupportedOperationException {@inheritDoc}

      * @throws IndexOutOfBoundsException     {@inheritDoc}

      */

     public E remove(int index) {

         try {

             ListIterator<E> e = listIterator(index);

             E outCast = e.next();

             e.remove();

             return outCast;

         } catch (NoSuchElementException exc) {

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

         }

     }

     // Bulk Operations

     /**

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

      * list at the specified position (optional operation).  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 this list in the order that they are returned by the

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

      * undefined 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.)

      *

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

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

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

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

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

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

      *

      * <p>Note that this implementation will throw an

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

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

      * operation.

      *

      * @throws UnsupportedOperationException {@inheritDoc}

      * @throws ClassCastException            {@inheritDoc}

      * @throws NullPointerException          {@inheritDoc}

      * @throws IllegalArgumentException      {@inheritDoc}

      * @throws IndexOutOfBoundsException     {@inheritDoc}

      */

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

         try {

             boolean modified = false;

             ListIterator<E> e1 = listIterator(index);

             Iterator<? extends E> e2 = c.iterator();

             while (e2.hasNext()) {

                 e1.add(e2.next());

                 modified = true;

             }

             return modified;

         } catch (NoSuchElementException exc) {

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

         }

     }

     // Iterators

     /**

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

      * sequence).<p>

      *

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

      *

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

      */

     public Iterator<E> 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 <code>next</code> method)

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

      *         sequence)

      * @throws IndexOutOfBoundsException {@inheritDoc}

      */

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

 }