ptolemy.kernel
Class Relation

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.Relation
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
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.

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() to throw an exception.

Since:
Ptolemy II 0.2
Version:
$Id: Relation.java,v 1.119.2.1 2004/06/18 00:49:16 cxh Exp $
Author:
Edward A. Lee, Neil Smyth
See Also:
Port, Entity, Serialized Form
Accepted Rating:
Green (johnr)
Proposed Rating:
Green (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _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  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.
protected  CrossRefList _getPortList()
          Return a reference to the local port list.
 java.lang.Object clone(Workspace workspace)
          Clone the object into the specified workspace.
 java.util.List linkedPortList()
          List the linked ports.
 java.util.List linkedPortList(Port except)
          List the linked ports except the specified port.
 java.util.Enumeration linkedPorts()
          Enumerate the linked ports.
 java.util.Enumeration linkedPorts(Port except)
          Deprecated. Use linkedPortList() instead.
 int numLinks()
          Return the number of links to ports.
 void unlinkAll()
          Unlink all ports.
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateExistence, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getContainer, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setName, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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)

linkedPortList

public java.util.List linkedPortList()
List 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:
A list of Port objects.

linkedPortList

public java.util.List linkedPortList(Port except)
List 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:
A list of Port objects.

linkedPorts

public java.util.Enumeration linkedPorts()
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() 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. This method is read-synchronized on the workspace.

Returns:
The number of links.

unlinkAll

public void unlinkAll()
Unlink all ports. 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.

_description

protected java.lang.String _description(int detail,
                                        int indent,
                                        int bracket)
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.

_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.

_getPortList

protected CrossRefList _getPortList()
Return a reference to the local port list. NOTE : This method has been made protected only for the purpose of connecting Ports to Relations (see Port.link(Relation)).

Returns:
The link list.
See Also:
Port