ptolemy.kernel
Class Entity

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity

All Implemented Interfaces:

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

Direct Known Subclasses:

ComponentEntity

public class Entity
extends InstantiableNamedObj

An Entity is a vertex in a generalized graph. It is an aggregation of ports. The ports can be linked to relations. The relations thus represent connections between ports, and hence, connections between entities. To add a port to an entity, simply set its container to the entity. To remove it, set its container to null, or to some other entity.

Entities are intended for flat graphs. Derived classes support hierarchy (clustered graphs) by defining entities that aggregate other entities.

An Entity can contain any instance of Port. Derived classes may wish to constrain to a subclass of Port. To do this, subclasses should override the public method newPort() to create a port of the appropriate subclass, and the protected method _addPort() to throw an exception if its argument is a port that is not of the appropriate subclass.

An Entity is created within a workspace. If the workspace is not specified as a constructor argument, then the default workspace is used. The workspace is used to synchronize simultaneous accesses to a topology from multiple threads. The workspace is immutable (it cannot be changed during the lifetime of the Entity).

Since:

Ptolemy II 0.2

Version:

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

Author:

John S. Davis II, Edward A. Lee

See Also:

Port, Relation, Serialized Form

Accepted Rating:

Green (johnr)

Proposed Rating:

Green (eal)

Nested Class Summary

protected class

Entity.ContainedObjectsIterator This class is an iterator over all the contained objects (all instances of NamedObj).

Field Summary

private java.util.LinkedList	_connectedPorts
private long	_connectedPortsVersion
private java.util.LinkedList	_linkedRelations
private long	_linkedRelationsVersion
(package private) NamedList	_portList A list of Ports owned by this Entity.

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

Entity()
Construct an entity in the default workspace with an empty string as its name.

Entity(java.lang.String name)
Construct an entity in the default workspace with the given name.

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

Entity(Workspace workspace, java.lang.String name)
Construct an entity in the given workspace with the given name.

Method Summary

protected void	_addPort(Port port) Add a port to this entity.
protected java.lang.String	_description(int detail, int indent, int bracket) Return a description of the object.
protected void	_exportMoMLContents(java.io.Writer output, int depth) Write a MoML description of the contents of this object, which in this class are the attributes plus the ports.
protected void	_removePort(Port port) Remove the specified port.
protected void	_validateSettables(java.util.Collection attributesValidated) Validate attributes deeply contained by this object if they implement the Settable interface by calling their validate() method.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
java.util.List	connectedPortList() Return a list of the ports that are connected to contained ports.
java.util.Enumeration	connectedPorts() Deprecated. Use connectedPortList() instead.
void	connectionsChanged(Port port) Notify this entity that the links to the specified port have been altered.
java.util.Iterator	containedObjectsIterator() Return an iterator over contained objects.
Attribute	getAttribute(java.lang.String name) Get the attribute with the given name.
Port	getPort(java.lang.String name) Return the port contained by this entity that has the specified name.
java.util.Enumeration	getPorts() Deprecated. Use portList() instead.
java.util.List	linkedRelationList() Get all relations that are linked to ports contained by this entity.
java.util.Enumeration	linkedRelations() Deprecated. Use linkedRelationList() instead.
Port	newPort(java.lang.String name) Create a new port with the specified name.
java.util.List	portList() Get the ports belonging to this entity.
void	removeAllPorts() Remove all ports by setting their container to null.
void	setClassDefinition(boolean isClass) Specify whether this object is a class definition.
java.lang.String	uniqueName(java.lang.String prefix) Return a name that is guaranteed to not be the name of any contained attribute or port.

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, instantiate, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getContainedObject, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateExistence, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getContainer, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, 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, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateExistence, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Field Detail

_portList

NamedList _portList

A list of Ports owned by this Entity.

_connectedPorts

private transient java.util.LinkedList _connectedPorts

_connectedPortsVersion

private transient long _connectedPortsVersion

_linkedRelations

private transient java.util.LinkedList _linkedRelations

