java.util
Class AbstractSequentialList<E>

java.lang.Object
  extended by java.util.AbstractCollection<E>
      extended by java.util.AbstractList<E>
          extended by java.util.AbstractSequentialList<E>
All Implemented Interfaces:
Iterable<E>, Collection<E>, List<E>
Direct Known Subclasses:
LinkedList

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

Abstract superclass to make it easier to implement the List interface when backed by a sequential-access store, such as a linked list. For random access data, use AbstractList. This class implements the random access methods (get, set, add, and remove) atop the list iterator, opposite of AbstractList's approach of implementing the iterator atop random access.

To implement a list, you need an implementation for size() and listIterator. With just hasNext, next, hasPrevious, previous, nextIndex, and previousIndex, you have an unmodifiable list. For a modifiable one, add set, and for a variable-size list, add add and remove.

The programmer should provide a no-argument constructor, and one that accepts another Collection, as recommended by the Collection interface. Unfortunately, there is no way to enforce this in Java.

Since:
1.2
See Also:
Collection, List, AbstractList, AbstractCollection, ListIterator, LinkedList

Field Summary
 
Fields inherited from class java.util.AbstractList
modCount
 
Constructor Summary
protected AbstractSequentialList()
          The main constructor, for use by subclasses.
 
Method Summary
 void add(int index, E o)
          Insert an element into the list at a given position (optional operation).
 boolean addAll(int index, Collection<? extends E> c)
          Insert the contents of a collection into the list at a given position (optional operation).
 E get(int index)
          Get the element at a given index in this list.
 Iterator<E> iterator()
          Obtain an Iterator over this list, whose sequence is the list order.
abstract  ListIterator<E> listIterator(int index)
          Returns a ListIterator over the list, starting from position index.
 E remove(int index)
          Remove the element at a given position in this list (optional operation).
 E set(int index, E o)
          Replace an element of this list with another object (optional operation).
 
Methods inherited from class java.util.AbstractList
add, clear, equals, hashCode, indexOf, lastIndexOf, listIterator, removeRange, subList
 
Methods inherited from class java.util.AbstractCollection
addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, size, toArray, toArray, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.List
addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, size, toArray, toArray
 

Constructor Detail

AbstractSequentialList

protected AbstractSequentialList()
The main constructor, for use by subclasses.

Method Detail

listIterator

public abstract ListIterator<E> listIterator(int index)
Returns a ListIterator over the list, starting from position index. Subclasses must provide an implementation of this method.

Specified by:
listIterator in interface List<E>
Overrides:
listIterator in class AbstractList<E>
Parameters:
index - the starting position of the list
Returns:
the list iterator
Throws:
IndexOutOfBoundsException - if index < 0 || index > size()
See Also:
AbstractList.modCount

add

public void add(int index,
                E o)
Insert an element into the list at a given position (optional operation). This shifts all existing elements from that position to the end one index to the right. This version of add has no return, since it is assumed to always succeed if there is no exception. This iteration uses listIterator(index).add(o).

Specified by:
add in interface List<E>
Overrides:
add in class AbstractList<E>
Parameters:
index - the location to insert the item
o - the object to insert
Throws:
UnsupportedOperationException - if this list does not support the add operation
IndexOutOfBoundsException - if index < 0 || index > size()
ClassCastException - if o cannot be added to this list due to its type
IllegalArgumentException - if o cannot be added to this list for some other reason.
NullPointerException - if o is null and the list does not permit the addition of null values.
See Also:
AbstractList.modCount

addAll

public boolean addAll(int index,
                      Collection<? extends E> c)
Insert the contents of a collection into the list at a given position (optional operation). Shift all elements at that position to the right by the number of elements inserted. This operation is undefined if this list is modified during the operation (for example, if you try to insert a list into itself).

This implementation grabs listIterator(index), then proceeds to use add for each element returned by c's iterator. Sun's online specs are wrong, claiming that this also calls next(): listIterator.add() correctly skips the added element.

Specified by:
addAll in interface List<E>
Overrides:
addAll in class AbstractList<E>
Parameters:
index - the location to insert the collection
c - the collection to insert
Returns:
true if the list was modified by this action, that is, if c is non-empty
Throws:
UnsupportedOperationException - if this list does not support the addAll operation
IndexOutOfBoundsException - if index < 0 || index > size()
ClassCastException - if some element of c cannot be added to this list due to its type
IllegalArgumentException - if some element of c cannot be added to this list for some other reason
NullPointerException - if the specified collection is null
NullPointerException - if an object, o, in c is null and the list does not permit the addition of null values.
See Also:
add(int, Object)

get

public E get(int index)
Get the element at a given index in this list. This implementation returns listIterator(index).next().

Specified by:
get in interface List<E>
Specified by:
get in class AbstractList<E>
Parameters:
index - the index of the element to be returned
Returns:
the element at index index in this list
Throws:
IndexOutOfBoundsException - if index < 0 || index >= size()

iterator

public Iterator<E> iterator()
Obtain an Iterator over this list, whose sequence is the list order. This implementation returns listIterator().

Specified by:
iterator in interface Iterable<E>
Specified by:
iterator in interface Collection<E>
Specified by:
iterator in interface List<E>
Overrides:
iterator in class AbstractList<E>
Returns:
an Iterator over the elements of this list, in order
See Also:
AbstractList.modCount

remove

public E remove(int index)
Remove the element at a given position in this list (optional operation). Shifts all remaining elements to the left to fill the gap. This implementation uses listIterator(index) and ListIterator.remove().

Specified by:
remove in interface List<E>
Overrides:
remove in class AbstractList<E>
Parameters:
index - the position within the list of the object to remove
Returns:
the object that was removed
Throws:
UnsupportedOperationException - if this list does not support the remove operation
IndexOutOfBoundsException - if index < 0 || index >= size()
See Also:
AbstractList.modCount

set

public E set(int index,
             E o)
Replace an element of this list with another object (optional operation). This implementation uses listIterator(index) and ListIterator.set(o).

Specified by:
set in interface List<E>
Overrides:
set in class AbstractList<E>
Parameters:
index - the position within this list of the element to be replaced
o - the object to replace it with
Returns:
the object that was replaced
Throws:
UnsupportedOperationException - if this list does not support the set operation
IndexOutOfBoundsException - if index < 0 || index >= size()
ClassCastException - if o cannot be added to this list due to its type
IllegalArgumentException - if o cannot be added to this list for some other reason
NullPointerException - if o is null and the list does not allow a value to be set to null.