ptolemy.moml

Class MoMLChangeRequest

java.lang.Object

ptolemy.kernel.util.ChangeRequest

ptolemy.moml.MoMLChangeRequest

Direct Known Subclasses:

OffsetMoMLChangeRequest

public class MoMLChangeRequest
extends ChangeRequest

A mutation request specified in MoML. This class provides the preferred mechanism for implementing mutations on a model while it is executing. To use it, create an instance of this class, specifying MoML code as an argument to the constructor. Then queue the instance of this class with a composite entity by calling its requestChange() method.

If a context is given to the constructor, then the MoML will be executed in that context. If that context has other objects that defer their MoML definitions to it (i.e., it is a class definition and there are instances of the class), then the MoML will also be executed in the context of those objects that defer to it. Thus, the change to a class will propagate to instances. If the context is (deeply) contained by another object that has objects that defer their MoML definitions to it, then the changes are also propagated to those objects. Thus, even when class definitions are nested within class definitions, a change within a class definition will propagate to all instances of the class(es).

The parser used to implement the change will be the parser contained by a ParserAttribute of the top-level element of the context. If no context is given, or there is no ParserAttribute in its top level, then a new parser is created, and a new ParserAttribute is placed in the top level.

Note that if a context is specified that is above a class definition, and a change within the class definition is made by referencing the contents of the class definition using dotted names, then the change will not propagate. Thus, changes should be made in the most specific context (lowest level in the hierarchy) possible.

Since:

Ptolemy II 1.0

Version:

$Id$

Author:

Edward A. Lee

Pt.AcceptedRating:

Red (neuendor)

Pt.ProposedRating:

Yellow (eal)

Constructor Summary

Constructors

Constructor and Description
MoMLChangeRequest(java.lang.Object originator, NamedObj context, java.lang.String request) Construct a mutation request to be executed in the specified context.
MoMLChangeRequest(java.lang.Object originator, NamedObj context, java.lang.String request, boolean structural) Construct a mutation request to be executed in the specified context.
MoMLChangeRequest(java.lang.Object originator, NamedObj context, java.lang.String request, java.net.URL base) Construct a mutation request to be executed in the specified context.
MoMLChangeRequest(java.lang.Object originator, java.lang.String request) Construct a mutation request.

Method Summary

Modifier and Type	Method and Description
protected void	_execute() Execute the change by evaluating the request and propagating the request if appropriate.
protected void	_postParse(MoMLParser parser) Do nothing.
protected void	_preParse(MoMLParser parser) Do nothing.
NamedObj	getContext() Return the context specified in the constructor, or null if none was specified.
static NamedObj	getDeferredToParent(NamedObj object) Deprecated. No longer needed; just use the specified object as a context.
void	setMergeWithPreviousUndo(boolean mergeWithPrevious) Set whether or not the undo from this change should be merged with the previous undoable change.
void	setReportErrorsToHandler(boolean report) Specify whether or not to report errors via the handler that is registered with the parser.
void	setUndoable(boolean undoable) Set whether or not this change is undoable.

Methods inherited from class ptolemy.kernel.util.ChangeRequest

addChangeListener, execute, getDescription, getLocality, getSource, isErrorReported, isPersistent, isStructuralChange, removeChangeListener, setDescription, setErrorReported, setListeners, setPersistent, waitForCompletion

Methods inherited from class java.lang.Object

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

Constructor Detail

MoMLChangeRequest

public MoMLChangeRequest(java.lang.Object originator,
                         java.lang.String request)

Construct a mutation request. The originator is the source of the change request. Since no context is given, a new parser will be used, and it will create a new top level. A listener to changes will probably want to check the originator so that when it is notified of errors or successful completion of changes, it can tell whether the change is one it requested. Alternatively, it can call waitForCompletion(). All external references are assumed to be absolute URLs. Whenever possible, use a different constructor that specifies the base.

Parameters:

originator - The originator of the change request.

request - The mutation request in MoML.

MoMLChangeRequest

public MoMLChangeRequest(java.lang.Object originator,
                         NamedObj context,
                         java.lang.String request)

Construct a mutation request to be executed in the specified context. The context is typically a Ptolemy II container, such as an entity, within which the objects specified by the MoML code will be placed. This method resets and uses a parser that is a static member of this class. A listener to changes will probably want to check the originator so that when it is notified of errors or successful completion of changes, it can tell whether the change is one it requested. Alternatively, it can call waitForCompletion(). All external references are assumed to be absolute URLs. Whenever possible, use a different constructor that specifies the base.