_linkedRelationsVersion

private transient long _linkedRelationsVersion

Constructor Detail

Entity

public Entity()

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

Entity

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

Construct an entity in the default workspace with the given name. 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 number of the workspace.

Parameters:

name - The name of this object.

Throws:

IllegalActionException - If the name has a period.

Entity

public Entity(Workspace workspace)

Construct an entity 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.

Entity

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

Construct an entity 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 - The workspace for synchronization and version tracking.

name - The 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 entity with clones of the ports of the original entity. The ports are set to the ports of the new entity. This method gets read access on the workspace associated with this object.

Overrides:

clone in class InstantiableNamedObj

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Entity.

Throws:

java.lang.CloneNotSupportedException - If cloned ports cannot have as their container the cloned entity (this should not occur), or if one of the attributes cannot be cloned.

See Also:

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

connectedPortList

public java.util.List connectedPortList()

Return a list of the ports that are connected to contained ports. Ports in this entity are not included unless there is a loopback, meaning that two distinct ports of this entity are linked to the same relation. The connected entities can be obtained from the ports using getContainer(). Note that a port may be listed more than once if there is more than one connection to it. This method is read-synchronized on the workspace.

Returns:

An unmodifiable list of Port objects.

connectedPorts

public java.util.Enumeration connectedPorts()

Deprecated. Use connectedPortList() instead.

Enumerate all ports that are connected to contained ports. Ports in this entity are not included unless there is a loopback, meaning that two distinct ports of this entity are linked to the same relation. The connected entities can be obtained from the ports using getContainer(). Note that a port may be listed more than once if there is more than one connection to it. This method is read-synchronized on the workspace.

Returns:

An enumeration of Port objects.

connectionsChanged

public void connectionsChanged(Port port)

Notify this entity that the links to the specified port have been altered. The default implementation in this base class is to do nothing, but derived classes may want to react to new connections.

Parameters:

port - The port to which connections have changed.

containedObjectsIterator

public java.util.Iterator containedObjectsIterator()

Return an iterator over contained objects. In this class, this is simply an iterator over attributes and ports. In derived classes, the iterator will also traverse classes, entities, and relations. The caller of this method should have read access on the workspace and hold it for the duration of the use of the iterator. Moreover, it should not modify the port or attribute list while using the iterator or it will get a ConcurrentModificationException.

Overrides:

containedObjectsIterator in class NamedObj

Returns:

An iterator over instances of NamedObj contained by this object.

getAttribute

public Attribute getAttribute(java.lang.String name)

Get the attribute with the given name. The name may be compound, with fields separated by periods, in which case the attribute returned is (deeply) contained by a contained attribute or port. This method is read-synchronized on the workspace.

Overrides:

getAttribute in class NamedObj

Parameters:

name - The name of the desired attribute.

Returns:

The requested attribute if it is found, null otherwise.

getPort

public Port getPort(java.lang.String name)

Return the port contained by this entity that has the specified name. If there is no such port, return null. This method is read-synchronized on the workspace.

Parameters:

name - The name of the desired port.

Returns:

A port with the given name, or null if none exists.

getPorts

public java.util.Enumeration getPorts()

Deprecated. Use portList() instead.

Enumerate the ports belonging to this entity. The order is the order in which they became contained by this entity. This method is read-synchronized on the workspace.

Returns:

An enumeration of Port objects.

linkedRelationList

public java.util.List linkedRelationList()

Get all relations that are linked to ports contained by this entity. Note that a relation may be listed more once. This method is read-synchronized on the workspace.

Returns:

An unmodifiable list of Relation objects.

linkedRelations

public java.util.Enumeration linkedRelations()

Deprecated. Use linkedRelationList() instead.

Enumerate relations that are linked to ports contained by this entity. Note that a relation may be listed more once. This method is read-synchronized on the workspace.

Returns:

An enumeration of Relation objects.

newPort

public Port newPort(java.lang.String name)
             throws IllegalActionException,
                    NameDuplicationException

