ptolemy.actor.gt
Class GraphTransformer

java.lang.Object
  ptolemy.kernel.util.ChangeRequest
      ptolemy.actor.gt.GraphTransformer

public class GraphTransformer
extends ChangeRequest

Model transformation with a given match of the pattern. The transformation is implemented as a GraphTransformer.CreateObjectChangeRequest, so its execution can be deferred. When it is executed, it generates a bunch of MoMLChangeRequests and immediately executes those requests. Those requests adjusts the model with the given match of the pattern.

Since:

Ptolemy II 7.1

Version:

$Id: GraphTransformer.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Thomas Huining Feng

Accepted Rating:

Red (tfeng)

Proposed Rating:

Yellow (tfeng)

Nested Class Summary

private class	GraphTransformer.CreateObjectChangeRequest The change request to create objects in the host model and record those objects in the tables.
static class	GraphTransformer.ReplacementObjectAttribute A temporary attribute to record the corresponding object in the replacement for any object in the pattern.

Field Summary

private CompositeEntity	_host The top level of the host model.
private java.util.List<TransformationListener>	_listeners The list of listeners.
private MatchResult	_matchResult The current match result for the transformation.
private java.util.List<MatchResult>	_matchResults The list of match results to be used.
private static boolean	_mergeWithPrevious Whether the change requests are undoable and merged with previous change requests in an undo action.
private java.util.Map<NamedObj,java.lang.String>	_moml The MoML of the objects recorded from the host model.
private Pattern	_pattern The pattern of the transformation rule.
private TwoWayHashMap<NamedObj,NamedObj>	_patternToReplacement A table from the preserved objects in the pattern to the objects in the replacement.
private Replacement	_replacement The replacement of the transformation rule.
private TwoWayHashMap<NamedObj,NamedObj>	_replacementToHost A table from the objects in the replacement to the objects in the host model.
private static boolean	_undoable Whether the change requests are undoable.

Constructor Summary

GraphTransformer(TransformationRule transformationRule, java.util.List<MatchResult> matchResults)
Construct a transformer with the given transformation rule (including a pattern and a replacement), and a list of match results.

GraphTransformer(TransformationRule transformationRule, MatchResult matchResult)
Construct a transformer with the given transformation rule (including a pattern and a replacement), and a single match result.

Method Summary

