Module javafx.base
Package javafx.collections

# Class ObservableListBase<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractList<E>
javafx.collections.ObservableListBase<E>

Type Parameters:
  `E` - the type of the elements contained in the List

All Implemented Interfaces:
  `Iterable<E>`, `Collection<E>`, `List<E>`, `Observable`, `ObservableList<E>`

Direct Known Subclasses:
  `ModifiableObservableListBase`, `TransformationList`

    public abstract class ObservableListBase<E>
    extends AbstractList<E>
    implements ObservableList<E>

Abstract class that serves as a base class for `ObservableList` implementations. The base class provides two functionalities for the implementing classes.

- Listener handling by implementing `addListener` and `removeListener` methods. `fireChange(javafx.collections.ListChangeListener.Change)` method is provided for notifying the listeners with a `Change` object.
- Methods for building up a `ListChangeListener.Change` object. There are various methods called `next*`, like `nextAdd(int, int)` for new items in the lists or `nextRemove(int, java.lang.Object)` for an item being removed from the list.

  These methods must be always enclosed in `beginChange()` and `endChange()` block.

  See the example below.

The following example shows how the Change build-up works:

      public void removeOddIndexes() {
          beginChange();
          try {
              for (int i = 1; i < size(); ++i) {
                  remove(i);
              }
          } finally {
              endChange();
          }
      }

      public void remove(int i) {
          beginChange();
          try {
              E removed = ... //do some stuff that will actually remove the element at index i
              nextRemove(i, removed);
          } finally {
              endChange();
          }
      }

The `try`/`finally` blocks in the example are needed only if there's a possibility for an exception to occur inside a `beginChange()` / `endChange()` block

Note: If you want to create modifiable `ObservableList` implementation, consider using `ModifiableObservableListBase` as a superclass.

Note: In order to create list with sequential access, you should override `AbstractList.listIterator()`, `AbstractList.iterator()` methods and use them in `AbstractList.get(int)`, `AbstractCollection.size()` and other methods accordingly.

Since:
  JavaFX 8.0
See Also:
  `ObservableList`, `ListChangeListener.Change`, `ModifiableObservableListBase`

- ## Field Summary

  ### Fields declared in class java.util.AbstractList

  `modCount`

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `ObservableListBase()` | Creates a default `ObservableListBase`.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `protected void` | `beginChange()` | Begins a change block.
  `protected void` | `endChange()` | Ends the change block.
  `protected void` | `fireChange​(ListChangeListener.Change<? extends E> change)` | Notifies all listeners of a change
  `protected boolean` | `hasListeners()` | Returns true if there are some listeners registered for this list.
  `protected void` | `nextAdd​(int from, int to)` | Adds a new add operation to the change.
  `protected void` | `nextPermutation​(int from, int to, int[] perm)` | Adds a new permutation operation to the change.
  `protected void` | `nextRemove​(int idx, E removed)` | Adds a new remove operation to the change with single item removed.
  `protected void` | `nextRemove​(int idx, List<? extends E> removed)` | Adds a new remove operation to the change with multiple items removed.
  `protected void` | `nextReplace​(int from, int to, List<? extends E> removed)` | Adds a new replace operation to the change.
  `protected void` | `nextSet​(int idx, E old)` | Adds a new set operation to the change.
  `protected void` | `nextUpdate​(int pos)` | Adds a new update operation to the change.

  ### Methods declared in class java.util.AbstractList

  `add, add, addAll, clear, equals, get, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, remove, removeRange, set, subList`

  ### Methods declared in class java.util.AbstractCollection

  `addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, size, toArray, toArray, toString`

  ### Methods declared in class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods declared in interface java.util.Collection

  `parallelStream, removeIf, stream, toArray`

  ### Methods declared in interface java.lang.Iterable

  `forEach`

  ### Methods declared in interface java.util.List

  `add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArray`

  ### Methods declared in interface javafx.beans.Observable

  `addListener, removeListener`

  ### Methods declared in interface javafx.collections.ObservableList

  `addAll, addListener, filtered, remove, removeAll, removeListener, retainAll, setAll, setAll, sorted, sorted`

