Module stasgora.observetree

Package dev.sgora.observetree

Class Observable

java.lang.Object

dev.sgora.observetree.Observable

Direct Known Subclasses:

SettableProperty

public abstract class Observable
extends Object

Base Observable class that holds a list of listeners and notifies them when it changes. Use one of the addListener(ChangeListener) methods to register a listener.

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

Use notificationMethod flag to configure whether notifyListeners() 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 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

Field Summary

Fields

Modifier and Type	Field	Description
protected 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 a listener to a specified set
protected boolean	add(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(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.
Set<Observable>	getChildren()	Returns children of this Observable
ListenerNotification	getNotificationMethod()	Returns notification method of this Observable
Set<Observable>	getParents()	Returns parents of this Observable
boolean	isValueChanged()	Returns whether this Observable was changed and it's listeners not yet called
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(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	setNotificationMethod(ListenerNotification notificationMethod)	Sets notification method of this Observable
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

protected 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

isValueChanged

public boolean isValueChanged()

Returns whether this Observable was changed and it's listeners not yet called

Returns:

true if the Observable was changed. false if not

add

protected boolean add(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(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(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(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 Set<Observable> getParents()

Returns parents of this Observable

Returns:

a set containing all the parents of this object

getChildren

public Set<Observable> getChildren()

Returns children of this Observable

Returns:

a set containing all the children of this object

getNotificationMethod

public ListenerNotification getNotificationMethod()

Returns notification method of this Observable

Returns:

a way in which this Observable listeners are notified

setNotificationMethod

public void setNotificationMethod(ListenerNotification notificationMethod)

Sets notification method of this Observable

Parameters:

notificationMethod - a way in which this Observable listeners are to be notified