protected void	_addConnections() Add new connections.
protected void	_addObjects() Add new NamedObjs.
private void	_addObjects(NamedObj replacement, NamedObj host, boolean copyAttributes) Add objects in a container in the replacement to a container in the host model.
private void	_addObjectsWithCreationAttributes(NamedObj pattern) Add objects with CreationAttributes from a container in the pattern to the container that that container matches in the host model.
private void	_addReplacementToHostEntries(NamedObj host) Add replacement-to-host entries in the table by traversing from a container in the host model to all its contained objects recursively.
private GraphTransformer.CreateObjectChangeRequest	_createAddObjectRequest(NamedObj context, java.lang.String moml) Create a change request to add an object in the context in the host model, and record the created object(s) in a private field of the change request itself.
private MoMLChangeRequest	_createChangeRequest(NamedObj context, java.lang.String moml) Create a change request to be executed in the context.
protected void	_execute() Execute the change request and perform the transformation on the match result(s) given to the constructor.
private Token	_getAttribute(NamedObj container, java.lang.String name, java.lang.Class<? extends Parameter> attributeClass) Get a GTAttribute in the given attribute class with the given name in the container.
private double[]	_getBestLocation(java.util.List<?> linkedObjectList) Return the best location (in X-Y coordinates) for a relation that is linked to the given list of objects.
private java.lang.String	_getLinkMoML(NamedObj object, Relation relation) Return the MoML to link the object to the relation.
private java.lang.String	_getMoML(NamedObj host) Get the MoML for an object in the host model.
private GraphTransformer.ReplacementObjectAttribute	_getReplacementObjectAttribute(NamedObj object) Get the ReplacementObjectAttribute associated with an object in the host model, if any.
protected void	_hideRelations() Hide all the relations in the host model that can be hidden, such as the ones that are visible but are not multi-way.
private void	_hideRelations(CompositeEntity host) Hide all the relations in a container in the host model that can be hidden, such as the ones that are visible but are not multi-way.
protected void	_init() Initialize model transformation and construct the maps between objects in the pattern, those in the replacement, and those in the host model.
private void	_initPatternToReplacement(NamedObj replacement) Initialize the table from objects in the pattern to the objects in the replacement.
private void	_initPreservedObjects(NamedObj pattern) For the objects in the pattern that are tagged to be preserved, mirror them to the replacement to preserve them.
private void	_initReplacementObjectAttributes(NamedObj replacement) Initialize the ReplacementObjectAttributes for all the objects in a container in the replacement, so that when those objects are copied into the host model, the new objects in the host model also have those ReplacementObjectAttributes.
private void	_initReplacementToHost() For the objects in the replacement, initialize table entries that map them to the host model if they are preserved from the pattern, and set the ReplacementObjectAttributes for them.
private boolean	_isAttributeCopied(Attribute attribute) Test whether the attribute should be copied.
protected void	_performOperations() Perform all the operations associated with the objects in the replacement.
private void	_recordMirroredObjects(NamedObj pattern, NamedObj host) Mirror the object tagged to be preserved in the pattern so that it is also considered to exist in the replacement.
protected void	_recordMoML() Record the MoML for the objects in the host model that are matched and need to be preserved in the result.
private boolean	_relink(Relation preserved, Relation removed) Remove the removed relation, and link all the ports that are originally linked to the removed relation with the preserved relation.
protected void	_removeLinks() Remove the links in the host model that are matched but need to be deleted.
private void	_removeLinks(CompositeEntity pattern) Remove the links in the host model that are matched but need to be deleted.
private java.util.Set<NamedObj>	_removeObject(NamedObj object, boolean shallowRemoval) Remove an object from the host model.
protected void	_removeObjects() Remove the NamedObjs in the host model that are matched but need to be deleted.
private void	_removeObjects(CompositeEntity host) Remove the NamedObjs in a container in the host model that are matched but need to be deleted.
private void	_removeReplacementObjectAttributes(NamedObj object) Remove the ReplacementObjectAttributes associated with the object and any of the objects contained in that object.
private void	_removeReplacementToHostEntries(NamedObj host) Remove the replacement-to-host entries in the table for the container in the host model, as well as all the objects contained in it.
private void	_replaceMatchResultEntries(NamedObj oldHost, NamedObj newHost) Replace the entries in the current match result from the old host object to the new host object.
protected void	_restoreParameterValues() Restore the values of the ValueIterators in the host model, so that they have the values that were used to obtain the match result.
private void	_setReplacementObjectAttribute(NamedObj object, java.lang.String replacementObjectCode) Set the ReplacementObjectAttribute for an object in the host model with the given code about the object type and object name.
protected void	_wrapup() Finish up transformation and remove the helper attributes in the replacement and the host model created in the transformation.
void	addTransformationListener(TransformationListener listener) Add a TransformationListener to listen to the transformation.
MatchResult	getMatchResult() Get the current match result used for the transformation.
Pattern	getPattern() Get the pattern of the transformation rule being used.
Replacement	getReplacement() Get the replacement of the transformation rule being used.
void	removeTransformationListener(TransformationListener listener) Remove a previously added TransformationListener.
static void	startUndoableTransformation(boolean mergeWithPrevious) Make all the transformers to execute undoable MoMLChangeRequests.
static void	stopUndoableTransformation() Stop executing undoable MoMLChangeRequests in all transformers, so that future requests cannot be undone.
static void	transform(TransformationRule transformationRule, java.util.List<MatchResult> matchResults) Transform a list of match results with a transformation rule.
static void	transform(TransformationRule transformationRule, java.util.List<MatchResult> matchResults, TransformationListener listener) Transform a list of match results with a transformation rule.
static void	transform(TransformationRule transformationRule, MatchResult matchResult) Transform a match result with a transformation rule.
static void	transform(TransformationRule transformationRule, MatchResult matchResult, TransformationListener listener) Transform a match result with a transformation rule.

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

Field Detail

_host

private CompositeEntity _host

The top level of the host model.

_listeners

private java.util.List<TransformationListener> _listeners

The list of listeners.

_matchResult

private MatchResult _matchResult

The current match result for the transformation.

_matchResults

private java.util.List<MatchResult> _matchResults

The list of match results to be used.

_mergeWithPrevious

private static boolean _mergeWithPrevious

Whether the change requests are undoable and merged with previous change requests in an undo action.

_moml

private java.util.Map<NamedObj,java.lang.String> _moml

The MoML of the objects recorded from the host model.

_pattern

private Pattern _pattern

The pattern of the transformation rule.

_patternToReplacement

private TwoWayHashMap<NamedObj,NamedObj> _patternToReplacement

A table from the preserved objects in the pattern to the objects in the replacement.

_replacement