Parameters:

originator - The originator of the change request.

context - The context in which to execute the MoML.

request - The mutation request in MoML.

MoMLChangeRequest

public MoMLChangeRequest(java.lang.Object originator,
                         NamedObj context,
                         java.lang.String request,
                         java.net.URL base)

Construct a mutation request to be executed in the specified context. The context is typically a Ptolemy II container, such as an entity, within which the objects specified by the MoML code will be placed. If the top-level containing the specified context has a ParserAttribute, then the parser associated with that attribute is used. Otherwise, a new parser is created, and set to be the top-level parser. A listener to changes will probably want to check the originator so that when it is notified of errors or successful completion of changes, it can tell whether the change is one it requested. Alternatively, it can call waitForCompletion(), although there is severe risk of deadlock when doing that.

Parameters:

originator - The originator of the change request.

context - The context in which to execute the MoML.

request - The mutation request in MoML.

base - The URL relative to which external references should be resolved.

MoMLChangeRequest

public MoMLChangeRequest(java.lang.Object originator,
                         NamedObj context,
                         java.lang.String request,
                         boolean structural)

Construct a mutation request to be executed in the specified context. The context is typically a Ptolemy II container, such as an entity, within which the objects specified by the MoML code will be placed. This method resets and uses a parser that is a static member of this class. This constructor also accepts a boolean argument to tell whether the change is structural. Non-structural changes do not require repainting.

Parameters:

originator - The originator of the change request.

context - The context in which to execute the MoML.

request - The mutation request in MoML.

structural - Whether or not this is a structural change.

Method Detail

getContext

public NamedObj getContext()

Return the context specified in the constructor, or null if none was specified.

Returns:

The context.

getDeferredToParent

@Deprecated
public static NamedObj getDeferredToParent(NamedObj object)

Deprecated. No longer needed; just use the specified object as a context.

Return the first container, moving up the hierarchy, for which there are other objects that defer their MoML definitions to it. If there is no such container, then return null. If the specified object has other objects deferring to it, then return the specified object. NOTE: It used to be that the returned value of this method was the recommended context to specify to a constructor. This is no longer necessary. Propagation is automatically taken care of if the context is contained by a deferred-to parent. Thus, you should give the most immediate container that makes sense for the context. It is harmless, however, to use this method to get the context, so older code will work fine.

Parameters:

object - The NamedObj to which other objects defer their MoML definitions.

Returns:

An object that deeply contains this one, or null.

setUndoable

public void setUndoable(boolean undoable)

Set whether or not this change is undoable.

Parameters:

undoable - whether or not this change should be treated as an incremental change that is undoable

setMergeWithPreviousUndo

public void setMergeWithPreviousUndo(boolean mergeWithPrevious)

Set whether or not the undo from this change should be merged with the previous undoable change.

Parameters:

mergeWithPrevious - whether or not this change should be merged

setReportErrorsToHandler

public void setReportErrorsToHandler(boolean report)

Specify whether or not to report errors via the handler that is registered with the parser. The initial default is to not report errors to the registered handler. If this method is called with a true argument, errors will be reported to the registered handler. Note that in either case, if the handler returns ErrorHandler.CANCEL, then exceptions will be reported to any change listeners that are registered with this object via their changeFailed() method. If the handler returns ErrorHandler.CONTINUE, then the exception will not be reported to any change listeners and the change listener will think that the change succeeded.

Parameters:

report - False to disable error reporting.

See Also:

ErrorHandler

_execute

protected void _execute()
                 throws java.lang.Exception

Execute the change by evaluating the request and propagating the request if appropriate.

Specified by:

_execute in class ChangeRequest

Throws:

java.lang.Exception - If an exception is thrown while evaluating the request.

_postParse

protected void _postParse(MoMLParser parser)

Do nothing. This is a strategy pattern method that is called by the _execute() method just after doing the parse. Subclasses may override this.

Parameters:

parser - The parser

_preParse

protected void _preParse(MoMLParser parser)

Do nothing. This is a strategy pattern method that is called by the _execute() method just before doing the parse. Subclasses may override this to do some setup of the parser.

Parameters:

parser - The parser