org.apache.commons.collections4.list

## Class CursorableLinkedList<E>

- java.lang.Object
- - org.apache.commons.collections4.list.AbstractLinkedList<E>
  - - org.apache.commons.collections4.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:
    1.0
  Version:
    $Id: CursorableLinkedList.java 1533984 2013-10-20 21:12:51Z tn $
  See Also:
    `LinkedList`, Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `CursorableLinkedList.Cursor<E>` An extended `ListIterator` that allows concurrent changes to the underlying list.
    `protected static class` | `CursorableLinkedList.SubCursor<E>` A cursor for the sublist based on LinkedSubListIterator.

    - ### Nested classes/interfaces inherited from class org.apache.commons.collections4.list.AbstractLinkedList

      `AbstractLinkedList.LinkedListIterator<E>, AbstractLinkedList.LinkedSubList<E>, AbstractLinkedList.LinkedSubListIterator<E>, AbstractLinkedList.Node<E>`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CursorableLinkedList()` Constructor that creates.
    `CursorableLinkedList(Collection<? extends E> coll)` Constructor that copies the specified collection

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `protected ListIterator<E>` | `createSubListListIterator(AbstractLinkedList.LinkedSubList<E> subList, int fromIndex)` Creates a list iterator for the sublist.
    `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.collections4.list.AbstractLinkedList

      `add, add, addAll, addAll, addFirst, addLast, addNodeAfter, addNodeBefore, clear, contains, containsAll, createHeaderNode, createNode, createSubListIterator, 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`

- - ### Constructor Detail

    - #### CursorableLinkedList

          public CursorableLinkedList()

      Constructor that creates.

    - #### CursorableLinkedList

          public CursorableLinkedList(Collection<? extends 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

    - #### createSubListListIterator

          protected ListIterator<E> createSubListListIterator(AbstractLinkedList.LinkedSubList<E> subList,
                                                  int fromIndex)

      Creates a list iterator for the sublist.
      Overrides:
        `createSubListListIterator` in class `AbstractLinkedList<E>`
      Parameters:
        `subList` - the sublist to get an iterator for
        `fromIndex` - the index to start from, relative to the sublist
      Returns:
        the list iterator for the sublist

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.