private Replacement _replacement

The replacement of the transformation rule.

_replacementToHost

private TwoWayHashMap<NamedObj,NamedObj> _replacementToHost

A table from the objects in the replacement to the objects in the host model. Those objects are either preserved, or created as a result of the transformation.

_undoable

private static boolean _undoable

Whether the change requests are undoable.

Constructor Detail

GraphTransformer

public GraphTransformer(TransformationRule transformationRule,
                        java.util.List<MatchResult> matchResults)

Construct a transformer with the given transformation rule (including a pattern and a replacement), and a list of match results. The transformer tries to transform all matches, unless the previous ones violate the latter ones.

Parameters:

transformationRule - The transformation rule.

matchResults - The list of match results.

GraphTransformer

public GraphTransformer(TransformationRule transformationRule,
                        MatchResult matchResult)

Construct a transformer with the given transformation rule (including a pattern and a replacement), and a single match result. The transformer transforms the match.

Parameters:

transformationRule - The transformation rule.

matchResult - The match result.

Method Detail

addTransformationListener

public void addTransformationListener(TransformationListener listener)

Add a TransformationListener to listen to the transformation.

Parameters:

listener - The TransformationListener.

See Also:

removeTransformationListener(TransformationListener)

getMatchResult

public MatchResult getMatchResult()

Get the current match result used for the transformation.

Returns:

The current match result.

getPattern

public Pattern getPattern()

Get the pattern of the transformation rule being used.

Returns:

The pattern.

getReplacement

public Replacement getReplacement()

Get the replacement of the transformation rule being used.

Returns:

The replacement.

removeTransformationListener

public void removeTransformationListener(TransformationListener listener)

Remove a previously added TransformationListener. No effect if the TransformationListener is not added yet.

Parameters:

listener - The TransformationListener.

See Also:

addTransformationListener(TransformationListener)

startUndoableTransformation

public static void startUndoableTransformation(boolean mergeWithPrevious)

Make all the transformers to execute undoable MoMLChangeRequests.

Parameters:

mergeWithPrevious - Whether the undo entries should be merged with previous undo entries.

stopUndoableTransformation

public static void stopUndoableTransformation()

Stop executing undoable MoMLChangeRequests in all transformers, so that future requests cannot be undone.

transform

public static void transform(TransformationRule transformationRule,
                             java.util.List<MatchResult> matchResults)
                      throws TransformationException

Transform a list of match results with a transformation rule.

Parameters:

transformationRule - The transformation rule.

matchResults - The list of match results.

Throws:

TransformationException - If the pattern is not matched to any host model in the match results.

transform

public static void transform(TransformationRule transformationRule,
                             java.util.List<MatchResult> matchResults,
                             TransformationListener listener)
                      throws TransformationException

Transform a list of match results with a transformation rule.

Parameters:

transformationRule - The transformation rule.

matchResults - The list of match results.

listener - The TransformationListener to listen to the transformation.

Throws:

TransformationException - If the pattern is not matched to any host model in the match results.

transform

public static void transform(TransformationRule transformationRule,
                             MatchResult matchResult)
                      throws TransformationException

Transform a match result with a transformation rule.

Parameters:

transformationRule - The transformation rule.

matchResult - The match result.

Throws:

TransformationException - If the pattern is not matched to any host model in the match result.

transform

public static void transform(TransformationRule transformationRule,
                             MatchResult matchResult,
                             TransformationListener listener)
                      throws TransformationException

Transform a match result with a transformation rule.

Parameters:

transformationRule - The transformation rule.

matchResult - The match result.

listener - The TransformationListener to listen to the transformation.

Throws:

TransformationException - If the pattern is not matched to any host model in the match result.

_addConnections

protected void _addConnections()
                        throws TransformationException

Add new connections.

Throws:

TransformationException - If transformation is unsuccessful.

_addObjects

protected void _addObjects()
                    throws TransformationException

Add new NamedObjs.

Throws:

TransformationException - If transformation is unsuccessful.

_execute

protected void _execute()
                 throws TransformationException

Execute the change request and perform the transformation on the match result(s) given to the constructor.

Specified by:

_execute in class ChangeRequest

Throws:

TransformationException - If transformation is unsuccessful.

_hideRelations

protected void _hideRelations()

Hide all the relations in the host model that can be hidden, such as the ones that are visible but are not multi-way.

_init

protected void _init()
              throws TransformationException

Initialize model transformation and construct the maps between objects in the pattern, those in the replacement, and those in the host model.

Throws:

TransformationException - If transformation is unsuccessful.

