Class CursorableLinkedList

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable, java.util.Collection, java.util.List

    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: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
    See Also:
    LinkedList, Serialized Form
    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Ensure serialization compatibility
        See Also:
        Constant Field Values
      • cursors

        protected transient java.util.List cursors
        A list of the cursor currently open on this list
    • 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

      • init

        protected void init()
        The equivalent of a default constructor called by any constructor and by readObject.
        Overrides:
        init in class AbstractLinkedList
      • 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.Collection
        Specified by:
        iterator in interface java.lang.Iterable
        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()).
      • updateNode

        protected void updateNode​(AbstractLinkedList.Node node,
                                  java.lang.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 class AbstractLinkedList
        Parameters:
        node - node to update
        value - new value of the node
      • removeNode

        protected void removeNode​(AbstractLinkedList.Node node)
        Removes the specified node from the list.
        Overrides:
        removeNode in class AbstractLinkedList
        Parameters:
        node - the node to remove
        Throws:
        java.lang.NullPointerException - if node is null
      • registerCursor

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

        protected void unregisterCursor​(CursorableLinkedList.Cursor cursor)
        Deregisters a cursor from the list to be notified of changes.
        Parameters:
        cursor - the cursor to deregister
      • 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
      • 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
      • 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
      • writeObject

        private void writeObject​(java.io.ObjectOutputStream out)
                          throws java.io.IOException
        Serializes the data held in this object to the stream specified.
        Throws:
        java.io.IOException
      • readObject

        private void readObject​(java.io.ObjectInputStream in)
                         throws java.io.IOException,
                                java.lang.ClassNotFoundException
        Deserializes the data held in this object to the stream specified.
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException
      • createSubListListIterator

        protected java.util.ListIterator createSubListListIterator​(AbstractLinkedList.LinkedSubList subList,
                                                                   int fromIndex)
        Creates a list iterator for the sublist.
        Overrides:
        createSubListListIterator in class AbstractLinkedList
        Parameters:
        subList - the sublist to get an iterator for
        fromIndex - the index to start from, relative to the sublist