ObservableListBase (JavaFX 17)

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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### ObservableListBase

          public ObservableListBase()

      Creates a default `ObservableListBase`.

  - ### Method Detail

    - #### 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