ptolemy.kernel
Class Relation

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.Relation

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

ComponentRelation

public class Relation
extends NamedObj

A Relation links ports, and therefore the entities that contain them. To link a port to a relation, use the link() method in the Port class. To remove a link, use the unlink() method in the Port class.

Relations can also be linked to other Relations. To create such a link, use the link() method of this class. To remove such a link, use the unlink() method. A group of linked relations behaves exactly as if it were one relation directly linked to all the ports linked to by each relation. In particular, the connectedPortList() method of the Port class returns the same list whether a single relation is used or a relation group. The order in which the ports are listed is the order in which links were made between the port and relations in the relation group. It is not relevant which relation in a relation group the port links to.

Derived classes may wish to disallow links under certain circumstances, for example if the proposed port is not an instance of an appropriate subclass of Port, or if the relation cannot support any more links. Such derived classes should override the protected method _checkPort() or _checkRelation() to throw an exception.

Since:

Ptolemy II 0.2

Version:

$Id: Relation.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Edward A. Lee, Neil Smyth

See Also:

Port, Entity, Serialized Form

Accepted Rating:

Green (acataldo)

Proposed Rating:

Green (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

protected CrossRefList

_linkList The list of Ports and Relations that are linked to this Relation.

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Relation()
Construct a relation in the default workspace with an empty string as its name.

Relation(java.lang.String name)
Construct a relation in the default workspace with the given name.

Relation(Workspace workspace)
Construct a relation in the given workspace with an empty string as a name.

Relation(Workspace workspace, java.lang.String name)
Construct a relation in the given workspace with the given name.

Method Summary

protected void	_checkPort(Port port) Throw an exception if the specified port cannot be linked to this relation.
protected void	_checkRelation(Relation relation, boolean symmetric) Check that this relation is compatible with the specified relation.
protected java.lang.String	_description(int detail, int indent, int bracket) Return a description of the object.
protected NamedObj	_getContainedObject(NamedObj container, java.lang.String relativeName) Get a relation with the specified name in the specified container.
private java.util.List	_linkedPortList(Port exceptPort, java.util.Set exceptRelations) List the linked ports except the exceptPort and those linked via the relations in the exceptRelations list.
private void	_relationGroup(java.util.List list) Append to the specified list all relations in the relation group with this one that are not already on the list.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
void	link(Relation relation) Link this relation with another relation.
java.util.List	linkedObjectsList() Return a list of the objects directly linked to this relation (ports and relations).
java.util.List	linkedPortList() List the ports linked to any relation in this relation's group.
java.util.List	linkedPortList(Port except) List the ports linked to any relation in this relation's group except the specified port.
java.util.Enumeration	linkedPorts() Deprecated. Use linkedPortList() instead.
java.util.Enumeration	linkedPorts(Port except) Deprecated. Use linkedPortList(Port) instead.
int	numLinks() Return the number of links to ports, either directly or indirectly via other relations in the relation group.
java.util.List	relationGroupList() Return the list of relations in the relation group containing this relation.
void	unlink(Relation relation) Unlink the specified Relation.
void	unlinkAll() Unlink all ports and relations that are directly linked to this relation.

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateExistence, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getContainer, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setName, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Field Detail

_linkList

protected CrossRefList _linkList

The list of Ports and Relations that are linked to this Relation.

Constructor Detail

Relation

public Relation()

Construct a relation in the default workspace with an empty string as its name. Increment the version number of the workspace. The object is added to the workspace directory.

Relation

public Relation(java.lang.String name)
         throws IllegalActionException

Construct a relation in the default workspace with the given name. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace. The object is added to the workspace directory.

Parameters:

name - Name of this object.

Throws:

IllegalActionException - If the name has a period.

Relation

public Relation(Workspace workspace)

Construct a relation in the given workspace with an empty string as a name. If the workspace argument is null, use the default workspace. The object is added to the workspace directory. Increment the version of the workspace.

Parameters:

workspace - The workspace for synchronization and version tracking.

Relation

public Relation(Workspace workspace,
                java.lang.String name)
         throws IllegalActionException

Construct a relation in the given workspace with the given name. If the workspace argument is null, use the default workspace. If the name argument is null, then the name is set to the empty string. The object is added to the workspace directory. Increment the version of the workspace.

Parameters:

workspace - Workspace for synchronization and version tracking

name - Name of this object.

Throws:

IllegalActionException - If the name has a period.

Method Detail

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new relation with no links and no container.

Overrides:

clone in class NamedObj

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new Relation.

Throws:

java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

link

public void link(Relation relation)
          throws IllegalActionException

Link this relation with another relation. The relation is required to be at the same level of the hierarchy as this relation. That is, level-crossing links are not allowed. If the specified relation is already linked to this one, do nothing. In derived classes, the relation may be required to be an instance of a particular subclass of Relation (this is checked by the _checkRelation() protected method). This method is write-synchronized on the workspace and increments its version number.

Parameters:

relation - The relation to link to this relation.

Throws:

IllegalActionException - If the link would cross levels of the hierarchy, or the relation is incompatible, or this relation has no container, or this relation is not in the same workspace as the relation.

linkedObjectsList

public java.util.List linkedObjectsList()

Return a list of the objects directly linked to this relation (ports and relations). Note that a port may appear more than once if more than one link to it has been established, but a relation will appear only once. There is no significance to multiple links between the same relations. This method is read-synchronized on the workspace.

Returns:

A list of Port and Relation objects.

linkedPortList

public java.util.List linkedPortList()

List the ports linked to any relation in this relation's group. Note that a port may appear more than once if more than one link to it has been established. The order in which ports are listed has no significance. This method is read-synchronized on the workspace.

Returns:

A list of Port objects.

linkedPortList

public java.util.List linkedPortList(Port except)

List the ports linked to any relation in this relation's group except the specified port. Note that a port may appear more than once if more than on link to it has been established. The order in which ports are listed has no significance. This method is read-synchronized on the workspace.

Parameters:

except - Port to exclude from the list.

Returns:

A list of Port objects.

linkedPorts

public java.util.Enumeration linkedPorts()

Deprecated. Use linkedPortList() instead.

Enumerate the linked ports. Note that a port may appear more than once if more than one link to it has been established. This method is read-synchronized on the workspace.

Returns:

An Enumeration of Port objects.

linkedPorts

public java.util.Enumeration linkedPorts(Port except)

Deprecated. Use linkedPortList(Port) instead.

Enumerate the linked ports except the specified port. Note that a port may appear more than once if more than on link to it has been established. This method is read-synchronized on the workspace.

Parameters:

except - Port to exclude from the enumeration.

Returns:

An Enumeration of Port objects.

numLinks

public int numLinks()

Return the number of links to ports, either directly or indirectly via other relations in the relation group. This is the size of the list returned by linkedPortList(). This method is read-synchronized on the workspace.

Returns:

The number of links.

See Also:

linkedPortList()

relationGroupList

public java.util.List relationGroupList()

Return the list of relations in the relation group containing this relation. The relation group includes this relation, all relations directly linked to it, all relations directly linked to those, etc. That is, it is a maximal set of linked relations. There is no significance to the order of the returned list, but the returned value is a List rather than a Set to facilitate testing.

Returns:

The relation group.

unlink

public void unlink(Relation relation)

Unlink the specified Relation. If the Relation is not linked to this relation, do nothing. This method is write-synchronized on the workspace and increments its version number.

Parameters:

relation - The relation to unlink.

unlinkAll

public void unlinkAll()

Unlink all ports and relations that are directly linked to this relation. This method is write-synchronized on the workspace and increments its version number.

_checkPort

protected void _checkPort(Port port)
                   throws IllegalActionException

Throw an exception if the specified port cannot be linked to this relation. In this base class, the exception is not thrown, but in derived classes, it might be, for example if the relation cannot support any more links, or the port is not an instance of an appropriate subclass of Port.

Parameters:

port - The port to link to.

Throws:

IllegalActionException - Not thrown in this base class.

_checkRelation

protected void _checkRelation(Relation relation,
                              boolean symmetric)
                       throws IllegalActionException

Check that this relation is compatible with the specified relation. In this base class, this method calls the corresponding check method of the specified relation, and if that returns, then it returns. Derived classes should override this method to check validity of the specified relation, and then call super._checkRelation().

Parameters:

relation - The relation to link to.

symmetric - If true, the call _checkRelation on the specified relation with this as an argument.

Throws:

IllegalActionException - If this relation has no container, or if this relation is not an acceptable relation for the specified relation.

_description

protected java.lang.String _description(int detail,
                                        int indent,
                                        int bracket)
                                 throws IllegalActionException

Return a description of the object. The level of detail depends on the argument, which is an or-ing of the static final constants defined in the NamedObj class. Lines are indented according to to the level argument using the protected method _getIndentPrefix(). Zero, one or two brackets can be specified to surround the returned description. If one is specified it is the the leading bracket. This is used by derived classes that will append to the description. Those derived classes are responsible for the closing bracket. An argument other than 0, 1, or 2 is taken to be equivalent to 0. This method is read-synchronized on the workspace.

Overrides:

_description in class NamedObj

Parameters:

detail - The level of detail.

indent - The amount of indenting.

bracket - The number of surrounding brackets (0, 1, or 2).

Returns:

A description of the object.

Throws:

IllegalActionException

_getContainedObject

protected NamedObj _getContainedObject(NamedObj container,
                                       java.lang.String relativeName)
                                throws IllegalActionException

Get a relation with the specified name in the specified container. The returned object is assured of being an instance of the same class as this object.

Overrides:

_getContainedObject in class NamedObj

Parameters:

relativeName - The name relative to the container.

container - The container expected to contain the object, which must be an instance of CompositeEntity.

Returns:

An object of the same class as this object, or null if there is none.

Throws:

IllegalActionException - If the object exists and has the wrong class, or if the specified container is not an instance of CompositeEntity.

_linkedPortList

private java.util.List _linkedPortList(Port exceptPort,
                                       java.util.Set exceptRelations)

List the linked ports except the exceptPort and those linked via the relations in the exceptRelations list. This relation is added to the exceptRelations list before returning. Note that a port may appear more than once if more than one link to it has been established. This method is not read-synchronized on the workspace, so the caller is expected to be.

Parameters:

exceptPort - A port to exclude, or null to not specify one.

exceptRelations - Set of relations to exclude.

Returns:

A list of Port objects.

_relationGroup

private void _relationGroup(java.util.List list)

Append to the specified list all relations in the relation group with this one that are not already on the list. The relation group includes this relation, all relations directly linked to it, all relations directly linked to those, etc.

Parameters:

list - The list to append to.