- java.lang.Object
-
- io.github.stasgora.observetree.Observable
-
- Direct Known Subclasses:
SettableProperty
public abstract class Observable extends Object
BaseObservable
class that holds a list of listeners and notifies them when it changes. Use one of theaddListener(ChangeListener)
methods to register a listener.To signal that the
Observable
has changed callonValueChanged()
from the extending class. WhennotificationMethod
isListenerNotification.MANUAL
, the changing entity should additionally callnotifyListeners()
when it wants the callbacks to fire.Use
notificationMethod
flag to configure whethernotifyListeners()
should be called:- automatically, immediately after a
onValueChanged()
was called - manually, through
notifyListeners()
(useful for complex multistage changes)
Observables
can create a tree structure. For creating the relations useaddSubObservable(Observable)
Cycles are not supported.- Calling
onValueChanged()
marks theObservable
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
Observables
will be called, etc. The order at which the listeners with the same priority are called is undefined. - resets the
Example use:
With several childObservables
grouped under a single parent, multiple independent modifications can be made to the children. Then thenotifyListeners()
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
-
-
Field Summary
Fields Modifier and Type Field Description ListenerNotification
notificationMethod
Listeners notification method
-
Constructor Summary
Constructors Constructor Description Observable()
-
Method Summary
Modifier and Type Method Description protected boolean
add(Set<ListenerEntry> listenerSet, ChangeListener listener)
Utility method used internally that contains logic associated with adding alistener
to a specifiedset
protected boolean
add(Set<ListenerEntry> listenerSet, ChangeListener listener, int priority)
Utility method used internally that contains logic associated with adding alistener
to a specifiedset
protected boolean
add(Set<ListenerEntry> listenerSet, ChangeListener listener, ListenerPriority priority)
Utility method used internally that contains logic associated with adding alistener
to a specifiedset
protected boolean
addChild(Observable observable)
Sets the specifiedObservable
as a child of thisObservable
.boolean
addListener(ChangeListener listener)
Adds the specified listener to the list of listeners with the default priorityListenerPriority.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 specifiedObservable
as a parent of thisObservable
.protected void
addSubObservable(Observable observable)
Adds the specifiedObservable
to the tree as a child of thisObservable
.void
clearListeners()
Removes all the listeners from thisObservable
void
copyListeners(Observable observable)
Copies all the listeners from thisObservable
to a specifiedObservable
.Set<Observable>
getChildren()
Returns children of thisObservable
Set<Observable>
getParents()
Returns parents of thisObservable
boolean
isValueChanged()
Returns whether thisObservable
was changed and it's listeners not yet calledvoid
notifyListeners()
Invokes the listeners of all descendant and ancestorObservables
that are currently marked as changed.protected void
onValueChanged()
Marks theObservable
and all its ancestors as changed.protected boolean
remove(Set<ListenerEntry> listenerSet, ChangeListener listener)
Utility method used internally that contains logic associated with removing alistener
from a specifiedset
protected boolean
removeChild(Observable observable)
Removes the specifiedObservable
from children of thisObservable
.boolean
removeListener(ChangeListener listener)
Removes the specified listener from the list of listeners.protected boolean
removeParent(Observable observable)
Removes the specifiedObservable
from parents of thisObservable
.protected void
removeSubObservable(Observable observable)
Removes the specifiedObservable
from the tree.void
setUnchanged(boolean traverseTree)
Resets the changed flag on this object and - if thetraverseTree
flag is set totrue
- all descendant and ancestorObservables
that are currently marked as changed.
-
-
-
Field Detail
-
notificationMethod
public transient ListenerNotification notificationMethod
Listeners notification method
-
-
Method Detail
-
addListener
public boolean addListener(ChangeListener listener)
Adds the specified listener to the list of listeners with the default priorityListenerPriority.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 addedpriority
- 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 addedpriority
- 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 specifiedObservable
to the tree as a child of thisObservable
. This method is recommended for creating theObservable
relations instead of plainaddParent(Observable)
andaddChild(Observable)
as it bindsObservables
both ways.- Parameters:
observable
- element to be inserted into the tree as a child of thisObservable
-
removeSubObservable
protected void removeSubObservable(Observable observable)
Removes the specifiedObservable
from the tree. This method is recommended for removingObservable
relations instead of plainremoveParent(Observable)
andremoveChild(Observable)
as it unbindsObservables
both ways.- Parameters:
observable
- element to be removed from the tree
-
onValueChanged
protected void onValueChanged()
Marks theObservable
and all its ancestors as changed. This method should be called inside a class extendingObservable
after a change was made.
-
notifyListeners
public void notifyListeners()
Invokes the listeners of all descendant and ancestorObservables
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 theObservables
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 thisObservable
to a specifiedObservable
.- Parameters:
observable
- element to copy the listeners to
-
clearListeners
public void clearListeners()
Removes all the listeners from thisObservable
-
setUnchanged
public void setUnchanged(boolean traverseTree)
Resets the changed flag on this object and - if thetraverseTree
flag is set totrue
- all descendant and ancestorObservables
that are currently marked as changed.- Parameters:
traverseTree
- whether to set all descendant and ancestor as unchanged
-
isValueChanged
public boolean isValueChanged()
Returns whether thisObservable
was changed and it's listeners not yet called- Returns:
true
if theObservable
was changed.false
if not
-
add
protected boolean add(Set<ListenerEntry> listenerSet, ChangeListener listener)
Utility method used internally that contains logic associated with adding alistener
to a specifiedset
- Parameters:
listenerSet
- set to operate ontolistener
- element to be added- Returns:
true
if the listener was successfully added.false
if it was already present
-
add
protected boolean add(Set<ListenerEntry> listenerSet, ChangeListener listener, ListenerPriority priority)
Utility method used internally that contains logic associated with adding alistener
to a specifiedset
- Parameters:
listenerSet
- set to operate ontolistener
- element to be addedpriority
- priority of this listener- Returns:
true
if the listener was successfully added.false
if it was already present
-
add
protected boolean add(Set<ListenerEntry> listenerSet, ChangeListener listener, int priority)
Utility method used internally that contains logic associated with adding alistener
to a specifiedset
- Parameters:
listenerSet
- set to operate ontolistener
- element to be addedpriority
- priority of this listener- Returns:
true
if the listener was successfully added.false
if it was already present
-
remove
protected boolean remove(Set<ListenerEntry> listenerSet, ChangeListener listener)
Utility method used internally that contains logic associated with removing alistener
from a specifiedset
- Parameters:
listenerSet
- set to operate ontolistener
- 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 specifiedObservable
as a parent of thisObservable
. Note: this creates only one way binding.addSubObservable(Observable)
method is recommended for setting upObservable
relations.- Parameters:
observable
- parent to be added- Returns:
true
if theObservable
was successfully added.false
if it was already present
-
removeParent
protected boolean removeParent(Observable observable)
Removes the specifiedObservable
from parents of thisObservable
. Note: this removed one way binding only.removeSubObservable(Observable)
method is recommended for removingObservable
relations.- Parameters:
observable
- parent to be removed- Returns:
true
if theObservable
was successfully removed.false
if it was not found
-
addChild
protected boolean addChild(Observable observable)
Sets the specifiedObservable
as a child of thisObservable
. Note: this creates only one way binding.addSubObservable(Observable)
method is recommended for setting upObservable
relations.- Parameters:
observable
- child to be added- Returns:
true
if theObservable
was successfully added.false
if it was already present
-
removeChild
protected boolean removeChild(Observable observable)
Removes the specifiedObservable
from children of thisObservable
. Note: this removed one way binding only.removeSubObservable(Observable)
method is recommended for removingObservable
relations.- Parameters:
observable
- child to be removed- Returns:
true
if theObservable
was successfully removed.false
if it was not found
-
getParents
public Set<Observable> getParents()
Returns parents of thisObservable
- Returns:
- a set containing all the parents of this object
-
getChildren
public Set<Observable> getChildren()
Returns children of thisObservable
- Returns:
- a set containing all the children of this object
-
-