ptolemy.vergil.basic.layout.kieler
Class PtolemyModelUtil

java.lang.Object
  ptolemy.vergil.basic.layout.kieler.PtolemyModelUtil

public class PtolemyModelUtil
extends java.lang.Object

Class containing methods for manipulating Ptolemy models for the purpose of layout a graphical Ptolemy diagram. Methods for positioning Actors and creating vertices are available. The changes are performed by MoMLChangeRequests where as long as possible those requests get buffered in order to perform multiple changes at once for performance.

Since:

Ptolemy II 8.0

Version:

$Id: PtolemyModelUtil.java 59203 2010-09-23 21:41:27Z cxh $

Author:

Hauke Fuhrmann,

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (cxh)

Field Summary

private boolean	_anyRequestsSoFar Flag indicating whether there have been any MoMLChangeRequests processed so far or not.
private static boolean	_hide Toggle variable to set the hidden status of unnecessary relation vertices.
private java.lang.StringBuffer	_momlChangeRequest StringBuffer for Requests of Model changes.
private java.util.Set<java.lang.String>	_nameSet Local cache of used names.
private static int	_uniqueCounter A unique number that is used to determine unique String names for relations.

Constructor Summary

PtolemyModelUtil()
Construct an instance and initialize the internal request buffer.

Method Summary

protected java.lang.String	_createRelation(java.lang.String relationName) Create a new MoMLChangeRequest to add a new Relation.
protected java.lang.String	_createRelationWithVertex(java.lang.String relationName, double x, double y) Create a new MoMLChangeRequest to add a new Relation with a Vertex at a given position.
protected static double[]	_getLocation(NamedObj namedObj) Get the location given by the location attribute of the given input object.
protected static java.util.Set<java.util.List<Relation>>	_getRelationGroups(java.util.Set<Relation> relations) For a set of relations get a set of relation groups, i.e. for each relation construct a list of relations that are all interconnected, either directly or indirectly.
protected int	_getUniqueNumber() Get a unique number.
protected java.lang.String	_getUniqueString(CompositeActor actor, java.lang.String prefix) Get a unique String in the namespace of the given composite actor with the prefix that is also given.
protected void	_hideVertex(java.lang.String relationName, java.lang.String vertexName, boolean hide) Hide a specific relation vertex.
protected static boolean	_isConnected(NamedObj namedObj) Check whether the given Ptolemy model object has any connections, i.e. is connected to any other components via some link.
protected static boolean	_isInput(Port port) Determine whether a given Port is an input port.
protected void	_link(java.lang.String type1, java.lang.String name1, java.lang.String type2, java.lang.String name2) Create a new MoMLChangeRequest to add a new link between arbitrary objects.
protected void	_linkPort(java.lang.String portName, java.lang.String type2, java.lang.String name2, int index) Link a port with something else (port or relation) at a specific index.
protected void	_linkPortInside(java.lang.String portName, java.lang.String type2, java.lang.String name2, int insideIndex) Link a port with something else (port or relation) at a specific inside index.
protected void	_performChangeRequest(CompositeActor actor) Flush all buffered change requests to the given Actor.
protected void	_removeRelation(Relation relation, CompositeActor actor) Remove a single relation.
protected void	_removeRelations(java.util.Set<Relation> relationSet) Create a MoMLChangeRequest to remove a set of relations in a Ptolemy model object.
protected void	_removeRelationVertex(Relation relation) Remove a vertex from a relation.
static void	_removeUnnecessaryRelations(CompositeActor parent) Remove all unnecessary relations within a composite actor.
protected void	_setLocation(NamedObj obj, double x, double y) Create a MoMLChangeRequest to move a Ptolemy model object and schedule it immediately.
protected void	_setLocation(Vertex vertex, Relation relation, double x, double y) Create a MoMLChangeRequest to move a Ptolemy model object and schedule it immediately.
protected static void	_showUnnecessaryRelations(CompositeActor parent, boolean show) Show or hide unnecessary relation vertices.
static void	_showUnnecessaryRelationsToggle(CompositeActor parent) Toggle show or hide status of unnecessary relation vertices.
protected static java.lang.String	_stripNumericSuffix(java.lang.String string) Return a string that is identical to the specified string except any trailing digits are removed.
protected void	_unlinkPort(java.lang.String portName, int index) Unlink a port at the given channel index.
protected void	_unlinkPortInside(java.lang.String portName, int insideIndex) Unlink a port at the given channel inside index.
protected void	_unlinkRelations(java.lang.String relation1, java.lang.String relation2) Unlink two relations.

Methods inherited from class java.lang.Object

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

Field Detail

_anyRequestsSoFar

private boolean _anyRequestsSoFar

Flag indicating whether there have been any MoMLChangeRequests processed so far or not. This is required for proper undo, because if there were some requests we also want to merge our undo to them.

_momlChangeRequest

private java.lang.StringBuffer _momlChangeRequest

StringBuffer for Requests of Model changes. In Ptolemy the main infrastructure to do model changes is through XML change requests of the XML representation. This field is used to collect all changes in one String and then carry them out in only one operation whereas possible.

