Module javafx.base
Package javafx.collections

# Class FXCollections

java.lang.Object
javafx.collections.FXCollections

public class FXCollections extends Object
Utility class that consists of static methods that are 1:1 copies of java.util.Collections methods.
The wrapper methods (like synchronizedObservableList or emptyObservableList) has exactly the same functionality as the methods in Collections, with exception that they return ObservableList and are therefore suitable for methods that require ObservableList on input.
The utility methods are here mainly for performance reasons. All methods are optimized in a way that they yield only limited number of notifications. On the other hand, java.util.Collections methods might call "modification methods" on an ObservableList multiple times, resulting in a number of notifications.

Since:
  JavaFX 2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E> ObservableList<E>`
  `checkedObservableList(ObservableList<E> list, Class<E> type)`
  Creates and returns a typesafe wrapper on top of provided observable list.
  `static <K, V> ObservableMap<K,V>`
  `checkedObservableMap(ObservableMap<K,V> map, Class<K> keyType, Class<V> valueType)`
  Creates and returns a typesafe wrapper on top of provided observable map.
  `static <E> ObservableSet<E>`
  `checkedObservableSet(ObservableSet<E> set, Class<E> type)`
  Creates and returns a typesafe wrapper on top of provided observable set.
  `static <E> ObservableList<E>`
  `concat(ObservableList<E>... lists)`
  Concatenates more observable lists into one.
  `static <T> void`
  `copy(ObservableList<? super T> dest, List<? extends T> src)`
  Copies elements from src to dest.
  `static <E> ObservableList<E>`
  `emptyObservableList()`
  Creates an empty unmodifiable observable list.
  `static <K, V> ObservableMap<K,V>`
  `emptyObservableMap()`
  Creates an empty unmodifiable observable map.
  `static <E> ObservableSet<E>`
  `emptyObservableSet()`
  Creates an empty unmodifiable observable set.
  `static <T> void`
  `fill(ObservableList<? super T> list, T obj)`
  Fills the provided list with obj.
  `static <E> ObservableList<E>`
  `observableArrayList()`
  Creates a new empty observable list that is backed by an array list.
  `static <E> ObservableList<E>`
  `observableArrayList(E... items)`
  Creates a new observable array list with `items` added to it.
  `static <E> ObservableList<E>`
  `observableArrayList(Collection<? extends E> col)`
  Creates a new observable array list and adds a content of collection `col` to it.
  `static <E> ObservableList<E>`
  `observableArrayList(Callback<E,Observable[]> extractor)`
  Creates a new empty `ObservableList` that is backed by an array list and listens to changes in observables of its items.
  `static ObservableFloatArray`
  `observableFloatArray()`
  Creates a new empty observable float array.
  `static ObservableFloatArray`
  `observableFloatArray(float... values)`
  Creates a new observable float array with `values` set to it.
  `static ObservableFloatArray`
  `observableFloatArray(ObservableFloatArray array)`
  Creates a new observable float array with copy of elements in given `array`.
  `static <K, V> ObservableMap<K,V>`
  `observableHashMap()`
  Creates a new empty observable map that is backed by a HashMap.
  `static ObservableIntegerArray`
  `observableIntegerArray()`
  Creates a new empty observable integer array.
  `static ObservableIntegerArray`
  `observableIntegerArray(int... values)`
  Creates a new observable integer array with `values` set to it.
  `static ObservableIntegerArray`
  `observableIntegerArray(ObservableIntegerArray array)`
  Creates a new observable integer array with copy of elements in given `array`.
  `static <E> ObservableList<E>`
  `observableList(List<E> list)`
  Constructs an ObservableList that is backed by the specified list.
  `static <E> ObservableList<E>`
  `observableList(List<E> list, Callback<E,Observable[]> extractor)`
  Constructs an `ObservableList` that is backed by the specified list and listens to changes in observables of its items.
  `static <K, V> ObservableMap<K,V>`
  `observableMap(Map<K,V> map)`
  Constructs an ObservableMap that is backed by the specified map.
  `static <E> ObservableSet<E>`
  `observableSet(E... elements)`
  Constructs an ObservableSet backed by a HashSet that contains all the specified elements.
  `static <E> ObservableSet<E>`
  `observableSet(Set<E> set)`
  Constructs an ObservableSet that is backed by the specified set.
  `static <T> boolean`
  `replaceAll(ObservableList<T> list, T oldVal, T newVal)`
  Replace all oldVal elements in the list with newVal element.
  `static void`
  `reverse(ObservableList list)`
  Reverses the order in the list.
  `static void`
  `rotate(ObservableList list, int distance)`
  Rotates the list by distance.
  `static void`
  `shuffle(ObservableList<?> list)`
  Shuffles all elements in the observable list.
  `static void`
  `shuffle(ObservableList list, Random rnd)`
  Shuffles all elements in the observable list.
  `static <E> ObservableList<E>`
  `singletonObservableList(E e)`
  Creates an unmodifiable observable list with single element.
  `static <T extends Comparable<? super T>>
  void`
  `sort(ObservableList<T> list)`
  Sorts the provided observable list as specified in `Collections.sort(List)`.
  `static <T> void`
  `sort(ObservableList<T> list, Comparator<? super T> comparator)`
  Sorts the provided observable list as specified in `Collections.sort(List, Comparator)`.
  `static <E> ObservableList<E>`
  `synchronizedObservableList(ObservableList<E> list)`
  Creates and returns a synchronized wrapper on top of provided observable list.
  `static <K, V> ObservableMap<K,V>`
  `synchronizedObservableMap(ObservableMap<K,V> map)`
  Creates and returns a synchronized wrapper on top of provided observable map.
  `static <E> ObservableSet<E>`
  `synchronizedObservableSet(ObservableSet<E> set)`
  Creates and returns a synchronized wrapper on top of provided observable set.
  `static <E> ObservableList<E>`
  `unmodifiableObservableList(ObservableList<E> list)`
  Creates and returns unmodifiable wrapper list on top of provided observable list.
  `static <K, V> ObservableMap<K,V>`
  `unmodifiableObservableMap(ObservableMap<K,V> map)`
  Constructs a read-only interface to the specified ObservableMap.
  `static <E> ObservableSet<E>`
  `unmodifiableObservableSet(ObservableSet<E> set)`
  Creates and returns unmodifiable wrapper on top of provided observable set.

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### observableList

    public static <E> ObservableList<E> observableList(List<E> list)
    Constructs an ObservableList that is backed by the specified list. Mutation operations on the ObservableList instance will be reported to observers that have registered on that instance.
    Note that mutation operations made directly to the underlying list are not reported to observers of any ObservableList that wraps it.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `list` - a concrete List that backs this ObservableList
    Returns:
      a newly created ObservableList

  - ### observableList

    public static <E> ObservableList<E> observableList(List<E> list, Callback<E,Observable[]> extractor)
    Constructs an `ObservableList` that is backed by the specified list and listens to changes in observables of its items. Mutation operations made directly to the underlying list are not reported to observers of any `ObservableList` that wraps it.

    The `extractor` returns observables (usually properties) of the objects in the created list. These observables are listened for changes, and the user is notified of these through an update change of an attached `ListChangeListener`. These changes are unrelated to the changes made to the observable list itself using methods such as `add` and `remove`.

    For example, a list of `Shape`s can listen to changes in the shapes' `fill` property.

    Type Parameters:
      `E` - The type of `List` to be wrapped
    Parameters:
      `list` - a concrete `List` that backs this `ObservableList`
      `extractor` - element to `Observable[]` converter
    Returns:
      a newly created `ObservableList`
    Since:
      JavaFX 2.1
    See Also:
      - `observableArrayList(javafx.util.Callback)`

  - ### observableMap

    public static <K, V> ObservableMap<K,V> observableMap(Map<K,V> map)
    Constructs an ObservableMap that is backed by the specified map. Mutation operations on the ObservableMap instance will be reported to observers that have registered on that instance.
    Note that mutation operations made directly to the underlying map are not reported to observers of any ObservableMap that wraps it.
    Type Parameters:
      `K` - the type of the wrapped key
      `V` - the type of the wrapped value
    Parameters:
      `map` - a Map that backs this ObservableMap
    Returns:
      a newly created ObservableMap

  - ### observableSet

    public static <E> ObservableSet<E> observableSet(Set<E> set)
    Constructs an ObservableSet that is backed by the specified set. Mutation operations on the ObservableSet instance will be reported to observers that have registered on that instance.
    Note that mutation operations made directly to the underlying set are not reported to observers of any ObservableSet that wraps it.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `set` - a Set that backs this ObservableSet
    Returns:
      a newly created ObservableSet
    Since:
      JavaFX 2.1

  - ### observableSet

    public static <E> ObservableSet<E> observableSet(E... elements)
    Constructs an ObservableSet backed by a HashSet that contains all the specified elements.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `elements` - elements that will be added into returned ObservableSet
    Returns:
      a newly created ObservableSet
    Since:
      JavaFX 2.1

  - ### unmodifiableObservableMap

    public static <K, V> ObservableMap<K,V> unmodifiableObservableMap(ObservableMap<K,V> map)
    Constructs a read-only interface to the specified ObservableMap. Only mutation operations made to the underlying ObservableMap will be reported to observers that have registered on the unmodifiable instance. This allows clients to track changes in a Map but disallows the ability to modify it.
    Type Parameters:
      `K` - the type of the wrapped key
      `V` - the type of the wrapped value
    Parameters:
      `map` - an ObservableMap that is to be monitored by this interface
    Returns:
      a newly created UnmodifiableObservableMap

  - ### checkedObservableMap

    public static <K, V> ObservableMap<K,V> checkedObservableMap(ObservableMap<K,V> map, Class<K> keyType, Class<V> valueType)
    Creates and returns a typesafe wrapper on top of provided observable map.
    Type Parameters:
      `K` - the type of the wrapped key
      `V` - the type of the wrapped value
    Parameters:
      `map` - an Observable map to be wrapped
      `keyType` - the type of key that `map` is permitted to hold
      `valueType` - the type of value that `map` is permitted to hold
    Returns:
      a dynamically typesafe view of the specified map
    Since:
      JavaFX 8.0
    See Also:
      - `Collections.checkedMap(java.util.Map, java.lang.Class, java.lang.Class)`

  - ### synchronizedObservableMap

    public static <K, V> ObservableMap<K,V> synchronizedObservableMap(ObservableMap<K,V> map)
    Creates and returns a synchronized wrapper on top of provided observable map.
    Type Parameters:
      `K` - the type of the wrapped key
      `V` - the type of the wrapped value
    Parameters:
      `map` - the map to be "wrapped" in a synchronized map.
    Returns:
      A synchronized version of the observable map
    Since:
      JavaFX 8.0
    See Also:
      - `Collections.synchronizedMap(java.util.Map)`

  - ### emptyObservableMap

    public static <K, V> ObservableMap<K,V> emptyObservableMap()
    Creates an empty unmodifiable observable map.
    Type Parameters:
      `K` - the type of the wrapped key
      `V` - the type of the wrapped value
    Returns:
      An empty unmodifiable observable map
    Since:
      JavaFX 8.0
    See Also:
      - `Collections.emptyMap()`

  - ### observableIntegerArray

    public static ObservableIntegerArray observableIntegerArray()
    Creates a new empty observable integer array.
    Returns:
      a newly created ObservableIntegerArray
    Since:
      JavaFX 8.0

  - ### observableIntegerArray

    public static ObservableIntegerArray observableIntegerArray(int... values)
    Creates a new observable integer array with `values` set to it.
    Parameters:
      `values` - the values that will be in the new observable integer array
    Returns:
      a newly created ObservableIntegerArray
    Since:
      JavaFX 8.0

  - ### observableIntegerArray

    public static ObservableIntegerArray observableIntegerArray(ObservableIntegerArray array)
    Creates a new observable integer array with copy of elements in given `array`.
    Parameters:
      `array` - observable integer array to copy
    Returns:
      a newly created ObservableIntegerArray
    Since:
      JavaFX 8.0

  - ### observableFloatArray

    public static ObservableFloatArray observableFloatArray()
    Creates a new empty observable float array.
    Returns:
      a newly created ObservableFloatArray
    Since:
      JavaFX 8.0

  - ### observableFloatArray

    public static ObservableFloatArray observableFloatArray(float... values)
    Creates a new observable float array with `values` set to it.
    Parameters:
      `values` - the values that will be in the new observable float array
    Returns:
      a newly created ObservableFloatArray
    Since:
      JavaFX 8.0

  - ### observableFloatArray

    public static ObservableFloatArray observableFloatArray(ObservableFloatArray array)
    Creates a new observable float array with copy of elements in given `array`.
    Parameters:
      `array` - observable float array to copy
    Returns:
      a newly created ObservableFloatArray
    Since:
      JavaFX 8.0

  - ### observableArrayList

    public static <E> ObservableList<E> observableArrayList()
    Creates a new empty observable list that is backed by an array list.
    Type Parameters:
      `E` - The type of List to be wrapped
    Returns:
      a newly created ObservableList
    See Also:
      - `observableList(java.util.List)`

  - ### observableArrayList

    public static <E> ObservableList<E> observableArrayList(Callback<E,Observable[]> extractor)
    Creates a new empty `ObservableList` that is backed by an array list and listens to changes in observables of its items.

    The `extractor` returns observables (usually properties) of the objects in the created list. These observables are listened for changes and the user is notified of these through an update change of an attached `ListChangeListener`. These changes are unrelated to the changes made to the observable list itself using methods such as `add` and `remove`.

    For example, a list of `Shape`s can listen to changes in the shapes' `fill` property.

    Type Parameters:
      `E` - The type of `List` to be wrapped
    Parameters:
      `extractor` - element to `Observable[]` converter
    Returns:
      a newly created `ObservableList`
    Since:
      JavaFX 2.1
    See Also:
      - `observableList(java.util.List, javafx.util.Callback)`

  - ### observableArrayList

    public static <E> ObservableList<E> observableArrayList(E... items)
    Creates a new observable array list with `items` added to it.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `items` - the items that will be in the new observable ArrayList
    Returns:
      a newly created observableArrayList
    See Also:
      - `observableArrayList()`

  - ### observableArrayList

    public static <E> ObservableList<E> observableArrayList(Collection<? extends E> col)
    Creates a new observable array list and adds a content of collection `col` to it.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `col` - a collection which content should be added to the observableArrayList
    Returns:
      a newly created observableArrayList

  - ### observableHashMap

    public static <K, V> ObservableMap<K,V> observableHashMap()
    Creates a new empty observable map that is backed by a HashMap.
    Type Parameters:
      `K` - the type of the wrapped key
      `V` - the type of the wrapped value
    Returns:
      a newly created observable HashMap

  - ### concat

    public static <E> ObservableList<E> concat(ObservableList<E>... lists)
    Concatenates more observable lists into one. The resulting list would be backed by an array list.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `lists` - lists to concatenate
    Returns:
      new observable array list concatenated from the arguments

  - ### unmodifiableObservableList

    public static <E> ObservableList<E> unmodifiableObservableList(ObservableList<E> list)
    Creates and returns unmodifiable wrapper list on top of provided observable list.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `list` - an ObservableList that is to be wrapped
    Returns:
      an ObserableList wrapper that is unmodifiable
    See Also:
      - `Collections.unmodifiableList(java.util.List)`

  - ### checkedObservableList

    public static <E> ObservableList<E> checkedObservableList(ObservableList<E> list, Class<E> type)
    Creates and returns a typesafe wrapper on top of provided observable list.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `list` - an Observable list to be wrapped
      `type` - the type of element that `list` is permitted to hold
    Returns:
      a dynamically typesafe view of the specified list
    See Also:
      - `Collections.checkedList(java.util.List, java.lang.Class)`

  - ### synchronizedObservableList

    public static <E> ObservableList<E> synchronizedObservableList(ObservableList<E> list)
    Creates and returns a synchronized wrapper on top of provided observable list.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `list` - the list to be "wrapped" in a synchronized list.
    Returns:
      A synchronized version of the observable list
    See Also:
      - `Collections.synchronizedList(java.util.List)`

  - ### emptyObservableList

    public static <E> ObservableList<E> emptyObservableList()
    Creates an empty unmodifiable observable list.
    Type Parameters:
      `E` - The type of List to be wrapped
    Returns:
      An empty unmodifiable observable list
    See Also:
      - `Collections.emptyList()`

  - ### singletonObservableList

    public static <E> ObservableList<E> singletonObservableList(E e)
    Creates an unmodifiable observable list with single element.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `e` - the only elements that will be contained in this singleton observable list
    Returns:
      a singleton observable list
    See Also:
      - `Collections.singletonList(java.lang.Object)`

  - ### unmodifiableObservableSet

    public static <E> ObservableSet<E> unmodifiableObservableSet(ObservableSet<E> set)
    Creates and returns unmodifiable wrapper on top of provided observable set.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `set` - an ObservableSet that is to be wrapped
    Returns:
      an ObserableSet wrapper that is unmodifiable
    Since:
      JavaFX 8.0
    See Also:
      - `Collections.unmodifiableSet(java.util.Set)`

  - ### checkedObservableSet

    public static <E> ObservableSet<E> checkedObservableSet(ObservableSet<E> set, Class<E> type)
    Creates and returns a typesafe wrapper on top of provided observable set.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `set` - an Observable set to be wrapped
      `type` - the type of element that `set` is permitted to hold
    Returns:
      a dynamically typesafe view of the specified set
    Since:
      JavaFX 8.0
    See Also:
      - `Collections.checkedSet(java.util.Set, java.lang.Class)`

  - ### synchronizedObservableSet

    public static <E> ObservableSet<E> synchronizedObservableSet(ObservableSet<E> set)
    Creates and returns a synchronized wrapper on top of provided observable set.
    Type Parameters:
      `E` - The type of List to be wrapped
    Parameters:
      `set` - the set to be "wrapped" in a synchronized set.
    Returns:
      A synchronized version of the observable set
    Since:
      JavaFX 8.0
    See Also:
      - `Collections.synchronizedSet(java.util.Set)`

  - ### emptyObservableSet

    public static <E> ObservableSet<E> emptyObservableSet()
    Creates an empty unmodifiable observable set.
    Type Parameters:
      `E` - The type of List to be wrapped
    Returns:
      An empty unmodifiable observable set
    Since:
      JavaFX 8.0
    See Also:
      - `Collections.emptySet()`

  - ### copy

    public static <T> void copy(ObservableList<? super T> dest, List<? extends T> src)
    Copies elements from src to dest. Fires only one change notification on dest.
    Type Parameters:
      `T` - The type of List to be wrapped
    Parameters:
      `dest` - the destination observable list
      `src` - the source list
    See Also:
      - `Collections.copy(java.util.List, java.util.List)`

  - ### fill

    public static <T> void fill(ObservableList<? super T> list, T obj)
    Fills the provided list with obj. Fires only one change notification on the list.
    Type Parameters:
      `T` - The type of List to be wrapped
    Parameters:
      `list` - the list to fill
      `obj` - the object to fill the list with
    See Also:
      - `Collections.fill(java.util.List, java.lang.Object)`

  - ### replaceAll

    public static <T> boolean replaceAll(ObservableList<T> list, T oldVal, T newVal)
    Replace all oldVal elements in the list with newVal element. Fires only one change notification on the list.
    Type Parameters:
      `T` - The type of List to be wrapped
    Parameters:
      `list` - the list which will have it's elements replaced
      `oldVal` - the element that is going to be replace
      `newVal` - the replacement
    Returns:
      true if the list was modified
    See Also:
      - `Collections.replaceAll(java.util.List, java.lang.Object, java.lang.Object)`

  - ### reverse

    public static void reverse(ObservableList list)
    Reverses the order in the list. Fires only one change notification on the list.
    Parameters:
      `list` - the list to be reversed
    See Also:
      - `Collections.reverse(java.util.List)`

  - ### rotate

    public static void rotate(ObservableList list, int distance)
    Rotates the list by distance. Fires only one change notification on the list.
    Parameters:
      `list` - the list to be rotated
      `distance` - the distance of rotation
    See Also:
      - `Collections.rotate(java.util.List, int)`

  - ### shuffle

    public static void shuffle(ObservableList<?> list)
    Shuffles all elements in the observable list. Fires only one change notification on the list.
    Parameters:
      `list` - the list to shuffle
    See Also:
      - `Collections.shuffle(java.util.List)`

  - ### shuffle

    public static void shuffle(ObservableList list, Random rnd)
    Shuffles all elements in the observable list. Fires only one change notification on the list.
    Parameters:
      `list` - the list to be shuffled
      `rnd` - the random generator used for shuffling
    See Also:
      - `Collections.shuffle(java.util.List, java.util.Random)`

  - ### sort

    public static <T extends Comparable<? super T>> void sort(ObservableList<T> list)
    Sorts the provided observable list as specified in `Collections.sort(List)`. Fires only one change notification on the list.
    Type Parameters:
      `T` - the type of elements in this list
    Parameters:
      `list` - the list to be sorted

  - ### sort

    public static <T> void sort(ObservableList<T> list, Comparator<? super T> comparator)
    Sorts the provided observable list as specified in `Collections.sort(List, Comparator)`. Fires only one change notification on the list.
    Type Parameters:
      `T` - the type of elements in this list
    Parameters:
      `list` - the list to sort
      `comparator` - the comparator to determine the order of the list. A `null` value indicates that the elements' natural ordering should be used.