java.util

Class AbstractSequentialList<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

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

Author:

Original author unknown, Bryce McKinlay, Eric Blake (ebb9@email.byu.edu)

See Also:

Collection, List, AbstractList, AbstractCollection, ListIterator, LinkedList

Method Summary

Modifier and Type	Method and Description
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, 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

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, size, toArray, toArray

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

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

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

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.