java.util

Class AbstractSequentialList<E>

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

UNKNOWN: updated to 1.4

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

Constructor Detail

AbstractSequentialList

protected AbstractSequentialList()

The main constructor, for use by subclasses.

Method Detail

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

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.

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.

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.

get

public E get(int index)

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

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().

Returns: an Iterator over the elements of this list, in order

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.

Parameters: index the starting position of the list

Returns: the list iterator

Throws: IndexOutOfBoundsException if index < 0 || index > size()

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().

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()

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

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.