org.apache.commons.collections.list
Class CursorableLinkedList<E>

java.lang.Object
  extended by org.apache.commons.collections.list.AbstractLinkedList<E>
      extended by org.apache.commons.collections.list.CursorableLinkedList<E>
All Implemented Interfaces:
Serializable, Iterable<E>, Collection<E>, List<E>

public class CursorableLinkedList<E>
extends AbstractLinkedList<E>
implements 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.1.1.1 $ $Date: 2005/05/23 04:35:20 $
Author:
Rodney Waldhoff, Janek Bogucki, Simon Kitching, Matt Hall, John Watkinson, Stephen Colebourne
See Also:
LinkedList, Serialized Form

Nested Class Summary
static class CursorableLinkedList.Cursor<E>
          An extended ListIterator that allows concurrent changes to the underlying list.
 
Nested classes/interfaces inherited from class org.apache.commons.collections.list.AbstractLinkedList
AbstractLinkedList.LinkedListIterator<E>, AbstractLinkedList.LinkedSubList<E>, AbstractLinkedList.LinkedSubListIterator<E>, AbstractLinkedList.Node<T>
 
Field Summary
protected  List<WeakReference<CursorableLinkedList.Cursor<E>>> cursors
          A list of the cursor currently open on this list
 
Fields inherited from class org.apache.commons.collections.list.AbstractLinkedList
header, modCount, size
 
Constructor Summary
CursorableLinkedList()
          Constructor that creates.
CursorableLinkedList(Collection<E> coll)
          Constructor that copies the specified collection
 
Method Summary
protected  void addNode(AbstractLinkedList.Node<E> nodeToInsert, AbstractLinkedList.Node<E> insertBeforeNode)
          Inserts a new node into the list.
protected  void broadcastNodeChanged(AbstractLinkedList.Node<E> node)
          Informs all of my registered cursors that the specified element was changed.
protected  void broadcastNodeInserted(AbstractLinkedList.Node<E> node)
          Informs all of my registered cursors that the specified element was just added to my list.
protected  void broadcastNodeRemoved(AbstractLinkedList.Node<E> node)
          Informs all of my registered cursors that the specified element was just removed from my list.
 CursorableLinkedList.Cursor<E> cursor()
          Returns a CursorableLinkedList.Cursor for iterating through the elements of this list.
 CursorableLinkedList.Cursor<E> cursor(int fromIndex)
          Returns a CursorableLinkedList.Cursor for iterating through the elements of this list starting from a specified index.
protected  void init()
          The equivalent of a default constructor called by any constructor and by readObject.
 Iterator<E> iterator()
          Returns an iterator that does not support concurrent modification.
 ListIterator<E> listIterator()
          Returns a cursor iterator that allows changes to the underlying list in parallel.
 ListIterator<E> listIterator(int fromIndex)
          Returns a cursor iterator that allows changes to the underlying list in parallel.
protected  void registerCursor(CursorableLinkedList.Cursor<E> cursor)
          Registers a cursor to be notified of changes to this list.
protected  void removeAllNodes()
          Removes all nodes by iteration.
protected  void removeNode(AbstractLinkedList.Node<E> node)
          Removes the specified node from the list.
protected  void unregisterCursor(CursorableLinkedList.Cursor<E> cursor)
          Deregisters a cursor from the list to be notified of changes.
protected  void updateNode(AbstractLinkedList.Node<E> node, E value)
          Updates the node with a new value.
 
Methods inherited from class org.apache.commons.collections.list.AbstractLinkedList
add, add, addAll, addAll, addFirst, addLast, addNodeAfter, addNodeBefore, clear, contains, containsAll, createHeaderNode, createNode, createSubListIterator, createSubListListIterator, doReadObject, doWriteObject, equals, get, getFirst, getLast, getNode, hashCode, indexOf, isEmpty, isEqualValue, lastIndexOf, remove, remove, removeAll, removeFirst, removeLast, retainAll, set, size, subList, toArray, toArray, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

cursors

protected transient List<WeakReference<CursorableLinkedList.Cursor<E>>> cursors
A list of the cursor currently open on this list

Constructor Detail

CursorableLinkedList

public CursorableLinkedList()
Constructor that creates.


CursorableLinkedList

public CursorableLinkedList(Collection<E> coll)
Constructor that copies the specified collection

Parameters:
coll - the collection to copy
Method Detail

init

protected void init()
The equivalent of a default constructor called by any constructor and by readObject.

Overrides:
init in class AbstractLinkedList<E>

iterator

public Iterator<E> 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 Iterable<E>
Specified by:
iterator in interface Collection<E>
Specified by:
iterator in interface List<E>
Overrides:
iterator in class AbstractLinkedList<E>
Returns:
a new iterator that does not support concurrent modification

listIterator

public ListIterator<E> 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 List<E>
Overrides:
listIterator in class AbstractLinkedList<E>
Returns:
a new cursor iterator

listIterator

public ListIterator<E> 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 List<E>
Overrides:
listIterator in class AbstractLinkedList<E>
Parameters:
fromIndex - the index to start from
Returns:
a new cursor iterator

cursor

public CursorableLinkedList.Cursor<E> 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<E> 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:
IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

updateNode

protected void updateNode(AbstractLinkedList.Node<E> node,
                          E value)
Updates the node with a new value. This implementation sets the value on the node. Subclasses can override this to record the change.

Overrides:
updateNode in class AbstractLinkedList<E>
Parameters:
node - node to update
value - new value of the node

addNode

protected void addNode(AbstractLinkedList.Node<E> nodeToInsert,
                       AbstractLinkedList.Node<E> insertBeforeNode)
Inserts a new node into the list.

Overrides:
addNode in class AbstractLinkedList<E>
Parameters:
nodeToInsert - new node to insert
insertBeforeNode - node to insert before
Throws:
NullPointerException - if either node is null

removeNode

protected void removeNode(AbstractLinkedList.Node<E> node)
Removes the specified node from the list.

Overrides:
removeNode in class AbstractLinkedList<E>
Parameters:
node - the node to remove
Throws:
NullPointerException - if node is null

removeAllNodes

protected void removeAllNodes()
Removes all nodes by iteration.

Overrides:
removeAllNodes in class AbstractLinkedList<E>

registerCursor

protected void registerCursor(CursorableLinkedList.Cursor<E> cursor)
Registers a cursor to be notified of changes to this list.

Parameters:
cursor - the cursor to register

unregisterCursor

protected void unregisterCursor(CursorableLinkedList.Cursor<E> cursor)
Deregisters a cursor from the list to be notified of changes.

Parameters:
cursor - the cursor to deregister

broadcastNodeChanged

protected void broadcastNodeChanged(AbstractLinkedList.Node<E> node)
Informs all of my registered cursors that the specified element was changed.

Parameters:
node - the node that was changed

broadcastNodeRemoved

protected void broadcastNodeRemoved(AbstractLinkedList.Node<E> node)
Informs all of my registered cursors that the specified element was just removed from my list.

Parameters:
node - the node that was changed

broadcastNodeInserted

protected void broadcastNodeInserted(AbstractLinkedList.Node<E> node)
Informs all of my registered cursors that the specified element was just added to my list.

Parameters:
node - the node that was changed


Copyright © 2005-2005 Apache Software Foundation, Matt Hall, John Watkinson. All Rights Reserved.