Create a new port with the specified name. Set its container to be this entity. Derived classes should override this method to create a subclass of Port, if they require subclasses of Port. If the name argument is null, then the name used is an empty string. This method is write-synchronized on the workspace, and increments its version number.

Parameters:

name - The name to assign to the newly created port.

Returns:

The new port.

Throws:

IllegalActionException - If the port created is not of an acceptable class (this is a programming error; failed to override this method in derived classes).

NameDuplicationException - If the entity already has a port with the specified name.

portList

public java.util.List portList()

Get the ports belonging to this entity. The order is the order in which they became contained by this entity. This method is read-synchronized on the workspace.

Returns:

An unmodifiable list of Port objects.

removeAllPorts

public void removeAllPorts()

Remove all ports by setting their container to null. As a side effect, the ports will be unlinked from all relations. This method is write-synchronized on the workspace, and increments its version number.

setClassDefinition

public void setClassDefinition(boolean isClass)
                        throws IllegalActionException

Specify whether this object is a class definition. This method overrides the base class to check that if the argument is true, then this entity contains no ports with links. This method is write synchronized on the workspace.

Overrides:

setClassDefinition in class InstantiableNamedObj

Parameters:

isClass - True to make this object a class definition.

Throws:

IllegalActionException - If the argument is true and this entity contains ports with links.

See Also:

InstantiableNamedObj.isClassDefinition(), Instantiable

uniqueName

public java.lang.String uniqueName(java.lang.String prefix)

Return a name that is guaranteed to not be the name of any contained attribute or port. In derived classes, this should be overridden so that the returned name is guaranteed to not conflict with any contained object. In this implementation, the argument is stripped of any numeric suffix, and then a numeric suffix is appended and incremented until a name is found that does not conflict with a contained attribute or port.

Overrides:

uniqueName in class NamedObj

Parameters:

prefix - A prefix for the name.

Returns:

A unique name.

_addPort

protected void _addPort(Port port)
                 throws IllegalActionException,
                        NameDuplicationException

Add a port to this entity. This method should not be used directly. Call the setContainer() method of the port instead. This method does not set the container of the port to point to this entity. It assumes that the port is in the same workspace as this entity, but does not check. The caller should check. Derived classes should override this method if they require a subclass of Port to throw an exception if the argument is not of an acceptable class. This method is not synchronized on the workspace, so the caller should be.

Parameters:

port - The port to add to this entity.

Throws:

IllegalActionException - If the port has no name.

NameDuplicationException - If the port name collides with a name already in the entity.

_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

_exportMoMLContents

protected void _exportMoMLContents(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException

Write a MoML description of the contents of this object, which in this class are the attributes plus the ports. This method is called by exportMoML(). Each description is indented according to the specified depth and terminated with a newline character.

Overrides:

_exportMoMLContents in class NamedObj

Parameters:

output - The output to write to.

depth - The depth in the hierarchy, to determine indenting.

Throws:

java.io.IOException - If an I/O error occurs.

See Also:

NamedObj.exportMoML(Writer, int)

_removePort

protected void _removePort(Port port)

Remove the specified port. This method should not be used directly. Call the setContainer() method of the port instead with a null argument. The port is assumed to be contained by this entity (otherwise, nothing happens). This method does not alter the container of the port. This method is not synchronized on the workspace, so the caller should be.

Parameters:

port - The port being removed from this entity.

_validateSettables

protected void _validateSettables(java.util.Collection attributesValidated)
                           throws IllegalActionException

Validate attributes deeply contained by this object if they implement the Settable interface by calling their validate() method. This method overrides the base class to check attributes contained by the contained ports. Errors that are triggered by this validation are handled by calling handleModelError().

Overrides:

_validateSettables in class NamedObj

Parameters:

attributesValidated - A HashSet of Attributes that have already been validated. For example, Settables that implement the SharedSettable interface are validated only once.

Throws:

IllegalActionException - If the superclass throws it or if handleModelError() throws it.

See Also:

NamedObj.handleModelError(NamedObj context, IllegalActionException exception)