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
  `boolean`
  `addAll(E... elements)`
  A convenience method for var-arg addition of elements.
  `final void`
  `addListener(InvalidationListener listener)`
  Adds an `InvalidationListener` which will be notified whenever the `Observable` becomes invalid.
  `final void`
  `addListener(ListChangeListener<? super E> listener)`
  Add a listener to this observable list.
  `protected final void`
  `beginChange()`
  Begins a change block.
  `protected final void`
  `endChange()`
  Ends the change block.
  `protected final void`
  `fireChange(ListChangeListener.Change<? extends E> change)`
  Notifies all listeners of a change
  `protected final boolean`
  `hasListeners()`
  Returns true if there are some listeners registered for this list.
  `protected final void`
  `nextAdd(int from, int to)`
  Adds a new add operation to the change.
  `protected final void`
  `nextPermutation(int from, int to, int[] perm)`
  Adds a new permutation operation to the change.
  `protected final void`
  `nextRemove(int idx, E removed)`
  Adds a new remove operation to the change with single item removed.
  `protected final void`
  `nextRemove(int idx, List<? extends E> removed)`
  Adds a new remove operation to the change with multiple items removed.
  `protected final void`
  `nextReplace(int from, int to, List<? extends E> removed)`
  Adds a new replace operation to the change.
  `protected final void`
  `nextSet(int idx, E old)`
  Adds a new set operation to the change.
  `protected final void`
  `nextUpdate(int pos)`
  Adds a new update operation to the change.
  `void`
  `remove(int from, int to)`
  A simplified way of calling `sublist(from, to).clear()`.
  `boolean`
  `removeAll(E... elements)`
  A convenience method for var-arg usage of the `removeAll` method.
  `final void`
  `removeListener(InvalidationListener listener)`
  Removes the given listener from the list of listeners, that are notified whenever the value of the `Observable` becomes invalid.
  `final void`
  `removeListener(ListChangeListener<? super E> listener)`
  Tries to remove a listener from this observable list.
  `boolean`
  `retainAll(E... elements)`
  A convenience method for var-arg usage of the `retainAll` method.
  `boolean`
  `setAll(E... elements)`
  Clears the ObservableList and adds all the elements passed as var-args.
  `boolean`
  `setAll(Collection<? extends E> col)`
  Clears the ObservableList and adds all elements from the collection.

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

  `subscribe`

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

  `filtered, 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()`

  - ### addListener

    public final void addListener(InvalidationListener listener)
    Description copied from interface: `Observable`
    Adds an `InvalidationListener` which will be notified whenever the `Observable` becomes invalid. If the same listener is added more than once, then it will be notified more than once. That is, no check is made to ensure uniqueness.

    Note that the same actual `InvalidationListener` instance may be safely registered for different `Observables`.

    The `Observable` stores a strong reference to the listener which will prevent the listener from being garbage collected and may result in a memory leak. It is recommended to either unregister a listener by calling `removeListener` after use or to use an instance of `WeakInvalidationListener` avoid this situation.

    Specified by:
      `addListener` in interface `Observable`
    Parameters:
      `listener` - The listener to register
    See Also:
      - `Observable.removeListener(InvalidationListener)`

  - ### removeListener

    public final void removeListener(InvalidationListener listener)
    Description copied from interface: `Observable`
    Removes the given listener from the list of listeners, that are notified whenever the value of the `Observable` becomes invalid.

    If the given listener has not been previously registered (i.e. it was never added) then this method call is a no-op. If it had been previously added then it will be removed. If it had been added more than once, then only the first occurrence will be removed.

    Specified by:
      `removeListener` in interface `Observable`
    Parameters:
      `listener` - The listener to remove
    See Also:
      - `Observable.addListener(InvalidationListener)`

  - ### addListener

    public final void addListener(ListChangeListener<? super E> listener)
    Description copied from interface: `ObservableList`
    Add a listener to this observable list.
    Specified by:
      `addListener` in interface `ObservableList<E>`
    Parameters:
      `listener` - the listener for listening to the list changes

  - ### removeListener

    public final void removeListener(ListChangeListener<? super E> listener)
    Description copied from interface: `ObservableList`
    Tries to remove a listener from this observable list. If the listener is not attached to this list, nothing happens.
    Specified by:
      `removeListener` in interface `ObservableList<E>`
    Parameters:
      `listener` - a listener to remove

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

  - ### addAll

    public boolean addAll(E... elements)
    Description copied from interface: `ObservableList`
    A convenience method for var-arg addition of elements.
    Specified by:
      `addAll` in interface `ObservableList<E>`
    Parameters:
      `elements` - the elements to add
    Returns:
      true (as specified by Collection.add(E))

  - ### setAll

    public boolean setAll(E... elements)
    Description copied from interface: `ObservableList`
    Clears the ObservableList and adds all the elements passed as var-args.
    Specified by:
      `setAll` in interface `ObservableList<E>`
    Parameters:
      `elements` - the elements to set
    Returns:
      true (as specified by Collection.add(E))

  - ### setAll

    public boolean setAll(Collection<? extends E> col)
    Description copied from interface: `ObservableList`
    Clears the ObservableList and adds all elements from the collection.
    Specified by:
      `setAll` in interface `ObservableList<E>`
    Parameters:
      `col` - the collection with elements that will be added to this observableArrayList
    Returns:
      true (as specified by Collection.add(E))

  - ### removeAll

    public boolean removeAll(E... elements)
    Description copied from interface: `ObservableList`
    A convenience method for var-arg usage of the `removeAll` method.
    Specified by:
      `removeAll` in interface `ObservableList<E>`
    Parameters:
      `elements` - the elements to be removed
    Returns:
      true if list changed as a result of this call

  - ### retainAll

    public boolean retainAll(E... elements)
    Description copied from interface: `ObservableList`
    A convenience method for var-arg usage of the `retainAll` method.
    Specified by:
      `retainAll` in interface `ObservableList<E>`
    Parameters:
      `elements` - the elements to be retained
    Returns:
      true if list changed as a result of this call

  - ### remove

    public void remove(int from, int to)
    Description copied from interface: `ObservableList`
    A simplified way of calling `sublist(from, to).clear()`. As this is a common operation, ObservableList has this method for convenient usage.
    Specified by:
      `remove` in interface `ObservableList<E>`
    Parameters:
      `from` - the start of the range to remove (inclusive)
      `to` - the end of the range to remove (exclusive)