ptolemy.kernel
Class ComponentRelation

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

All Implemented Interfaces:

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

Direct Known Subclasses:

IORelation, Transition, Transition

public class ComponentRelation
extends Relation

This class defines a relation supporting hierarchy (clustered graphs). Specifically, a method is added for defining a container and for performing deep traversals of a graph. Most importantly, however, instances of this class refuse to link to ports that are not instances of ComponentPort. Thus, this class ensures that ComponentPort instances are only connected to other ComponentPort instances.

Derived classes may wish to further constrain linked ports to a subclass of ComponentPort, or to disallow links under other circumstances, for example if the relation cannot support any more links. Such derived classes should override the protected method _checkPort() to throw an exception.

To link a ComponentPort to a ComponentRelation, use the link() or liberalLink() method in the ComponentPort class. To remove a link, use the unlink() method.

The container for instances of this class can only be instances of ComponentEntity. Derived classes may wish to further constrain the container to subclasses of ComponentEntity. To do this, they should override the protected _checkContainer() method.

Since:

Ptolemy II 0.2

Version:

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

Author:

Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Green (johnr)

Proposed Rating:

Green (eal)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

private CompositeEntity	_container
private java.util.List	_deepLinkedPorts
private long	_deepLinkedPortsVersion

Fields inherited from class ptolemy.kernel.Relation

_linkList

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

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

ComponentRelation(CompositeEntity container, java.lang.String name)
Construct a relation with the given name contained by the specified entity.

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

Method Summary

protected void	_checkContainer(CompositeEntity container) Check that the specified container is of a suitable class for this relation.
protected void	_checkPort(Port port) Throw an exception if the specified port cannot be linked to this relation (is not of class ComponentPort).
protected void	_checkRelation(Relation relation, boolean symmetric) Throw an exception if the specified relation is not an instance of ComponentRelation.
protected NamedObj	_propagateExistence(NamedObj container) Propagate existence of this object to the specified object.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
java.util.List	deepLinkedPortList() Deeply list the ports linked to this relation.
java.util.Enumeration	deepLinkedPorts() Deprecated. Use deepLinkedPortList() instead.
NamedObj	getContainer() Get the container entity.
int	moveDown() Move this object down by one in the list of relations of its container.
int	moveToFirst() Move this object to the first position in the list of relations of the container.
int	moveToIndex(int index) Move this object to the specified position in the list of relations of the container.
int	moveToLast() Move this object to the last position in the list of relations of the container.
int	moveUp() Move this object up by one in the list of relations of the container.
void	setContainer(CompositeEntity container) Specify the container entity, adding the relation to the list of relations in the container.
void	setName(java.lang.String name) Set the name of the ComponentRelation.
void	unlinkAll() Override the base class to break inside links on ports as well as outside lists.

Methods inherited from class ptolemy.kernel.Relation

_description, _getContainedObject, link, linkedObjectsList, linkedPortList, linkedPortList, linkedPorts, linkedPorts, numLinks, relationGroupList, unlink

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _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, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, 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

_container

private CompositeEntity _container

_deepLinkedPorts

private transient java.util.List _deepLinkedPorts

_deepLinkedPortsVersion

private transient long _deepLinkedPortsVersion

Constructor Detail

ComponentRelation

public ComponentRelation()

Construct a relation in the default workspace with an empty string as its name. Add the relation to the directory of the workspace.

ComponentRelation

public ComponentRelation(Workspace workspace)

Construct a relation in the specified workspace with an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. Add the relation to the workspace directory.

Parameters:

workspace - The workspace that will list the relation.

ComponentRelation

public ComponentRelation(CompositeEntity container,
                         java.lang.String name)
                  throws IllegalActionException,
                         NameDuplicationException

Construct a relation with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This relation will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. This constructor write-synchronizes on the workspace.

Parameters:

container - The container.

name - The name of the relation.

Throws:

IllegalActionException - If the container is incompatible with this relation.

NameDuplicationException - If the name coincides with a relation already in the container.

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 Relation

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new ComponentRelation.

Throws:

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

See Also:

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

deepLinkedPortList

public java.util.List deepLinkedPortList()

Deeply list the ports linked to this relation. Look through all transparent ports and return only opaque ports. This method is read-synchronized on the workspace.

Returns:

An unmodifiable list of ComponentPorts.

deepLinkedPorts

public java.util.Enumeration deepLinkedPorts()

Deprecated. Use deepLinkedPortList() instead.

Deeply enumerate the ports linked to this relation. Look through all transparent ports and return only opaque ports. This method is read-synchronized on the workspace.

Returns:

An enumeration of ComponentPorts.

getContainer

public NamedObj getContainer()

Get the container entity.

Specified by:

getContainer in interface Nameable

Overrides:

getContainer in class NamedObj

Returns:

An instance of CompositeEntity.

See Also:

setContainer(CompositeEntity)

moveDown

