ptolemy.kernel.util

Class ChangeRequest

java.lang.Object

ptolemy.kernel.util.ChangeRequest

Direct Known Subclasses:

ApplyLayoutRequest, GraphTransformer, GTFrameTools.ModelChangeRequest, MoMLChangeRequest, PtolemyFrame.PrintChangeRequest, RedoChangeRequest, UndoChangeRequest

public abstract class ChangeRequest
extends java.lang.Object

Abstract base class for change requests. 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 typical use of this class is to define an anonymous inner class that implements the _execute() method to bring about the desired change. The instance of that anonymous inner class is then queued with an instance of NamedObj using its requestChange() method. The execute() method must be called only once; attempting to call it multiple times will trigger an exception.

Concrete derived classes can be defined to implement mutations of a certain kind or in a certain way. Instances of these classes should be queued with a NamedObj, just like an anonymous inner class extending this class. MoMLChangeRequest is such a concrete derived class, where the mutation is specified as MoML code.

Since:

Ptolemy II 1.0

Version:

$Id: ChangeRequest.java 65768 2013-03-07 03:33:00Z cxh $

Author:

Edward A. Lee, Contributor: Bert Rodiers

See Also:

ChangeListener

Accepted Rating:

Green (neuendor)

Proposed Rating:

Green (eal)

Constructor Summary

Constructors

Constructor and Description
ChangeRequest(java.lang.Object source, java.lang.String description) Construct a request with the specified source and description.
ChangeRequest(java.lang.Object source, java.lang.String description, boolean isStructuralChange) Construct a request with the specified source and description.

Method Summary

Modifier and Type	Method and Description
protected abstract void	_execute() Execute the change.
void	addChangeListener(ChangeListener listener) Add a new change listener to this request.
void	execute() Execute the change.
java.lang.String	getDescription() Get the description that was specified in the constructor.
NamedObj	getLocality() If a change is localized to a particular object and objects that it contains, then that object should be returned by this method.
java.lang.Object	getSource() Get the source that was specified in the constructor.
boolean	isErrorReported() Return true if setErrorReported() has been called with a true argument.
boolean	isPersistent() Return false if the change represented by this request has been asserted to be non-persistent by calling setPersistent(false), and return true otherwise.
boolean	isStructuralChange() Return whether this change request is a structural change request.
void	removeChangeListener(ChangeListener listener) Remove the given change listener from this request.
void	setDescription(java.lang.String description) Set the description.
void	setErrorReported(boolean reported) Call with a true argument to indicate that an error has been reported to the user.
void	setListeners(java.util.List listeners) Specify a list of listeners to be notified when changes are successfully executed, or when an attempt to execute them results in an exception.
void	setPersistent(boolean persistent) Assert whether the change represented by this request is persistent.
void	waitForCompletion() Wait for execution (or failure) of this change request.

Methods inherited from class java.lang.Object

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

Constructor Detail

ChangeRequest

public ChangeRequest(java.lang.Object source,
                     java.lang.String description)

Construct a request with the specified source and description. The description is a string that is used to report the change, typically to the user in a debugging environment. The source is the object that requested this change request. A listener to changes will probably want to check the source so that when it is notified of errors or successful completion of changes, it can tell whether the change is one it requested. This constructor is here for backwards compatibility. The constructor ChangeRequest(Object source, String description, boolean isStructuralChange) has an extra parameter that allows you to specify whether this change is a structural change. If it isn't one, no complete repaints will be done of the visual model. By using this constructor the repaints will be done if there are AbstractBasicGraphModel listeners listening to this ChangeRequest.

Parameters:

source - The source of the change request.

description - A description of the change request.

See Also:

ChangeRequest(Object, String, boolean)

ChangeRequest

public ChangeRequest(java.lang.Object source,
                     java.lang.String description,
                     boolean isStructuralChange)

Construct a request with the specified source and description. The description is a string that is used to report the change, typically to the user in a debugging environment. The source is the object that requested this change request. A listener to changes will probably want to check the source so that when it is notified of errors or successful completion of changes, it can tell whether the change is one it requested. This constructor is here for backwards compatibility. isStructuralChange specifies whether the change is structural or not. If it isn't a structural change (isStructuralChange equal to false), no complete repaints will be done of the visual model. If isStructuralChange equals true, repaints will be done if there are AbstractBasicGraphModel listeners listening to this ChangeRequest.

Parameters:

source - The source of the change request.

description - A description of the change request.

isStructuralChange - Specifies whether this change is a structural one.

Method Detail

addChangeListener

public void addChangeListener(ChangeListener listener)

Add a new change listener to this request. The listener will get notified when the change is executed, or the change fails. This listener is notified first, and then any listeners that were given by setListeners. This listener is also notified before other listeners that have been previously registered with this object.

Parameters:

listener - The listener to add.

See Also:

removeChangeListener(ChangeListener)

execute

public final void execute()