_performOperations

protected void _performOperations()
                           throws TransformationException

Perform all the operations associated with the objects in the replacement.

Throws:

TransformationException - If transformation is unsuccessful.

_recordMoML

protected void _recordMoML()
                    throws TransformationException

Record the MoML for the objects in the host model that are matched and need to be preserved in the result.

Throws:

TransformationException - If transformation is unsuccessful.

_removeLinks

protected void _removeLinks()

Remove the links in the host model that are matched but need to be deleted.

_removeObjects

protected void _removeObjects()
                       throws TransformationException

Remove the NamedObjs in the host model that are matched but need to be deleted.

Throws:

TransformationException - If transformation is unsuccessful.

_restoreParameterValues

protected void _restoreParameterValues()
                                throws TransformationException

Restore the values of the ValueIterators in the host model, so that they have the values that were used to obtain the match result.

Throws:

TransformationException - If transformation is unsuccessful.

_wrapup

protected void _wrapup()
                throws TransformationException

Finish up transformation and remove the helper attributes in the replacement and the host model created in the transformation.

Throws:

TransformationException - If transformation is unsuccessful.

_addObjects

private void _addObjects(NamedObj replacement,
                         NamedObj host,
                         boolean copyAttributes)
                  throws TransformationException

Add objects in a container in the replacement to a container in the host model.

Parameters:

replacement - A container in the replacement.

host - A container in the host model.

copyAttributes - Whether attributes of the container in the replacement, if it is a CompositeEntity, should be copied to the container in the host model.

Throws:

TransformationException - If transformation is unsuccessful.

_addObjectsWithCreationAttributes

private void _addObjectsWithCreationAttributes(NamedObj pattern)
                                        throws TransformationException

Add objects with CreationAttributes from a container in the pattern to the container that that container matches in the host model.

Parameters:

pattern - A container in the pattern.

Throws:

TransformationException - If transformation is unsuccessful.

_addReplacementToHostEntries

private void _addReplacementToHostEntries(NamedObj host)

Add replacement-to-host entries in the table by traversing from a container in the host model to all its contained objects recursively. The given container in the host model should have been created from the replacement, and is not originally in the host model.

Parameters:

host - A container in the host model.

_createAddObjectRequest

private GraphTransformer.CreateObjectChangeRequest _createAddObjectRequest(NamedObj context,
                                                                           java.lang.String moml)

Create a change request to add an object in the context in the host model, and record the created object(s) in a private field of the change request itself.

Parameters:

context - The context.

moml - The MoML to be executed to add the object.

Returns:

The change request.

_createChangeRequest

private MoMLChangeRequest _createChangeRequest(NamedObj context,
                                               java.lang.String moml)

Create a change request to be executed in the context.

Parameters:

context - The context.

moml - The MoML to be executed.

Returns:

The change request.

_getAttribute

private Token _getAttribute(NamedObj container,
                            java.lang.String name,
                            java.lang.Class<? extends Parameter> attributeClass)

Get a GTAttribute in the given attribute class with the given name in the container. If it is not found in the container, and the container is in the host model with a corresponding container in the replacement, then the container in the replacement is searched. The container's container is also searched, until no such attribute is found, or the top level is reached.

Parameters:

container - The container to start the search with.

name - The name of the attribute to be searched for.

attributeClass - The class of the attribute to be searched for.

Returns:

The attribute, if found, or null otherwise.

_getBestLocation

private double[] _getBestLocation(java.util.List<?> linkedObjectList)

Return the best location (in X-Y coordinates) for a relation that is linked to the given list of objects.

Parameters:

linkedObjectList - The list of objects that a relation is linked to.

Returns:

The X-Y coordinates of the chosen location.

_getLinkMoML

private java.lang.String _getLinkMoML(NamedObj object,
                                      Relation relation)

Return the MoML to link the object to the relation. The object may be a port or a relation.

Parameters:

object - The object.

relation - The relation.

Returns:

The MoML whose execution leads to the object and the relation being linked.

_getMoML

private java.lang.String _getMoML(NamedObj host)

Get the MoML for an object in the host model.

Parameters:

host - An object in the host model.

Returns:

The MoML for the object.

_getReplacementObjectAttribute

private GraphTransformer.ReplacementObjectAttribute _getReplacementObjectAttribute(NamedObj object)

Get the ReplacementObjectAttribute associated with an object in the host model, if any.

Parameters:

object - The object.

Returns:

The ReplacementObjectAttribute, or null if not found.

_hideRelations

private void _hideRelations(CompositeEntity host)