public int moveDown()
             throws IllegalActionException

Move this object down by one in the list of relations of its container. If this object is already last, do nothing. Increment the version of the workspace.

Specified by:

moveDown in interface Moveable

Overrides:

moveDown in class NamedObj

Returns:

The index of the specified object prior to moving it, or -1 if it is not moved.

Throws:

IllegalActionException - If this object has no container.

moveToFirst

public int moveToFirst()
                throws IllegalActionException

Move this object to the first position in the list of relations of the container. If this object is already first, do nothing. Increment the version of the workspace.

Specified by:

moveToFirst in interface Moveable

Overrides:

moveToFirst in class NamedObj

Returns:

The index of the specified object prior to moving it, or -1 if it is not moved.

Throws:

IllegalActionException - If this object has no container.

moveToIndex

public int moveToIndex(int index)
                throws IllegalActionException

Move this object to the specified position in the list of relations of the container. If this object is already at the specified position, do nothing. Increment the version of the workspace.

Specified by:

moveToIndex in interface Moveable

Overrides:

moveToIndex in class NamedObj

Parameters:

index - The position to move this object to.

Returns:

The index of the specified object prior to moving it, or -1 if it is not moved.

Throws:

IllegalActionException - If this object has no container or if the index is out of bounds.

moveToLast

public int moveToLast()
               throws IllegalActionException

Move this object to the last position in the list of relations of the container. If this object is already last, do nothing. Increment the version of the workspace.

Specified by:

moveToLast in interface Moveable

Overrides:

moveToLast in class NamedObj

Returns:

The index of the specified object prior to moving it, or -1 if it is not moved.

Throws:

IllegalActionException - If this object has no container.

moveUp

public int moveUp()
           throws IllegalActionException

Move this object up by one in the list of relations of the container. If this object is already first, do nothing. Increment the version of the workspace.

Specified by:

moveUp in interface Moveable

Overrides:

moveUp in class NamedObj

Returns:

The index of the specified object prior to moving it, or -1 if it is not moved.

Throws:

IllegalActionException - If this object has no container.

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Specify the container entity, adding the relation to the list of relations in the container. If the container already contains a relation with the same name, then throw an exception and do not make any changes. Similarly, if the container is not in the same workspace as this relation, throw an exception. If the relation is a class element and the proposed container does not match the current container, then also throw an exception. If the relation is already contained by the container, do nothing. If this relation already has a container, remove it from that container first. Otherwise, remove it from the workspace directory, if it is present. If the argument is null, then unlink the ports from the relation and remove it from its container. It is not added to the workspace directory, so this could result in this relation being garbage collected. Derived classes may further constrain the class of the container to a subclass of CompositeEntity. This method validates all deeply contained instances of Settable, since they may no longer be valid in the new context. This method is write-synchronized on the workspace and increments its version number.

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If this entity and the container are not in the same workspace, or if a contained Settable becomes invalid and the error handler throws it.

NameDuplicationException - If the name collides with a name already on the contents list of the container.

See Also:

getContainer()

setName

public void setName(java.lang.String name)
             throws IllegalActionException,
                    NameDuplicationException

Set the name of the ComponentRelation. If there is already a ComponentRelation of the container with the same name, throw an exception.

Specified by:

setName in interface Nameable

Overrides:

setName in class NamedObj

Parameters:

name - The new name.

Throws:

IllegalActionException - If the name has a period.

NameDuplicationException - If there is already a relation with the same name in the container.

See Also:

NamedObj.getName(), NamedObj.getName(NamedObj)

unlinkAll

public void unlinkAll()

Override the base class to break inside links on ports as well as outside lists. This method is write-synchronized on the workspace and increments its version number.

Overrides:

unlinkAll in class Relation

_checkContainer

protected void _checkContainer(CompositeEntity container)
                        throws IllegalActionException

Check that the specified container is of a suitable class for this relation. In this base class, this method returns immediately without doing anything.

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the container is not of an acceptable class. Not thrown in this base class.

_checkPort

protected void _checkPort(Port port)
                   throws IllegalActionException

Throw an exception if the specified port cannot be linked to this relation (is not of class ComponentPort).

Overrides:

_checkPort in class Relation

Parameters:

port - The port to link to.

Throws:

IllegalActionException - If the port is not a ComponentPort.

_checkRelation

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

Throw an exception if the specified relation is not an instance of ComponentRelation.

Overrides:

_checkRelation in class Relation

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 port has no container, or if this port is not an acceptable port for the specified relation.

_propagateExistence

protected NamedObj _propagateExistence(NamedObj container)
                                throws IllegalActionException

Propagate existence of this object to the specified object. This overrides the base class to set the container.

Overrides:

_propagateExistence in class NamedObj

Parameters:

container - Object to contain the new object.

Returns:

A new object of the same class and name as this one.

Throws:

IllegalActionException - If the object cannot be cloned.