_hide

private static boolean _hide

Toggle variable to set the hidden status of unnecessary relation vertices.

_nameSet

private java.util.Set<java.lang.String> _nameSet

Local cache of used names.

_uniqueCounter

private static int _uniqueCounter

A unique number that is used to determine unique String names for relations.

Constructor Detail

PtolemyModelUtil

public PtolemyModelUtil()

Construct an instance and initialize the internal request buffer.

Method Detail

_createRelation

protected java.lang.String _createRelation(java.lang.String relationName)

Create a new MoMLChangeRequest to add a new Relation. The MoML code is appended to the field MoMLChangeRequest buffer to buffer multiple such requests. Don't actually execute the request. To flush the request, the method _performChangeRequest(CompositeActor) must be called.

Parameters:

relationName - Name of the new relation which needs to be unique

Returns:

name of newly created relation

_createRelationWithVertex

protected java.lang.String _createRelationWithVertex(java.lang.String relationName,
                                                     double x,
                                                     double y)

Create a new MoMLChangeRequest to add a new Relation with a Vertex at a given position. The MoML code is appended to the field MoMLChangeRequest buffer to buffer multiple such requests. Don't actually execute the request. To flush the request, the method _performChangeRequest(CompositeActor) must be called.

Parameters:

relationName - Name of the new relation which needs to be unique

x - coordinate of new vertex

y - coordinate of new vertex

Returns:

name of newly created relation

_hideVertex

protected void _hideVertex(java.lang.String relationName,
                           java.lang.String vertexName,
                           boolean hide)

Hide a specific relation vertex. Set or unset the _hide attribute of a relation vertex.

Parameters:

relationName - Name of the relation that contains the vertex.

vertexName - Name of the vertex.

hide - True iff the hide attribute should be set. Otherwise if it should be unset.

_link

protected void _link(java.lang.String type1,
                     java.lang.String name1,
                     java.lang.String type2,
                     java.lang.String name2)

Create a new MoMLChangeRequest to add a new link between arbitrary objects. The MoML code is appended to the field MoMLChangeRequest buffer to buffer multiple such requests. Don't actually execute the request. Supported types are given by MoML, e.g. "port", "relation". Connecting multiple relations requires to add a number, "relation1", "relation2" to the corresponding type. To flush the request, the method _performChangeRequest(CompositeActor) must be called.

Parameters:

type1 - type of the first item to be linked, e.g. port, relation, relation1, relation2

name1 - name of the first item to be linked

type2 - type of the second item to be linked, e.g. port, relation, relation1, relation2

name2 - name of the second item to be linked

_linkPort

protected void _linkPort(java.lang.String portName,
                         java.lang.String type2,
                         java.lang.String name2,
                         int index)

Link a port with something else (port or relation) at a specific index.

Parameters:

portName - Name of the port to be linked.

type2 - Type of the second object, i.e. port or relation.

name2 - Name of the second object to be linked.

index - Index of the relation in the channel list of the first port.

_linkPortInside

protected void _linkPortInside(java.lang.String portName,
                               java.lang.String type2,
                               java.lang.String name2,
                               int insideIndex)

Link a port with something else (port or relation) at a specific inside index.

Parameters:

portName - Name of the port to be linked.

type2 - Type of the second object, i.e. port or relation.

name2 - Name of the second object to be linked.

insideIndex - Index of the relation in the channel list of the first port.

_removeRelation

protected void _removeRelation(Relation relation,
                               CompositeActor actor)

Remove a single relation.

Parameters:

relation - Relation to be removed.

actor - Parent actor of the relation.

_removeRelations

protected void _removeRelations(java.util.Set<Relation> relationSet)

Create a MoMLChangeRequest to remove a set of relations in a Ptolemy model object.

Parameters:

relationSet - Set of relation to be removed from the Ptolemy model

_removeUnnecessaryRelations

public static void _removeUnnecessaryRelations(CompositeActor parent)

Remove all unnecessary relations within a composite actor. Unnecessary means that a relation is connected only with 0, 1 or 2 objects. In such case a relation can be either simply removed or replaced by a direct link between the objects. Iterate all relations in the parent actor and for all unnecessary relations with vertices, remove them and if required reestablish the links such that the semantics keeps the same.

Parameters:

parent - The composite actor in which to look for unnecessary relations.

_removeRelationVertex

protected void _removeRelationVertex(Relation relation)

Remove a vertex from a relation.

Parameters:

relation - The relation to remove the vertex from.

_getLocation

protected static double[] _getLocation(NamedObj namedObj)

Get the location given by the location attribute of the given input object. If the Ptolemy object has no location attribute, return double zero.

Parameters:

namedObj - The Ptolemy object for which the location should be retrieved.

Returns:

A double array containing two double values corresponding to the location (x and y) of the object. Will return double zero if no location attribute is set for the object.

_getRelationGroups

protected static java.util.Set<java.util.List<Relation>> _getRelationGroups(java.util.Set<Relation> relations)

For a set of relations get a set of relation groups, i.e. for each relation construct a list of relations that are all interconnected, either directly or indirectly.

Parameters:

relations - Set of relations

