Class Observables


  • public class Observables
    extends Object
    Contains static methods to operate on or return Observables.
    Since:
    1.0
    • Constructor Detail

      • Observables

        public Observables()
    • Method Detail

      • observeDelayedValue

        public static <T> IObservableValue<T> observeDelayedValue​(int delay,
                                                                  IObservableValue<T> observable)
        Returns an observable which delays notification of value change events from observable until delay milliseconds have elapsed since the last change event. This observable helps to boost performance in situations where an observable has computationally expensive listeners or many dependencies. A common use of this observable is to delay validation of user input until the user stops typing in a UI field.

        To notify about pending changes, the returned observable fires a stale event when the wrapped observable value fires a change event, and remains stale until the delay has elapsed and the value change is fired. A call to getValue() while a value change is pending will fire the value change immediately, short-circuiting the delay.

        Note:

        • Use SWTObservables.observeDelayedValue() instead when the target observable is observing a SWT Control, or ViewersObservables.observeDelayedValue() when the target observable is observing a JFace Viewer. These observables ensure that pending value changes are fired when the underlying control loses focus. (Otherwise, it is possible for pending changes to be lost if a window is closed before the delay has elapsed.)
        • This observable does not forward ValueChangingEvent events from a wrapped IVetoableValue.
        Type Parameters:
        T - the value type
        Parameters:
        delay - the delay in milliseconds
        observable - the observable being delayed
        Returns:
        an observable which delays notification of value change events from observable until delay milliseconds have elapsed since the last change event.
        Since:
        1.2
      • unmodifiableObservableValue

        public static <T> IObservableValue<T> unmodifiableObservableValue​(IObservableValue<T> value)
        Returns an unmodifiable observable value backed by the given observable value.
        Type Parameters:
        T - the value type
        Parameters:
        value - the value to wrap in an unmodifiable value
        Returns:
        an unmodifiable observable value backed by the given observable value
        Since:
        1.1
      • constantObservableValue

        public static <T> IObservableValue<T> constantObservableValue​(Realm realm,
                                                                      T value,
                                                                      Object valueType)
        Returns an observable value with the given constant value.
        Type Parameters:
        T - the value type
        Parameters:
        realm - the observable's realm
        value - the observable's constant value
        valueType - the observable's value type
        Returns:
        an immutable observable value with the given constant value
        Since:
        1.1
      • constantObservableValue

        public static <T> IObservableValue<T> constantObservableValue​(Realm realm,
                                                                      T value)
        Returns an observable value with the given constant value.
        Type Parameters:
        T -
        Parameters:
        realm - the observable's realm
        value - the observable's constant value
        Returns:
        an immutable observable value with the given constant value
        Since:
        1.1
      • constantObservableValue

        public static <T> IObservableValue<T> constantObservableValue​(T value,
                                                                      T valueType)
        Returns an observable value with the given constant value.
        Type Parameters:
        T - the value type
        Parameters:
        value - the observable's constant value
        valueType - the observable's value type
        Returns:
        an immutable observable value with the given constant value
        Since:
        1.1
      • constantObservableValue

        public static <T> IObservableValue<T> constantObservableValue​(T value)
        Returns an observable value with the given constant value.
        Type Parameters:
        T -
        Parameters:
        value - the observable's constant value
        Returns:
        an immutable observable value with the given constant value
        Since:
        1.1
      • unmodifiableObservableList

        public static <E> IObservableList<E> unmodifiableObservableList​(IObservableList<E> list)
        Returns an unmodifiable observable list backed by the given observable list.
        Type Parameters:
        E - the element type
        Parameters:
        list - the list to wrap in an unmodifiable list
        Returns:
        an unmodifiable observable list backed by the given observable list
      • unmodifiableObservableSet

        public static <E> IObservableSet<E> unmodifiableObservableSet​(IObservableSet<E> set)
        Returns an unmodifiable observable set backed by the given observable set.
        Type Parameters:
        E -
        Parameters:
        set - the set to wrap in an unmodifiable set
        Returns:
        an unmodifiable observable set backed by the given observable set
        Since:
        1.1
      • unmodifiableObservableMap

        public static <K,​V> IObservableMap<K,​V> unmodifiableObservableMap​(IObservableMap<K,​V> map)
        Returns an unmodifiable observable map backed by the given observable map.
        Type Parameters:
        K - map key type
        V - map value type
        Parameters:
        map - the map to wrap in an unmodifiable map
        Returns:
        an unmodifiable observable map backed by the given observable map.
        Since:
        1.2
      • emptyObservableList

        public static <E> IObservableList<E> emptyObservableList()
        Returns an empty observable list. The returned list continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the list element type
        Returns:
        an empty observable list.
      • emptyObservableList

        public static <E> IObservableList<E> emptyObservableList​(Object elementType)
        Returns an empty observable list of the given element type. The returned list continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the list element type
        Parameters:
        elementType - the element type of the returned list
        Returns:
        an empty observable list
        Since:
        1.1
      • emptyObservableList

        public static <E> IObservableList<E> emptyObservableList​(Realm realm)
        Returns an empty observable list belonging to the given realm. The returned list continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the list element type
        Parameters:
        realm - the realm of the returned list
        Returns:
        an empty observable list.
      • emptyObservableList

        public static <E> IObservableList<E> emptyObservableList​(Realm realm,
                                                                 Object elementType)
        Returns an empty observable list of the given element type and belonging to the given realm. The returned list continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the list element type
        Parameters:
        realm - the realm of the returned list
        elementType - the element type of the returned list
        Returns:
        an empty observable list
        Since:
        1.1
      • emptyObservableSet

        public static <E> IObservableSet<E> emptyObservableSet()
        Returns an empty observable set. The returned set continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the set element type
        Returns:
        an empty observable set.
      • emptyObservableSet

        public static <E> IObservableSet<E> emptyObservableSet​(Object elementType)
        Returns an empty observable set of the given element type. The returned set continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the set element type
        Parameters:
        elementType - the element type of the returned set
        Returns:
        an empty observable set
        Since:
        1.1
      • emptyObservableSet

        public static <E> IObservableSet<E> emptyObservableSet​(Realm realm)
        Returns an empty observable set belonging to the given realm. The returned set continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the set element type
        Parameters:
        realm - the realm of the returned set
        Returns:
        an empty observable set.
      • emptyObservableSet

        public static <E> IObservableSet<E> emptyObservableSet​(Realm realm,
                                                               Object elementType)
        Returns an empty observable set of the given element type and belonging to the given realm. The returned set continues to work after it has been disposed of and can be disposed of multiple times.
        Type Parameters:
        E - the set element type
        Parameters:
        realm - the realm of the returned set
        elementType - the element type of the returned set
        Returns:
        an empty observable set
        Since:
        1.1
      • staticObservableSet

        public static <E> IObservableSet<E> staticObservableSet​(Set<E> set)
        Returns an observable set backed by the given set.
        Type Parameters:
        E - the set element type
        Parameters:
        set - the set to wrap in an IObservableSet
        Returns:
        an observable set backed by the given set
      • staticObservableSet

        public static <E> IObservableSet<E> staticObservableSet​(Set<E> set,
                                                                Object elementType)
        Returns an observable set of the given element type, backed by the given set.
        Type Parameters:
        E - the set element type
        Parameters:
        set - the set to wrap in an IObservableSet
        elementType - the element type of the returned set
        Returns:
        Returns an observable set backed by the given unchanging set
        Since:
        1.1
      • staticObservableSet

        public static <E> IObservableSet<E> staticObservableSet​(Realm realm,
                                                                Set<E> set)
        Returns an observable set belonging to the given realm, backed by the given set.
        Type Parameters:
        E -
        Parameters:
        realm - the realm of the returned set
        set - the set to wrap in an IObservableSet
        Returns:
        an observable set backed by the given unchanging set
      • staticObservableSet

        public static <E> IObservableSet<E> staticObservableSet​(Realm realm,
                                                                Set<E> set,
                                                                Object elementType)
        Returns an observable set of the given element type and belonging to the given realm, backed by the given set.
        Type Parameters:
        E - the set element type
        Parameters:
        realm - the realm of the returned set
        set - the set to wrap in an IObservableSet
        elementType - the element type of the returned set
        Returns:
        an observable set backed by the given set
        Since:
        1.1
      • proxyObservableValue

        public static <T> IObservableValue<T> proxyObservableValue​(IObservableValue<T> target)
        Returns an observable value that contains the same value as the given observable, and fires the same events as the given observable, but can be disposed of without disposing of the wrapped observable.
        Type Parameters:
        T - the value type
        Parameters:
        target - the observable value to wrap
        Returns:
        a disposable proxy for the given observable value.
        Since:
        1.2
      • proxyObservableSet

        public static <E> IObservableSet<E> proxyObservableSet​(IObservableSet<E> target)
        Returns an observable set that contains the same elements as the given set, and fires the same events as the given set, but can be disposed of without disposing of the wrapped set.
        Type Parameters:
        E - the set element type
        Parameters:
        target - the set to wrap
        Returns:
        a disposable proxy for the given observable set
      • proxyObservableList

        public static <E> IObservableList<E> proxyObservableList​(IObservableList<E> target)
        Returns an observable list that contains the same elements as the given list, and fires the same events as the given list, but can be disposed of without disposing of the wrapped list.
        Type Parameters:
        E - the list element type
        Parameters:
        target - the list to wrap
        Returns:
        a disposable proxy for the given observable list
        Since:
        1.1
      • proxyObservableMap

        public static <K,​V> IObservableMap<K,​V> proxyObservableMap​(IObservableMap<K,​V> target)
        Returns an observable map that contains the same entries as the given map, and fires the same events as the given map, but can be disposed of without disposing of the wrapped map.
        Type Parameters:
        K - the map key type
        V - the map value type
        Parameters:
        target - the map to wrap
        Returns:
        a disposable proxy for the given observable map
        Since:
        1.2
      • staticObservableList

        public static <E> IObservableList<E> staticObservableList​(List<E> list)
        Returns an observable list backed by the given list.
        Type Parameters:
        E - the list element type
        Parameters:
        list - the list to wrap in an IObservableList
        Returns:
        an observable list backed by the given unchanging list
      • staticObservableList

        public static <E> IObservableList<E> staticObservableList​(List<E> list,
                                                                  Object elementType)
        Returns an observable list of the given element type, backed by the given list.
        Type Parameters:
        E - the list element type
        Parameters:
        list - the list to wrap in an IObservableList
        elementType - the element type of the returned list
        Returns:
        an observable list backed by the given unchanging list
        Since:
        1.1
      • staticObservableList

        public static <E> IObservableList<E> staticObservableList​(Realm realm,
                                                                  List<E> list)
        Returns an observable list belonging to the given realm, backed by the given list.
        Type Parameters:
        E - the list element type
        Parameters:
        realm - the realm of the returned list
        list - the list to wrap in an IObservableList
        Returns:
        an observable list backed by the given unchanging list
      • staticObservableList

        public static <E> IObservableList<E> staticObservableList​(Realm realm,
                                                                  List<E> list,
                                                                  Object elementType)
        Returns an observable list of the given element type and belonging to the given realm, backed by the given list.
        Type Parameters:
        E - the list element type
        Parameters:
        realm - the realm of the returned list
        list - the list to wrap in an IObservableList
        elementType - the element type of the returned list
        Returns:
        an observable list backed by the given unchanging list
        Since:
        1.1
      • observeStale

        public static IObservableValue<Boolean> observeStale​(IObservable observable)
        Returns an observable value of type Boolean.TYPE which tracks whether the given observable is stale.
        Parameters:
        observable - the observable to track
        Returns:
        an observable value which tracks whether the given observable is stale
        Since:
        1.1
      • observeMapEntry

        public static <K,​V> IObservableValue<V> observeMapEntry​(IObservableMap<K,​V> map,
                                                                      K key)
        Returns an observable value that tracks changes to the value of an observable map's entry specified by its key.

        The state where the key does not exist in the map is equivalent to the state where the key exists and its value is null. The transition between these two states is not considered a value change and no event is fired.

        Type Parameters:
        K - the map key type
        V - the map value type
        Parameters:
        map - the observable map whose entry will be tracked.
        key - the key identifying the map entry to track.
        Returns:
        an observable value that tracks the value associated with the specified key in the given map
        Since:
        1.2
      • observeMapEntry

        public static <K,​V> IObservableValue<V> observeMapEntry​(IObservableMap<K,​V> map,
                                                                      K key,
                                                                      Object valueType)
        Returns an observable value that tracks changes to the value of an observable map's entry specified by its key.

        The state where the key does not exist in the map is equivalent to the state where the key exists and its value is null. The transition between these two states is not considered a value change and no event is fired.

        Type Parameters:
        K - the map key type
        V - the map value type
        Parameters:
        map - the observable map whose entry will be tracked.
        key - the key identifying the map entry to track.
        valueType - the type of the value. May be null, meaning the value is untyped.
        Returns:
        an observable value that tracks the value associated with the specified key in the given map
        Since:
        1.1
      • mapEntryValueFactory

        public static <K,​V> IObservableFactory<K,​IObservableValue<V>> mapEntryValueFactory​(IObservableMap<K,​V> map,
                                                                                                       Object valueType)
        Returns a factory for creating observable values tracking the value of the observable map entry identified by a particular key.
        Type Parameters:
        K - the map key type
        V - the map value type
        Parameters:
        map - the observable map whose entry will be tracked.
        valueType - the type of the value. May be null, meaning the value is untyped.
        Returns:
        a factory for creating observable values tracking the value of the observable map entry identified by a particular key object.
        Since:
        1.1
      • observeDetailMapEntry

        public static <K,​V> IObservableValue<V> observeDetailMapEntry​(IObservableMap<K,​V> map,
                                                                            IObservableValue<K> master,
                                                                            Object valueType)
        Helper method for MasterDetailObservables.detailValue(master, mapEntryValueFactory(map, valueType), valueType).
        Type Parameters:
        K - the map key type
        V - the map value type
        Parameters:
        map - the observable map whose entry will be tracked.
        master - the observable value that identifies which map entry to track.
        valueType - the type of the value. May be null, meaning the value is untyped.
        Returns:
        an observable value tracking the current value of the specified key in the given map an observable value that tracks the current value of the named property for the current value of the master observable value
        Since:
        1.1
      • pipe

        public static <T> void pipe​(IObservableValue<T> source,
                                    IObservableValue<? super T> destination)
        Copies the current value of the source observable to the destination observable, and upon value change events fired by the source observable, updates the destination observable accordingly, until the source observable is disposed. This method assumes that both observables are on the same realm.
        Type Parameters:
        T - the value type
        Parameters:
        source - the source observable
        destination - the destination observable
        Since:
        1.2