org.apache.commons.collections.list

Class CursorableLinkedList

Implemented Interfaces:
List, Serializable

public class CursorableLinkedList
extends AbstractLinkedList
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 java.util.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.

Version:
$Revision: 1.5 $ $Date: 2004/02/18 01:12:26 $
Authors:
Rodney Waldhoff
Janek Bogucki
Simon Kitching
Stephen Colebourne
Since:
Commons Collections 1.0
See Also:
java.util.LinkedList

Nested Class Summary

static class
CursorableLinkedList.Cursor
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, AbstractLinkedList.LinkedSubList, AbstractLinkedList.LinkedSubListIterator, AbstractLinkedList.Node

Field Summary

protected List
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 coll)
Constructor that copies the specified collection

Method Summary

protected void
addNode(AbstractLinkedList.Node nodeToInsert, AbstractLinkedList.Node insertBeforeNode)
Inserts a new node into the list.
protected void
broadcastNodeChanged(AbstractLinkedList.Node node)
Informs all of my registered cursors that the specified element was changed.
protected void
broadcastNodeInserted(AbstractLinkedList.Node node)
Informs all of my registered cursors that the specified element was just added to my list.
protected void
broadcastNodeRemoved(AbstractLinkedList.Node node)
Informs all of my registered cursors that the specified element was just removed from my list.
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.
protected void
init()
The equivalent of a default constructor called by any constructor and by readObject.
Iterator
iterator()
Returns an iterator that does not support concurrent modification.
ListIterator
listIterator()
Returns a cursor iterator that allows changes to the underlying list in parallel.
ListIterator
listIterator(int fromIndex)
Returns a cursor iterator that allows changes to the underlying list in parallel.
protected void
registerCursor(CursorableLinkedList.Cursor 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 node)
Removes the specified node from the list.
protected void
unregisterCursor(CursorableLinkedList.Cursor cursor)
Deregisters a cursor from the list to be notified of changes.
protected void
updateNode(AbstractLinkedList.Node node, Object value)
Updates the node with a new value.

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

add, add, addAll, addAll, addFirst, addLast, addNode, addNodeAfter, addNodeBefore, clear, contains, containsAll, createHeaderNode, createNode, createSubListIterator, createSubListListIterator, doReadObject, doWriteObject, equals, get, getFirst, getLast, getNode, hashCode, indexOf, init, isEmpty, isEqualValue, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, removeAllNodes, removeFirst, removeLast, removeNode, retainAll, set, size, subList, toArray, toArray, toString, updateNode

Field Details

cursors

protected List cursors
A list of the cursor currently open on this list

Constructor Details

CursorableLinkedList

public CursorableLinkedList()
Constructor that creates.

CursorableLinkedList

public CursorableLinkedList(Collection coll)
Constructor that copies the specified collection
Parameters:
coll - the collection to copy

Method Details

addNode

protected void addNode(AbstractLinkedList.Node nodeToInsert,
                       AbstractLinkedList.Node insertBeforeNode)
Inserts a new node into the list.
Overrides:
addNode in interface AbstractLinkedList
Parameters:
nodeToInsert - new node to insert
insertBeforeNode - node to insert before

broadcastNodeChanged

protected void broadcastNodeChanged(AbstractLinkedList.Node node)
Informs all of my registered cursors that the specified element was changed.
Parameters:
node - the node that was changed

broadcastNodeInserted

protected void broadcastNodeInserted(AbstractLinkedList.Node node)
Informs all of my registered cursors that the specified element was just added to my list.
Parameters:
node - the node that was changed

broadcastNodeRemoved

protected void broadcastNodeRemoved(AbstractLinkedList.Node node)
Informs all of my registered cursors that the specified element was just removed from my list.
Parameters:
node - the node that was changed

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

init

protected void init()
The equivalent of a default constructor called by any constructor and by readObject.
Overrides:
init in interface AbstractLinkedList

iterator

public Iterator iterator()
Overrides:
iterator in interface AbstractLinkedList
Returns:
a new iterator that does not support concurrent modification

listIterator

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

Overrides:
listIterator in interface AbstractLinkedList
Returns:
a new cursor iterator

listIterator

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

Overrides:
listIterator in interface AbstractLinkedList
Parameters:
fromIndex - the index to start from
Returns:
a new cursor iterator

registerCursor

protected void registerCursor(CursorableLinkedList.Cursor cursor)
Registers a cursor to be notified of changes to this list.
Parameters:
cursor - the cursor to register

removeAllNodes

protected void removeAllNodes()
Removes all nodes by iteration.
Overrides:
removeAllNodes in interface AbstractLinkedList

removeNode

protected void removeNode(AbstractLinkedList.Node node)
Removes the specified node from the list.
Overrides:
removeNode in interface AbstractLinkedList
Parameters:
node - the node to remove

unregisterCursor

protected void unregisterCursor(CursorableLinkedList.Cursor cursor)
Deregisters a cursor from the list to be notified of changes.
Parameters:
cursor - the cursor to deregister

updateNode

protected void updateNode(AbstractLinkedList.Node node,
                          Object 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 interface AbstractLinkedList
Parameters:
node - node to update
value - new value of the node

Copyright © 2001-2006 Apache Software Foundation. All Rights Reserved.