- ## Constructor Details

  - ### ObservableListBase

    public ObservableListBase()
    Creates a default `ObservableListBase`.

- ## Method Details

  - ### nextUpdate

    protected final void nextUpdate​(int pos)
    Adds a new update operation to the change.

    Note: needs to be called inside `beginChange()` / `endChange()` block.

    Note: needs to reflect the current state of the list.

    Parameters:
      `pos` - the position in the list where the updated element resides.

  - ### nextSet

    protected final void nextSet​(int idx, E old)
    Adds a new set operation to the change. Equivalent to `nextRemove(idx); nextAdd(idx, idx + 1);` .

    Note: needs to be called inside `beginChange()` / `endChange()` block.

    Note: needs to reflect the current state of the list.

    Parameters:
      `idx` - the index of the item that was set
      `old` - the old value at the `idx` position.

  - ### nextReplace

    protected final void nextReplace​(int from, int to, List<? extends E> removed)
    Adds a new replace operation to the change. Equivalent to `nextRemove(from, removed); nextAdd(from, to);`

    Note: needs to be called inside `beginChange()` / `endChange()` block.

    Note: needs to reflect the current state of the list.

    Parameters:
      `from` - the index where the items were replaced
      `to` - the end index (exclusive) of the range where the new items reside
      `removed` - the list of items that were removed

  - ### nextRemove

    protected final void nextRemove​(int idx, List<? extends E> removed)
    Adds a new remove operation to the change with multiple items removed.

    Note: needs to be called inside `beginChange()` / `endChange()` block.

    Note: needs to reflect the current state of the list.

    Parameters:
      `idx` - the index where the items were removed
      `removed` - the list of items that were removed

  - ### nextRemove

    protected final void nextRemove​(int idx, E removed)
    Adds a new remove operation to the change with single item removed.

    Note: needs to be called inside `beginChange()` / `endChange()` block.

    Note: needs to reflect the current state of the list.

    Parameters:
      `idx` - the index where the item was removed
      `removed` - the item that was removed

  - ### nextPermutation

    protected final void nextPermutation​(int from, int to, int[] perm)
    Adds a new permutation operation to the change. The permutation on index `"i"` contains the index, where the item from the index `"i"` was moved.

    It's not necessary to provide the smallest permutation possible. It's correct to always call this method with `nextPermutation(0, size(), permutation);`

    Note: needs to be called inside `beginChange()` / `endChange()` block.

    Note: needs to reflect the current state of the list.

    Parameters:
      `from` - marks the beginning (inclusive) of the range that was permutated
      `to` - marks the end (exclusive) of the range that was permutated
      `perm` - the permutation in that range. Even if `from != 0`, the array should contain the indexes of the list. Therefore, such permutation would not contain indexes of range `(0, from)`

  - ### nextAdd

    protected final void nextAdd​(int from, int to)
    Adds a new add operation to the change. There's no need to provide the list of added items as they can be found directly in the list under the specified indexes.

    Note: needs to be called inside `beginChange()` / `endChange()` block.

    Note: needs to reflect the current state of the list.

    Parameters:
      `from` - marks the beginning (inclusive) of the range that was added
      `to` - marks the end (exclusive) of the range that was added

  - ### beginChange

    protected final void beginChange()
    Begins a change block. Must be called before any of the `next*` methods is called. For every `beginChange()`, there must be a corresponding `endChange()` call.

    `beginChange()` calls can be nested in a `beginChange()`/`endChange()` block.

    See Also:
      `endChange()`

  - ### endChange

    protected final void endChange()
    Ends the change block. If the block is the outer-most block for the `ObservableList`, the `Change` is constructed and all listeners are notified.

    Ending a nested block doesn't fire a notification.

    See Also:
      `beginChange()`

  - ### fireChange

    protected final void fireChange​(ListChangeListener.Change<? extends E> change)
    Notifies all listeners of a change
    Parameters:
      `change` - an object representing the change that was done

  - ### hasListeners

    protected final boolean hasListeners()
    Returns true if there are some listeners registered for this list.
    Returns:
      true if there is a listener for this list