Execute the change. This method invokes the protected method _execute(), takes care of reporting execution to any listeners and then wakes up any threads that might be waiting in a call to waitForCompletion(). Listeners that are attached directly to this object (using the addChangeListener() and removeChangeListener() methods) are notified first of the status of the request, followed by global listeners that were set using the setListeners() method. If the change failed because an exception was thrown, and the exception was not reported to any global listeners, then we throw an InternalErrorException because it is a bug to not have a listener in this case.

This method should be called exactly once, by the object that the change request was queued with. Attempting to call this method more than once will throw an exception.

getDescription

public java.lang.String getDescription()

Get the description that was specified in the constructor.

Returns:

The description of the change.

See Also:

setDescription(String)

getLocality

public NamedObj getLocality()

If a change is localized to a particular object and objects that it contains, then that object should be returned by this method. In this base class, this method returns null to indicate that the change is not localized (or at least, is not known to be localized). Derived classes that make changes that they know to be local should return non-null.

Returns:

Null to indicate that the change is not localized.

getSource

public java.lang.Object getSource()

Get the source that was specified in the constructor.

Returns:

The source of the change.

isErrorReported

public boolean isErrorReported()

Return true if setErrorReported() has been called with a true argument. This is used by listeners to avoid reporting an error repeatedly. By convention, a listener that reports the error to the user, in a dialog box for example, should call this method to determine whether the error has already been reported. If it reports the error, then it should call setErrorReported() with a true argument.

Returns:

True if an error has already been reported.

isPersistent

public boolean isPersistent()

Return false if the change represented by this request has been asserted to be non-persistent by calling setPersistent(false), and return true otherwise. That is, return false if the change has been asserted to not affect the MoML representation of the model. This might be used, for example, by a user interface, to determine whether to mark the model "modified," and hence, whether to prompt the user to save the model if a window is closed.

This method returns true unless setPersistent() has been called with an argument false. It is up to the creator of the change request to call that method to ensure that the change is not persistent. There is no automatic detection of whether the change is persistent.

Returns:

True if the change represented by this request is persistent.

See Also:

setPersistent(boolean)

isStructuralChange

public boolean isStructuralChange()

Return whether this change request is a structural change request. This is used to determine whether a complete repaint of the model is necessary.

Returns:

True this change request is a structural one.

removeChangeListener

public void removeChangeListener(ChangeListener listener)

Remove the given change listener from this request. The listener will no longer be notified when the change is executed, or the change fails.

Parameters:

listener - The listener to be removed.

See Also:

addChangeListener(ChangeListener)

setDescription

public void setDescription(java.lang.String description)

Set the description.

Parameters:

description - The description.

Since:

Ptolemy II 3.1

See Also:

getDescription()

setErrorReported

public void setErrorReported(boolean reported)

Call with a true argument to indicate that an error has been reported to the user. This is used by listeners to avoid reporting an error repeatedly. By convention, a listener that reports the error to the user, in a dialog box for example, should call this method after reporting an error. It should call isErrorReported() to determine whether it is necessary to report the error.

Parameters:

reported - True if an error has been reported.

setListeners

public void setListeners(java.util.List listeners)

Specify a list of listeners to be notified when changes are successfully executed, or when an attempt to execute them results in an exception. The next time that execute() is called, all listeners on the specified list will be notified. This class has this method, in addition to the usual addChangeListener() and removeChangeListener() because it is assumed that the primary list of listeners is being maintained in another class, specifically the top-level named object in the hierarchy. The listeners set with this method are notified after the listeners that are attached directly to this object.

The class copies the given list, so that in the process of handling notifications from this class, more listeners can be added to the list of listeners in the top-level object.

Note that an alternative to using listeners is to call waitForCompletion(), although this may cause undesirable synchronization between the different threads.

Parameters:

listeners - A list of instances of ChangeListener or instances of WeakReference referring to instances of ChangeListener.

See Also:

ChangeListener, NamedObj

setPersistent

public void setPersistent(boolean persistent)

Assert whether the change represented by this request is persistent. Call this method with argument false to assert that the change does not affect the MoML representation of the model. This might, for example, guide a user interface, to determine whether to mark the model "modified," and hence, whether to prompt the user to save the model if a window is closed.

It is up to the creator of the change request to call this method to assure that the change is not persistent. Calling this method with a false argument does not make the change non-persistent. It merely asserts that it is. There is no automatic detection of whether the change is persistent. By default, the change is assumed to be persistent, so unless this is called with argument false, a UI will likely mark the model modified upon execution of the change request.

Parameters:

persistent - False to indicate that the change represented by this request is not persistent.

See Also:

isPersistent()

waitForCompletion

public final void waitForCompletion()
                             throws java.lang.Exception

Wait for execution (or failure) of this change request. The calling thread is suspended until the execute() method completes. If an exception occurs processing the request, then this method will throw that exception.

Note that using this method may cause the model to deadlock and not be able to proceed. This is especially true if it is called from the Swing thread, and any actors in the model (such as plotters) wait for swing events.

Throws:

java.lang.Exception - If the execution of the change request throws it.

_execute

protected abstract void _execute()
                          throws java.lang.Exception

Execute the change. Derived classes must implement this method. Any exception may be thrown if the change fails.

Throws:

java.lang.Exception - If the change fails.