org.apache.commons.collections.list
Class CursorableLinkedList

java.lang.Object
  |
  +--org.apache.commons.collections.list.AbstractLinkedList
        |
        +--org.apache.commons.collections.list.CursorableLinkedList

All Implemented Interfaces:

java.util.Collection, java.util.List, java.io.Serializable

public class CursorableLinkedList

extends AbstractLinkedList

implements java.io.Serializable

A List implementation with a ListIterator that allows concurrent modifications to the underlying list.

This implementation supports all of the optional List operations. It extends AbstractLinkedList and thus provides the stack/queue/dequeue operations available in LinkedList.

The main feature of this class is the ability to modify the list and the iterator at the same time. Both the listIterator() and cursor() methods provides access to a Cursor instance which extends ListIterator. The cursor allows changes to the list concurrent with changes to the iterator. Note that the iterator() method and sublists do not provide this cursor behaviour.

The Cursor class is provided partly for backwards compatibility and partly because it allows the cursor to be directly closed. Closing the cursor is optional because references are held via a WeakReference. For most purposes, simply modify the iterator and list at will, and then let the garbage collector to the rest.

Note that this implementation is not synchronized.

Since:

Commons Collections 1.0

Version:

$Revision: 1.5 $ $Date: 2004/02/18 01:12:26 $

Author:

Rodney Waldhoff, Janek Bogucki, Simon Kitching, Stephen Colebourne

See Also:

LinkedList, Serialized Form

Nested Class Summary

static class

CursorableLinkedList.Cursor An extended ListIterator that allows concurrent changes to the underlying list.

Constructor Summary

CursorableLinkedList()
Constructor that creates.

CursorableLinkedList(java.util.Collection coll)
Constructor that copies the specified collection

Method Summary

CursorableLinkedList.Cursor	cursor() Returns a CursorableLinkedList.Cursor for iterating through the elements of this list.
CursorableLinkedList.Cursor	cursor(int fromIndex) Returns a CursorableLinkedList.Cursor for iterating through the elements of this list starting from a specified index.
java.util.Iterator	iterator() Returns an iterator that does not support concurrent modification.
java.util.ListIterator	listIterator() Returns a cursor iterator that allows changes to the underlying list in parallel.
java.util.ListIterator	listIterator(int fromIndex) Returns a cursor iterator that allows changes to the underlying list in parallel.

Methods inherited from class org.apache.commons.collections.list.AbstractLinkedList

add, add, addAll, addAll, addFirst, addLast, clear, contains, containsAll, equals, get, getFirst, getLast, hashCode, indexOf, isEmpty, lastIndexOf, remove, remove, removeAll, removeFirst, removeLast, retainAll, set, size, subList, toArray, toArray, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CursorableLinkedList

public CursorableLinkedList()

Constructor that creates.

CursorableLinkedList

public CursorableLinkedList(java.util.Collection coll)

Constructor that copies the specified collection

Parameters:

coll - the collection to copy

Method Detail

iterator

public java.util.Iterator iterator()

Returns an iterator that does not support concurrent modification.

If the underlying list is modified while iterating using this iterator a ConcurrentModificationException will occur. The cursor behaviour is available via listIterator().

Specified by:

iterator in interface java.util.List

Overrides:

iterator in class AbstractLinkedList

Returns:

a new iterator that does not support concurrent modification

listIterator

public java.util.ListIterator listIterator()

Returns a cursor iterator that allows changes to the underlying list in parallel.

The cursor enables iteration and list changes to occur in any order without invalidating the iterator (from one thread). When elements are added to the list, an event is fired to all active cursors enabling them to adjust to the change in the list.

When the "current" (i.e., last returned by ListIterator.next() or ListIterator.previous()) element of the list is removed, the cursor automatically adjusts to the change (invalidating the last returned value such that it cannot be removed).

Specified by:

listIterator in interface java.util.List

Overrides:

listIterator in class AbstractLinkedList

Returns:

a new cursor iterator

listIterator

public java.util.ListIterator listIterator(int fromIndex)

Returns a cursor iterator that allows changes to the underlying list in parallel.

The cursor enables iteration and list changes to occur in any order without invalidating the iterator (from one thread). When elements are added to the list, an event is fired to all active cursors enabling them to adjust to the change in the list.

When the "current" (i.e., last returned by ListIterator.next() or ListIterator.previous()) element of the list is removed, the cursor automatically adjusts to the change (invalidating the last returned value such that it cannot be removed).

Specified by:

listIterator in interface java.util.List

Overrides:

listIterator in class AbstractLinkedList

Parameters:

fromIndex - the index to start from

Returns:

a new cursor iterator

cursor

public CursorableLinkedList.Cursor cursor()

Returns a CursorableLinkedList.Cursor for iterating through the elements of this list.

A Cursor is a ListIterator with an additional close() method. Calling this method immediately discards the references to the cursor. If it is not called, then the garbage collector will still remove the reference as it is held via a WeakReference.

The cursor enables iteration and list changes to occur in any order without invalidating the iterator (from one thread). When elements are added to the list, an event is fired to all active cursors enabling them to adjust to the change in the list.

When the "current" (i.e., last returned by ListIterator.next() or ListIterator.previous()) element of the list is removed, the cursor automatically adjusts to the change (invalidating the last returned value such that it cannot be removed).

The listIterator() method returns the same as this method, and can be cast to a Cursor if the close method is required.

Returns:

a new cursor iterator

cursor

public CursorableLinkedList.Cursor cursor(int fromIndex)

Returns a CursorableLinkedList.Cursor for iterating through the elements of this list starting from a specified index.

A Cursor is a ListIterator with an additional close() method. Calling this method immediately discards the references to the cursor. If it is not called, then the garbage collector will still remove the reference as it is held via a WeakReference.

The cursor enables iteration and list changes to occur in any order without invalidating the iterator (from one thread). When elements are added to the list, an event is fired to all active cursors enabling them to adjust to the change in the list.

When the "current" (i.e., last returned by ListIterator.next() or ListIterator.previous()) element of the list is removed, the cursor automatically adjusts to the change (invalidating the last returned value such that it cannot be removed).

The listIterator(int) method returns the same as this method, and can be cast to a Cursor if the close method is required.

Parameters:

fromIndex - the index to start from

Returns:

a new cursor iterator

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).