Returns:

a Set of relation groups as given by List objects by Ptolemy

_getUniqueNumber

protected int _getUniqueNumber()

Get a unique number. Subsequent calls to this method will return an increasing sequence of numbers. This can be used to suffix a NamedObj where the official getUniqueName() methods of the parent composite actors cannot be used (e.g. if to create multiple new objects in just one MoMLChangeRequest.

Returns:

An integer where every following call will give a different one.

_getUniqueString

protected java.lang.String _getUniqueString(CompositeActor actor,
                                            java.lang.String prefix)

Get a unique String in the namespace of the given composite actor with the prefix that is also given. The idea is the same than the CompositeEntity.uniqueName(String) method of any CompositeEntity. However, build a local cache of used names and add the names that get created by subsequent calls. I.e. multiple subsequent calls won't return the same name even when the name of a former call is not used yet in the composite actor.

The rationale is that for MoMLChangeRequests it is desireable to collect multiple changes (e.g. multiple object creations that all require a unique name).

Parameters:

actor - CompositeActor in which to search for the names.

prefix - Given prefix that shall be suffixed to get a unique name.

Returns:

A unique name in the composite actor namespace.

_isConnected

protected static boolean _isConnected(NamedObj namedObj)

Check whether the given Ptolemy model object has any connections, i.e. is connected to any other components via some link.

Parameters:

namedObj - The Ptolemy model object which is to be analyzed

Returns:

True if the object is an Actor and any port has any relations or is connected to any other port; true if the object is a Relation; false if the object is an Attribute. Defaults to false.

_isInput

protected static boolean _isInput(Port port)

Determine whether a given Port is an input port.

Parameters:

port - The port to be analyzed

Returns:

True if the port is an input port

_performChangeRequest

protected void _performChangeRequest(CompositeActor actor)

Flush all buffered change requests to the given Actor. Reset the buffer afterwards.

Parameters:

actor - The target of the change request, e.g. the composite actor containing the objects for which changes are requested.

_setLocation

protected void _setLocation(NamedObj obj,
                            double x,
                            double y)

Create a MoMLChangeRequest to move a Ptolemy model object and schedule it immediately. The request is addressed to a specific NamedObj in the Ptolemy model and hence does not get buffered because there is only exactly one move request per layout run per node.

Parameters:

obj - Ptolemy node to be moved

x - new coordinate

y - new coordinate

_setLocation

protected void _setLocation(Vertex vertex,
                            Relation relation,
                            double x,
                            double y)

Create a MoMLChangeRequest to move a Ptolemy model object and schedule it immediately. The request is addressed to a specific NamedObj in the Ptolemy model and hence does not get buffered because there is only exactly one move request per layout run per node.

Parameters:

vertex - Ptolemy node to be moved

relation - Ptolemy Relation to be moved

x - new coordinate

y - new coordinate

_showUnnecessaryRelations

protected static void _showUnnecessaryRelations(CompositeActor parent,
                                                boolean show)

Show or hide unnecessary relation vertices. Iterate all relations in the parent composite actor and find unnecessary relations. I.e. relations that are connected to exactly 2 other object. These relation vertices have no semantic impact and are likely only added to manipulate the routing of the corresponding edges. Either hide or show those relation vertices. Relations with connection degree 0 or 1 do not get hidden, because they are not only inserted for layout. Usually those are completely unnecessary and should be removed, so the user should be able to see them.

Parameters:

parent - Composite actor that should be searched for unnecessary vertices.

show - True iff the vertices should be shown, false if hidden.

_showUnnecessaryRelationsToggle

public static void _showUnnecessaryRelationsToggle(CompositeActor parent)

Toggle show or hide status of unnecessary relation vertices. Iterate all relations in the parent composite actor and find unnecessary relations. I.e. relations that are connected to exactly 2 other object. These relation vertices have no semantic impact and are likely only added to manipulate the routing of the corresponding edges. Either hide or show those relation vertices. Relations with connection degree 0 or 1 do not get hidden, because they are not only inserted for layout. Usually those are completely unnecessary and should be removed, so the user should be able to see them.

Parameters:

parent - Composite actor that should be searched for unnecessary vertices.

_stripNumericSuffix

protected static java.lang.String _stripNumericSuffix(java.lang.String string)

Return a string that is identical to the specified string except any trailing digits are removed.

Parameters:

string - The string to strip of its numeric suffix.

Returns:

A string with no numeric suffix.

_unlinkPort

protected void _unlinkPort(java.lang.String portName,
                           int index)

Unlink a port at the given channel index.

Parameters:

portName - Name of the Port.

index - Index of the channel to be unlinked.

_unlinkPortInside

protected void _unlinkPortInside(java.lang.String portName,
                                 int insideIndex)

Unlink a port at the given channel inside index.

Parameters:

portName - Name of the Port.

insideIndex - Index of the channel to be unlinked.

_unlinkRelations

protected void _unlinkRelations(java.lang.String relation1,
                                java.lang.String relation2)

Unlink two relations.

Parameters:

relation1 - Name of first relation to unlink.

relation2 - Name of second relation to unlink.