mapss.dif.util
Interface Changeable

All Known Implementing Classes:

Attribute, NamedObj, mapss.dif.data.expr.ScopeExtendingAttribute, UnitCategory, UnitSystem

public interface Changeable

This is an interface for objects that support change requests that can be deferred. A change request is any modification to a model that might be performed during execution of the model, but where there might only be certain phases of execution during which it is safe to make the modification. Such changes are also called mutations.

A change request is typically made by instantiating a subclass of ChangeRequest (possibly using an anonymous inner class) and then passing it to the requestChange() method of an object implementing this interface. That object may delegate the request (for example, it might consolidate all such requests at the top level of the hierarchy by passing the request to its container). If it does delegate, then it is expected to consistently delegate all commands to the same object.

When a change request is made, if it is safe to do so, then an implementor of this interface is free to immediately execute the request, unless setDeferringChangeRequests(true) has been called. It is never safe to execute a change request if the implementor is already in the middle of executing a change request (that execution may have triggered the request).

Since:

Ptolemy II 4.0

Version:

$Id: Changeable.java,v 1.13 2005/07/08 19:59:15 cxh Exp $

Author:

Edward A. Lee

See Also:

ChangeRequest

Method Summary

void	addChangeListener(ChangeListener listener) Add a change listener.
void	executeChangeRequests() Execute requested changes.
boolean	isDeferringChangeRequests() Return true if setDeferringChangeRequests(true) has been called to specify that change requests should be deferred.
void	removeChangeListener(ChangeListener listener) Remove a change listener, if it is present, and otherwise do nothing.
void	requestChange(ChangeRequest change) Request that the given change be executed.
boolean	setDeferringChangeRequests(boolean isDeferring) Specify whether change requests made by calls to requestChange() should be executed immediately.

Method Detail

addChangeListener

void addChangeListener(ChangeListener listener)

Add a change listener. Each listener will be notified of the execution (or failure) of each change request that is executed via the requestChange() method. Implementors are free to delegate both the request and the listener to other objects (e.g. the container), so the listener may be notified of more changes than those requested through the requestChange() method of this object. Implementors are required to not add a listener that is already on the list of listeners (i.e., objects should not appear more than once on the list).

Parameters:

listener - The listener to add.

See Also:

removeChangeListener(ChangeListener), requestChange(ChangeRequest)

executeChangeRequests

void executeChangeRequests()

Execute requested changes. An implementor is free to delegate this to another implementor of Changeable. An implementor is expected to execute all pending change requests (even if setDeferringChangeRequests() has been called with a true argument). Listeners will be notified of success or failure.

See Also:

addChangeListener(ChangeListener), requestChange(ChangeRequest), setDeferringChangeRequests(boolean)

isDeferringChangeRequests

boolean isDeferringChangeRequests()

Return true if setDeferringChangeRequests(true) has been called to specify that change requests should be deferred.

Returns:

True if change requests are being deferred.

See Also:

setDeferringChangeRequests(boolean)

removeChangeListener

void removeChangeListener(ChangeListener listener)

Remove a change listener, if it is present, and otherwise do nothing.

Parameters:

listener - The listener to remove.

See Also:

addChangeListener(ChangeListener)

requestChange

void requestChange(ChangeRequest change)

Request that the given change be executed. An implementor is free to delegate this request to another object (e.g. the container). It may also execute the request immediately, unless this object is deferring change requests. If setDeferChangeRequests() has been called with a true argument, then an implementor is expected to queue the request until either setDeferChangeRequests() is called with a false argument or executeChangeRequests() is called. If an implementor is already in the middle of executing a change request, then the implementor is expected to finish that execution before executing this one. Change listeners will be notified of success (or failure) of the request when it is executed.

Parameters:

change - The requested change.

See Also:

executeChangeRequests(), setDeferringChangeRequests(boolean)

setDeferringChangeRequests

boolean setDeferringChangeRequests(boolean isDeferring)

Specify whether change requests made by calls to requestChange() should be executed immediately. An implementor is free to delegate this to another object implementing Changeable (e.g. the container). If the argument is true, then an implementor is expected to queue requests until either this method is called again with argument false, or until executeChangeRequests() is called. If the argument is false, then execute any pending change requests and set a flag requesting that future requests be executed immediately.

Parameters:

isDeferring - If true, defer change requests.

Returns:

True if this object was previously deferring change requests.

See Also:

addChangeListener(ChangeListener), executeChangeRequests(), isDeferringChangeRequests(), requestChange(ChangeRequest)