Hide all the relations in a container in the host model that can be hidden, such as the ones that are visible but are not multi-way.

Parameters:

host - A container in the host model.

_initPatternToReplacement

private void _initPatternToReplacement(NamedObj replacement)

Initialize the table from objects in the pattern to the objects in the replacement.

Parameters:

replacement - The replacement.

_initPreservedObjects

private void _initPreservedObjects(NamedObj pattern)

For the objects in the pattern that are tagged to be preserved, mirror them to the replacement to preserve them.

Parameters:

pattern - The pattern.

_initReplacementObjectAttributes

private void _initReplacementObjectAttributes(NamedObj replacement)
                                       throws TransformationException

Initialize the ReplacementObjectAttributes for all the objects in a container in the replacement, so that when those objects are copied into the host model, the new objects in the host model also have those ReplacementObjectAttributes.

Parameters:

replacement - A container in the replacement.

Throws:

TransformationException - If attributes cannot be created.

_initReplacementToHost

private void _initReplacementToHost()
                             throws TransformationException

For the objects in the replacement, initialize table entries that map them to the host model if they are preserved from the pattern, and set the ReplacementObjectAttributes for them.

Throws:

TransformationException - If attributes cannot be created.

_isAttributeCopied

private boolean _isAttributeCopied(Attribute attribute)

Test whether the attribute should be copied. Attributes that have special meaning in the transformation, such as criteria and operations, should not be copied into the host model, whereas other attributes should if they or their containers are copied.

Parameters:

attribute - The attribute to test.

Returns:

true if the attribute should be copied; false otherwise.

_recordMirroredObjects

private void _recordMirroredObjects(NamedObj pattern,
                                    NamedObj host)

Mirror the object tagged to be preserved in the pattern so that it is also considered to exist in the replacement.

Parameters:

pattern - An object in the pattern.

host - An object in the host model corresponding to the object in the pattern.

_relink

private boolean _relink(Relation preserved,
                        Relation removed)

Remove the removed relation, and link all the ports that are originally linked to the removed relation with the preserved relation. If any port originally linked to the removed relation is linked to more than one relations (including the removed relation), then false is returned and no change is made.

Parameters:

preserved - The preserved relation.

removed - The removed relation.

Returns:

true if the relinking can be done; otherwise, false and no change is made.

_removeLinks

private void _removeLinks(CompositeEntity pattern)

Remove the links in the host model that are matched but need to be deleted.

Parameters:

pattern - A container in the pattern that contains the links to be removed.

_removeObject

private java.util.Set<NamedObj> _removeObject(NamedObj object,
                                              boolean shallowRemoval)
                                       throws TransformationException

Remove an object from the host model.

Parameters:

object - The object in the host model to be removed.

shallowRemoval - Whether the removal is shallow. If it is and the object to be removed is a CompositeEntity, then the entities and the connections between them in the CompositeEntity are moved to the upper level.

Returns:

The objects that are moved to the upper level, or null if the removal is not shallow.

Throws:

TransformationException - If transformation is unsuccessful.

_removeObjects

private void _removeObjects(CompositeEntity host)
                     throws TransformationException

Remove the NamedObjs in a container in the host model that are matched but need to be deleted.

Parameters:

host - A container in the host model.

Throws:

TransformationException - If transformation is unsuccessful.

_removeReplacementObjectAttributes

private void _removeReplacementObjectAttributes(NamedObj object)

Remove the ReplacementObjectAttributes associated with the object and any of the objects contained in that object.

Parameters:

object - The object whose ReplacementObjectAttributes need to be removed.

_removeReplacementToHostEntries

private void _removeReplacementToHostEntries(NamedObj host)

Remove the replacement-to-host entries in the table for the container in the host model, as well as all the objects contained in it.

Parameters:

host - A container in the host model.

_replaceMatchResultEntries

private void _replaceMatchResultEntries(NamedObj oldHost,
                                        NamedObj newHost)

Replace the entries in the current match result from the old host object to the new host object. Also replace the objects contained in them.

Parameters:

oldHost - The old host object.

newHost - The new host object.

_setReplacementObjectAttribute

private void _setReplacementObjectAttribute(NamedObj object,
                                            java.lang.String replacementObjectCode)
                                     throws TransformationException

Set the ReplacementObjectAttribute for an object in the host model with the given code about the object type and object name.

Parameters:

object - An object in the host model.

replacementObjectCode - The code to be set in the ReplacementObjectAttribute.

Throws:

TransformationException - If the attribute cannot be created.