Package com.github.stasgora.observetree

Class Observable

  • Direct Known Subclasses:
    SettableProperty
    public abstract class Observable
extends java.lang.Object
    Base Observable class that holds a list of listeners and notifies them when it changes. Use one of the add(Set, ChangeListener) methods to register a listener.

    To signal that the Observable has changed call onValueChanged() from the extending class. When notificationMethod is true, the changing entity should additionally call notifyListeners() when it wants the callbacks to fire.

    Use notificationMethod flag to configure whether notifyListeners() should be called:

    Observables can create a tree structure. For creating the relations use addSubObservable(Observable)
    Cycles are not supported.

    • Calling onValueChanged() marks the Observable and all its ancestors as changed
    • Calling notifyListeners():
      • resets the Observable changed flag
      • invokes the listeners of all descendant and ancestor Observables that are currently marked as changed
      The listeners are called in order of their priority (globally) - first the listeners with the highest priority from all the Observables will be called, etc. The order at which the listeners with the same priority are called is undefined.

    Example use:
    With several child Observables grouped under a single parent, multiple independent modifications can be made to the children. Then the notifyListeners() can be called only once on the parent object to notify all the listeners including the children's.

    Author:
    Stanisław Góra
    See Also:
    SettableProperty, SettableObservable, ChangeListener, ListenerPriority, ListenerNotification

    • Constructor Summary

      Constructors 
      Constructor Description
      Observable()  

    • Method Summary

      Modifier and Type Method Description
      protected boolean add​(java.util.Set<ListenerEntry> listenerSet, ChangeListener listener)
      Utility method used internally that contains logic associated with adding a listener to a specified set
      protected boolean add​(java.util.Set<ListenerEntry> listenerSet, ChangeListener listener, int priority)
      Utility method used internally that contains logic associated with adding a listener to a specified set
      protected boolean add​(java.util.Set<ListenerEntry> listenerSet, ChangeListener listener, ListenerPriority priority)
      Utility method used internally that contains logic associated with adding a listener to a specified set
      protected boolean addChild​(Observable observable)
      Sets the specified Observable as a child of this Observable.
      boolean addListener​(ChangeListener listener)
      Adds the specified listener to the list of listeners with the default priority ListenerPriority.NORMAL (0).
      boolean addListener​(ChangeListener listener, int priority)
      Adds the specified listener to the list of listeners with the specified priority.
      boolean addListener​(ChangeListener listener, ListenerPriority priority)
      Adds the specified listener to the list of listeners with the specified priority.
      protected boolean addParent​(Observable observable)
      Sets the specified Observable as a parent of this Observable.
      protected void addSubObservable​(Observable observable)
      Adds the specified Observable to the tree as a child of this Observable.
      void clearListeners()
      Removes all the listeners from this Observable
      void copyListeners​(Observable observable)
      Copies all the listeners from this Observable to a specified Observable.
      java.util.Set<Observable> getChildren()
      Returns children of this Observable
      java.util.Set<Observable> getParents()
      Returns parents of this Observable
      void notifyListeners()
      Invokes the listeners of all descendant and ancestor Observables that are currently marked as changed.
      protected void onValueChanged()
      Marks the Observable and all its ancestors as changed.
      protected boolean remove​(java.util.Set<ListenerEntry> listenerSet, ChangeListener listener)
      Utility method used internally that contains logic associated with removing a listener from a specified set
      protected boolean removeChild​(Observable observable)
      Removes the specified Observable from children of this Observable.
      boolean removeListener​(ChangeListener listener)
      Removes the specified listener from the list of listeners.
      protected boolean removeParent​(Observable observable)
      Removes the specified Observable from parents of this Observable.
      protected void removeSubObservable​(Observable observable)
      Removes the specified Observable from the tree.
      void setUnchanged​(boolean traverseTree)
      Resets the changed flag on this object and - if the traverseTree flag is set to true - all descendant and ancestor Observables that are currently marked as changed.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • notificationMethod

        public transient ListenerNotification notificationMethod
        Listeners notification method

    • Constructor Detail

      • Observable

        public Observable()

    • Method Detail

      • addListener

        public boolean addListener​(ChangeListener listener)
        Adds the specified listener to the list of listeners with the default priority ListenerPriority.NORMAL (0).
        Parameters:
        listener - element to be added
        Returns:
        true if the listener was successfully added. false if it was already present

      • addListener

        public boolean addListener​(ChangeListener listener,
                           ListenerPriority priority)
        Adds the specified listener to the list of listeners with the specified priority.
        Parameters:
        listener - element to be added
        priority - priority of this listener
        Returns:
        true if the listener was successfully added. false if it was already present

      • addListener

        public boolean addListener​(ChangeListener listener,
                           int priority)
        Adds the specified listener to the list of listeners with the specified priority.
        Parameters:
        listener - element to be added
        priority - priority of this listener
        Returns:
        true if the listener was successfully added. false if it was already present

      • removeListener

        public boolean removeListener​(ChangeListener listener)
        Removes the specified listener from the list of listeners.
        Parameters:
        listener - element to be removed
        Returns:
        true if the listener was successfully removed. false if it was not found

      • addSubObservable

        protected void addSubObservable​(Observable observable)
        Adds the specified Observable to the tree as a child of this Observable. This method is recommended for creating the Observable relations instead of plain addParent(Observable) and addChild(Observable) as it binds Observables both ways.
        Parameters:
        observable - element to be inserted into the tree as a child of this Observable

      • removeSubObservable

        protected void removeSubObservable​(Observable observable)
        Removes the specified Observable from the tree. This method is recommended for removing Observable relations instead of plain removeParent(Observable) and removeChild(Observable) as it unbinds Observables both ways.
        Parameters:
        observable - element to be removed from the tree

      • onValueChanged

        protected void onValueChanged()
        Marks the Observable and all its ancestors as changed. This method should be called inside a class extending Observable after a change was made.

      • notifyListeners

        public void notifyListeners()
        Invokes the listeners of all descendant and ancestor Observables that are currently marked as changed. Resets the changed flag. The listeners are called in order of their priority (globally) - first the listeners with the highest priority from all the Observables will be called, etc. The order at which the listeners with the same priority are called is undefined.

      • copyListeners

        public void copyListeners​(Observable observable)
        Copies all the listeners from this Observable to a specified Observable.
        Parameters:
        observable - element to copy the listeners to

      • clearListeners

        public void clearListeners()
        Removes all the listeners from this Observable

      • setUnchanged

        public void setUnchanged​(boolean traverseTree)
        Resets the changed flag on this object and - if the traverseTree flag is set to true - all descendant and ancestor Observables that are currently marked as changed.
        Parameters:
        traverseTree - whether to set all descendant and ancestor as unchanged

      • add

        protected boolean add​(java.util.Set<ListenerEntry> listenerSet,
                      ChangeListener listener)
        Utility method used internally that contains logic associated with adding a listener to a specified set
        Parameters:
        listenerSet - set to operate onto
        listener - element to be added
        Returns:
        true if the listener was successfully added. false if it was already present

      • add

        protected boolean add​(java.util.Set<ListenerEntry> listenerSet,
                      ChangeListener listener,
                      ListenerPriority priority)
        Utility method used internally that contains logic associated with adding a listener to a specified set
        Parameters:
        listenerSet - set to operate onto
        listener - element to be added
        priority - priority of this listener
        Returns:
        true if the listener was successfully added. false if it was already present

      • add

        protected boolean add​(java.util.Set<ListenerEntry> listenerSet,
                      ChangeListener listener,
                      int priority)
        Utility method used internally that contains logic associated with adding a listener to a specified set
        Parameters:
        listenerSet - set to operate onto
        listener - element to be added
        priority - priority of this listener
        Returns:
        true if the listener was successfully added. false if it was already present

      • remove

        protected boolean remove​(java.util.Set<ListenerEntry> listenerSet,
                         ChangeListener listener)
        Utility method used internally that contains logic associated with removing a listener from a specified set
        Parameters:
        listenerSet - set to operate onto
        listener - element to be removed
        Returns:
        true if the listener was successfully removed. false if it was not found

      • addParent

        protected boolean addParent​(Observable observable)
        Sets the specified Observable as a parent of this Observable. Note: this creates only one way binding. addSubObservable(Observable) method is recommended for setting up Observable relations.
        Parameters:
        observable - parent to be added
        Returns:
        true if the Observable was successfully added. false if it was already present

      • removeParent

        protected boolean removeParent​(Observable observable)
        Removes the specified Observable from parents of this Observable. Note: this removed one way binding only. removeSubObservable(Observable) method is recommended for removing Observable relations.
        Parameters:
        observable - parent to be removed
        Returns:
        true if the Observable was successfully removed. false if it was not found

      • addChild

        protected boolean addChild​(Observable observable)
        Sets the specified Observable as a child of this Observable. Note: this creates only one way binding. addSubObservable(Observable) method is recommended for setting up Observable relations.
        Parameters:
        observable - child to be added
        Returns:
        true if the Observable was successfully added. false if it was already present

      • removeChild

        protected boolean removeChild​(Observable observable)
        Removes the specified Observable from children of this Observable. Note: this removed one way binding only. removeSubObservable(Observable) method is recommended for removing Observable relations.
        Parameters:
        observable - child to be removed
        Returns:
        true if the Observable was successfully removed. false if it was not found

      • getParents

        public java.util.Set<Observable> getParents()
        Returns parents of this Observable
        Returns:
        a set containing all the parents of this object

      • getChildren

        public java.util.Set<Observable> getChildren()
        Returns children of this Observable
        Returns:
        a set containing all the children of this object