ptolemy.kernel
Class CompositeEntity

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

All Implemented Interfaces:

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

Direct Known Subclasses:

CompositeActor, Configuration, Effigy, EffigyFactory, EntityLibrary, FSMActor, FSMActor, ModelDirectory, Tableau

public class CompositeEntity
extends ComponentEntity

A CompositeEntity is a cluster in a clustered graph. I.e., it is a non-atomic entity, in that it can contain other entities and relations. It supports transparent ports, where, in effect, the port of a contained entity is represented by a port of this entity. Methods that "deeply" traverse the topology see right through transparent ports. It may be opaque, in which case its ports are opaque and methods that "deeply" traverse the topology do not see through them. For instance, deepEntityList() returns the opaque entities directly or indirectly contained by this entity.

To add an entity or relation to this composite, call its setContainer() method with this composite as an argument. To remove it, call its setContainer() method with a null argument (or another container). The entity must be an instance of ComponentEntity and the relation of ComponentRelation or an exception is thrown. Derived classes may further constrain these to subclasses. To do that, they should override the protected methods _addEntity() and _addRelation() and the public member newRelation().

A CompositeEntity may be contained by another CompositeEntity. To set that up, call the setContainer() method of the inside entity. Derived classes may further constrain the container to be a subclass of CompositeEntity. To do this, they should override setContainer() to throw an exception. Recursive containment structures, where an entity directly or indirectly contains itself, are disallowed, and an exception is thrown on an attempt to set up such a structure.

A CompositeEntity can contain instances of ComponentPort. By default these ports will be transparent, although subclasses of CompositeEntity can make them opaque by overriding the isOpaque() method to return true. Derived classes may further constrain the ports to a subclass of ComponentPort. To do this, they 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.

Since contained entities implement the Instantiable interface, some may be class definitions. If an entity is a class definition, then it is not included in the lists returned by entityList(), entityList(Class), deepEntityList(), and allAtomicEntityList(). Correspondingly, if it is not a class definition, then it is not included in the list returned by classDefinitionList(). Contained class definitions are nonetheless required to have names distinct from contained entities that are not class definitions, and the method getEntity(String) will return either a class definition or an entity that is not a class definition, as long as the name matches. Note that contained entities that are class definitions cannot be connected to other entities. Moreover, they cannot be deleted as long as there are either subclasses or instances present.

Since:

Ptolemy II 0.2

Version:

$Id: CompositeEntity.java 59167 2010-09-21 17:08:02Z cxh $

Author:

John S. Davis II, Edward A. Lee, contributor: Christopher Brooks

See Also:

Serialized Form

Accepted Rating:

Green (hyzheng)

Proposed Rating:

Green (eal)

Nested Class Summary

protected class	CompositeEntity.ContainedObjectsIterator This class is an iterator over all the contained objects (all instances of NamedObj).
private static class	CompositeEntity.CountComparator A comparator for a Map.
private static class	CompositeEntity.LinkRecord A data structure for level-crossing links.

Field Summary

private java.util.List	_classDefinitionListCache Cache of class definition list.
private long	_classDefinitionListVersion Workspace version for cache.
(package private) NamedList	_containedEntities List of contained entities.
(package private) NamedList	_containedRelations
private java.util.List<DecoratedAttributes>	_decoratedAttributesToStoreAtThisLevel Decorated attributes within this composite for which this composite is responsible.
private static java.lang.String	_defaultIcon The default value icon.
private java.util.List	_entityListCache Cache of entity list.
private long	_entityListVersion Workspace version for cache.
private boolean	_levelCrossingConnectAllowed
protected java.util.List<CompositeEntity.LinkRecord>	_levelCrossingLinks Level-crossing links within this composite for which this composite is responsible.

Fields inherited from class ptolemy.kernel.Entity

_portList

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

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

CompositeEntity(CompositeEntity container, java.lang.String name)
Create an object with a name and a container.

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

Method Summary

private static <T> void	_addAll(java.util.Set<T> result, java.util.Collection<?> sourceList) Add all elements from the sourceList into the targetList.
protected void	_addEntity(ComponentEntity entity) Add an entity or class definition to this container.
private void	_addIcon() Add a default icon description.
protected void	_addRelation(ComponentRelation relation) Add a relation to this container.
protected void	_adjustDeferrals() Adjust the deferrals in this object.
private NamedObj	_commonContainer(NamedObj object1, NamedObj object2) Find the least common container of the two objects.
private boolean	_commonImplier(NamedObj object1, int depth1, NamedObj object2, int depth2) Return true if the two specified objects are both derived, it is the same container above them whose parent-child relationship makes them derived, or if one of the containers contains the other, and those containers are no more than depth1 and depth2 above them, respectively.
protected void	_deepOpaqueEntityList(java.util.List result) List the opaque entities that are directly or indirectly contained by this entity.
private int	_depthInside(NamedObj containee) Return the depth of specified object inside this.
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, ports, contained relations, and contained entities, plus all links.
protected void	_finishedAddEntity(ComponentEntity entity) Notify this entity that the given entity has been added inside it.
protected void	_recordDecoratedAttributes(DecoratedAttributes attributes) Record decorated attributes to store at the level of the container of the decorator.
private void	_recordLevelCrossingLink(Port port, Relation relation1, Relation relation2, int index) Record a level-crossing link with the least common container if there is such a least common container and if that least common container is currently exporting MoML.
protected void	_removeEntity(ComponentEntity entity) Remove the specified entity.
protected void	_removeRelation(ComponentRelation relation) Remove the specified relation.
private void	_unlinkLevelCrossingLinksToOutside(CompositeEntity entity) Remove all level-crossing links from relations contained by the specified entity to ports or relations outside this composite entity, and from ports contained by entities contained by the specified entity to relations outside this composite entity.
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.util.List	allAtomicEntityList() Return a list that consists of all the atomic entities in a model.
java.util.List	allCompositeEntityList() Return a list that consists of all the non-opaque composite entities in a model.
void	allowLevelCrossingConnect(boolean boole) Allow or disallow connections that are created using the connect() method to cross levels of the hierarchy.
java.util.List	classDefinitionList() List the contained class definitions in the order they were added (using their setContainer() method).
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
ComponentRelation	connect(ComponentPort port1, ComponentPort port2) Create a new relation and use it to connect two ports.
ComponentRelation	connect(ComponentPort port1, ComponentPort port2, java.lang.String relationName) Create a new relation with the specified name and use it to connect two ports.
java.util.Iterator	containedObjectsIterator() Return an iterator over contained objects.
java.util.List	deepEntityList() List the opaque entities that are directly or indirectly contained by this entity.
java.util.Enumeration	deepGetEntities() Deprecated. Use deepEntityList() instead.
java.util.List	deepOpaqueEntityList() List the opaque entities that are directly or indirectly contained by this entity.
java.util.Set<ComponentRelation>	deepRelationSet() Return a set with the relations that are directly or indirectly contained by this entity.
java.util.List	entityList() List the contained entities in the order they were added (using their setContainer() method).
java.util.List	entityList(java.lang.Class filter) Return a list of the component entities contained by this object that are instances of the specified Java class.
java.lang.String	exportLinks(int depth, java.util.Collection filter) Return a sequence of MoML link attributes that describe any link between objects (ports, entities, and relations) that are present in the filter argument.
void	exportMoML(java.io.Writer output, int depth, java.lang.String name) Override the base class to initialize a data structure that can capture and then export level-crossing links deeply contained structure within.
Attribute	getAttribute(java.lang.String name) Get the attribute with the given name.
java.util.Enumeration	getEntities() Deprecated. Use entityList() instead.
ComponentEntity	getEntity(java.lang.String name) Get a contained entity by name.
Port	getPort(java.lang.String name) Get a contained port by name.
ComponentRelation	getRelation(java.lang.String name) Get a contained relation by name.
java.util.Enumeration	getRelations() Deprecated. Use relationList() instead.
boolean	isAtomic() Return false since CompositeEntities are not atomic.
boolean	isOpaque() Return false.
java.util.List	lazyAllAtomicEntityList() Lazy version of allAtomicEntityList().
java.util.List	lazyAllCompositeEntityList() Lazy version of {#link #allCompositeEntityList()}.
java.util.List	lazyClassDefinitionList() Lazy version of classDefinitionList().
java.util.List	lazyDeepEntityList() Lazy version of deepEntityList().
java.util.List	lazyEntityList() Lazy version of entityList().
java.util.List	lazyRelationList() Lazy version of relationList().
ComponentRelation	newRelation(java.lang.String name) Create a new relation with the specified name, add it to the relation list, and return it.
int	numberOfEntities() Return the number of contained entities, not including class definitions.
int	numberOfRelations() Return the number of contained relations.
int	numEntities() Deprecated. Use numberOfEntities
int	numRelations() Deprecated. Use numberOfRelations.
java.util.List	relationList() List the relations contained by this entity.
void	removeAllEntities() Remove all contained entities and unlink them from all relations.
void	removeAllRelations() Remove all contained relations and unlink them from everything.
void	setClassDefinition(boolean isClass) Specify whether this object is a class definition.
void	setContainer(CompositeEntity container) Override the base class so that if the argument is null, all level-crossing links from inside this composite to outside this composite are removed.
java.lang.String	statistics(java.lang.String className) Return a string describing how many actors, parameters, ports, and relations are in this CompositeEntity.
java.lang.String	uniqueName(java.lang.String prefix) Return a name that is guaranteed to not be the name of any contained attribute, port, class, entity, or relation.

Methods inherited from class ptolemy.kernel.ComponentEntity

_addPort, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, newPort, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_removePort, connectedPortList, connectedPorts, connectionsChanged, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

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

Methods inherited from class ptolemy.kernel.util.NamedObj

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

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getDisplayName, getFullName, getName, getName

Field Detail

_levelCrossingLinks

protected java.util.List<CompositeEntity.LinkRecord> _levelCrossingLinks

Level-crossing links within this composite for which this composite is responsible. This data structure is populated when exportMoML() is called.

_containedEntities

NamedList _containedEntities

List of contained entities.

_containedRelations

NamedList _containedRelations

_classDefinitionListCache

private transient java.util.List _classDefinitionListCache

Cache of class definition list.

_classDefinitionListVersion

private transient long _classDefinitionListVersion

Workspace version for cache.

_decoratedAttributesToStoreAtThisLevel

private java.util.List<DecoratedAttributes> _decoratedAttributesToStoreAtThisLevel

Decorated attributes within this composite for which this composite is responsible. This data structure is populated when exportMoML() is called.

_defaultIcon

private static java.lang.String _defaultIcon

The default value icon. This is static so that we avoid doing string concatenation each time we construct this object.

_entityListCache

private transient java.util.List _entityListCache

Cache of entity list.

_entityListVersion

private transient long _entityListVersion

Workspace version for cache.

_levelCrossingConnectAllowed

private boolean _levelCrossingConnectAllowed

Constructor Detail

CompositeEntity

public CompositeEntity()

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

CompositeEntity

public CompositeEntity(Workspace workspace)

Construct an entity 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 entity to the workspace directory. Increment the version number of the workspace.

Parameters:

workspace - The workspace that will list the entity.

CompositeEntity

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

Create an object with a name and a container. The container argument must not be null, or a NullPointerException will be thrown. This entity 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. Increment the version of the workspace.

Parameters:

container - The container entity.

name - The name of the entity.

Throws:

IllegalActionException - If the container is incompatible with this entity.

NameDuplicationException - If the name coincides with an entity already in the container.

Method Detail

allAtomicEntityList

public java.util.List allAtomicEntityList()

Return a list that consists of all the atomic entities in a model. This method differs from deepEntityList() in that this method looks inside opaque entities, whereas deepEntityList() does not. The returned list does not include any entities that are class definitions.

Returns:

a List of all atomic entities in the model.

allCompositeEntityList

public java.util.List allCompositeEntityList()

Return a list that consists of all the non-opaque composite entities in a model. This method differs from allAtomicEntityList() in that this method returns CompositeEntities and allAtomicEntityList() returns atomic entities. This method differs from deepEntityList() in that this method returns only CompositeEntities, whereas deepEntityList() returns ComponentEntities. The returned list of this method does not include any entities that are class definitions.

Returns:

a List of all Composite entities in the model.

allowLevelCrossingConnect

public void allowLevelCrossingConnect(boolean boole)

Allow or disallow connections that are created using the connect() method to cross levels of the hierarchy. The default is that such connections are disallowed. Generally it is a bad idea to allow level-crossing connections, since it breaks modularity. This loss of modularity means, among other things, that this composite cannot be cloned. Nonetheless, this capability is provided for the benefit of users that feel they just must have it, and who are willing to sacrifice clonability and modularity.

Parameters:

boole - True to allow level-crossing connections.

classDefinitionList

public java.util.List classDefinitionList()

List the contained class definitions in the order they were added (using their setContainer() method). The returned list does not include any entities that are not class definitions. The returned list is static in the sense that it is not affected by any subsequent additions or removals of class definitions. This method is read-synchronized on the workspace.

Returns:

A list of ComponentEntity objects.

See Also:

entityList()

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). This method gets read access on the workspace associated with this object.

Overrides:

clone in class ComponentEntity

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new CompositeEntity.

Throws:

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

See Also:

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

connect

public ComponentRelation connect(ComponentPort port1,
                                 ComponentPort port2)
                          throws IllegalActionException

Create a new relation and use it to connect two ports. It creates a new relation using newRelation() with an automatically generated name and uses it to link the specified ports. The order of the ports determines the order in which the links to the relation are established, but otherwise has no importance. The name is of the form "_Ri" where i is an integer. Level-crossing connections are not permitted unless allowLevelCrossingConnect() has been called with a true argument. Note that is rarely a good idea to permit level crossing connections, since they break modularity and cloning. A reference to the newly created relation is returned. To remove the relation, call its setContainer() method with a null argument. This method is write-synchronized on the workspace and increments its version number.

Note that if this method is being called many times, then it may be more efficient to use connect(ComponentPort, ComponentPort, String) instead of this method because this method calls uniqueName(String) each time, which searches the object for attributes, ports, entities and relations that may match a candidate unique name.

Parameters:

port1 - The first port to connect.

port2 - The second port to connect.

Returns:

The ComponentRelation that is created to connect port1 and port2.

Throws:

IllegalActionException - If one of the arguments is null, or if a disallowed level-crossing connection would result.

connect

public ComponentRelation connect(ComponentPort port1,
                                 ComponentPort port2,
                                 java.lang.String relationName)
                          throws IllegalActionException,
                                 NameDuplicationException

Create a new relation with the specified name and use it to connect two ports. Level-crossing connections are not permitted unless allowLevelCrossingConnect() has been called with a true argument. Note that is rarely a good idea to permit level crossing connections, since they break modularity and cloning. A reference to the newly created alias relation is returned. To remove the relation, call its setContainer() method with a null argument. This method is write-synchronized on the workspace and increments its version number.

Parameters:

port1 - The first port to connect.

port2 - The second port to connect.

relationName - The name of the new relation.

Returns:

The ComponentRelation that is created to connect port1 and port2.

Throws:

IllegalActionException - If one of the arguments is null, or if a disallowed level-crossing connection would result, or if the two ports are not in the same workspace as this entity.

NameDuplicationException - If there is already a relation with the specified name in this entity.

containedObjectsIterator

public java.util.Iterator containedObjectsIterator()

Return an iterator over contained objects. In this class, this is an iterator over attributes, ports, classes, entities, and relations.

Overrides:

containedObjectsIterator in class Entity

Returns:

An iterator over instances of NamedObj contained by this object.

deepOpaqueEntityList

public java.util.List deepOpaqueEntityList()

List the opaque entities that are directly or indirectly contained by this entity. The list will be empty if there are no such contained entities. This list does not include class definitions nor anything contained by them. This method is read-synchronized on the workspace.

Returns:

A list of opaque ComponentEntity objects.

See Also:

classDefinitionList(), allAtomicEntityList()

deepEntityList

public java.util.List deepEntityList()

List the opaque entities that are directly or indirectly contained by this entity. The list will be empty if there are no such contained entities. This list does not include class definitions nor anything contained by them. This method is read-synchronized on the workspace.

Returns:

A list of opaque ComponentEntity objects.

See Also:

classDefinitionList(), allAtomicEntityList()

deepRelationSet

public java.util.Set<ComponentRelation> deepRelationSet()

Return a set with the relations that are directly or indirectly contained by this entity. The set will be empty if there are no such contained relations. This method is read-synchronized on the workspace.

Returns:

A set of ComponentRelation objects.

deepGetEntities

public java.util.Enumeration deepGetEntities()

Deprecated. Use deepEntityList() instead.

Enumerate the opaque entities that are directly or indirectly contained by this entity. The enumeration will be empty if there are no such contained entities. The enumeration does not include any entities that are class definitions. This method is read-synchronized on the workspace.

Returns:

An enumeration of opaque ComponentEntity objects.

entityList

public java.util.List entityList()

List the contained entities in the order they were added (using their setContainer() method). The returned list does not include any class definitions. The returned list is static in the sense that it is not affected by any subsequent additions or removals of entities. This method is read-synchronized on the workspace.

Returns:

A list of ComponentEntity objects.

See Also:

classDefinitionList()

entityList

public java.util.List entityList(java.lang.Class filter)

Return a list of the component entities contained by this object that are instances of the specified Java class. If there are no such instances, then return an empty list. The returned list does not include class definitions. This method is read-synchronized on the workspace.

Parameters:

filter - The class of ComponentEntity of interest.

Returns:

A list of instances of specified class.

See Also:

classDefinitionList()

exportLinks

public java.lang.String exportLinks(int depth,
                                    java.util.Collection filter)
                             throws java.io.IOException

Return a sequence of MoML link attributes that describe any link between objects (ports, entities, and relations) that are present in the filter argument. Both ends of the link must be present in filter for MoML to be generated for that link. The filter argument normally contains ports, relations, and entities that are contained by this composite entity. If it contains an entity, then that is equivalent to containing all the ports contained by that entity. It is recommended to use a collection class (such as HashSet) for which the contains() method is efficient.

If the filter argument is null, then return all the links that this composite is responsible for (i.e., apply no filtering). If the argument is an empty collection, then return none of the links. The links that this entity is responsible for are the inside links of its ports, and links on ports contained by contained entities.

If any link is found where both ends of the link are inherited objects, then that link is not exported. It is assumed that the base class will export that link. For this purpose, a port of a contained entity is deemed to be an inherited object if it is itself a class element and its container is an inherited object.

Parameters:

depth - The depth below the MoML export in the hierarchy.

filter - A collection of ports, parameters, and entities, or null to apply no filtering.

Returns:

A string that describes the links present in the filter.

Throws:

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

exportMoML

public void exportMoML(java.io.Writer output,
                       int depth,
                       java.lang.String name)
                throws java.io.IOException

Override the base class to initialize a data structure that can capture and then export level-crossing links deeply contained structure within. Otherwise, this delegates to the base class to do all the work.

Specified by:

exportMoML in interface MoMLExportable

Overrides:

exportMoML in class InstantiableNamedObj

Parameters:

output - The output stream to write to.

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

name - The name to use in the exported MoML.

Throws:

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

See Also:

MoMLExportable

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 contained by a (deeply) contained attribute, port, relation, or entity. If the name contains one or more periods, then it is assumed to be the relative name of an attribute contained by one of the contained attributes, ports, entities or relations. This method is read-synchronized on the workspace.

Overrides:

getAttribute in class Entity

Parameters:

name - The name of the desired attribute.

Returns:

The requested attribute if it is found, null otherwise.

getEntities

public java.util.Enumeration getEntities()

Deprecated. Use entityList() instead.

Enumerate the contained entities in the order they were added (using their setContainer() method). The returned enumeration is static in the sense that it is not affected by any subsequent additions or removals of entities. This method is read-synchronized on the workspace.

Returns:

An enumeration of ComponentEntity objects.

getEntity

public ComponentEntity getEntity(java.lang.String name)

Get a contained entity by name. The name may be compound, with fields separated by periods, in which case the entity returned is contained by a (deeply) contained entity. This method will return class definitions and ordinary entities. This method is read-synchronized on the workspace.

Parameters:

name - The name of the desired entity.

Returns:

An entity with the specified name, or null if none exists.

getPort

public Port getPort(java.lang.String name)

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

Overrides:

getPort in class Entity

Parameters:

name - The name of the desired port.

Returns:

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

getRelation

public ComponentRelation getRelation(java.lang.String name)

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

Parameters:

name - The name of the desired relation.

Returns:

A relation with the specified name, or null if none exists.

getRelations

public java.util.Enumeration getRelations()

Deprecated. Use relationList() instead.

Enumerate the relations contained by this entity. The returned enumeration is static in the sense that it is not affected by any subsequent additions or removals of relations. This method is read-synchronized on the workspace.

Returns:

An enumeration of ComponentRelation objects.

isAtomic

public final boolean isAtomic()

Return false since CompositeEntities are not atomic. Note that this will return false even if there are no contained entities or relations. Derived classes may not override this. To hide the contents of the entity, they should override isOpaque().

Overrides:

isAtomic in class ComponentEntity

Returns:

False.

See Also:

CompositeEntity

isOpaque

public boolean isOpaque()

Return false. Derived classes may return true in order to hide their components behind opaque ports.

Overrides:

isOpaque in class ComponentEntity

Returns:

True if the entity is opaque.

See Also:

CompositeEntity

lazyAllAtomicEntityList

public java.util.List lazyAllAtomicEntityList()

Lazy version of allAtomicEntityList(). In this base class, this is identical to allAtomicEntityList(), except that if any inside entities are lazy, their contents are listed lazily. Derived classes may omit from the returned list any entities whose instantiation is deferred.

Returns:

A list of ComponentEntity objects.

lazyAllCompositeEntityList

public java.util.List lazyAllCompositeEntityList()

Lazy version of {#link #allCompositeEntityList()}. In this base class, this is identical to allCompositeEntityList(), except that if any contained composite is lazy, its contents are listed lazily. Derived classes may omit from the returned list any class definitions whose instantiation is deferred.

Returns:

A list of ComponentEntity objects.

lazyClassDefinitionList

public java.util.List lazyClassDefinitionList()

Lazy version of classDefinitionList(). In this base class, this is identical to classDefinitionList(), but derived classes may omit from the returned list any class definitions whose instantiation is deferred.

Returns:

A list of ComponentEntity objects.

lazyDeepEntityList

public java.util.List lazyDeepEntityList()

Lazy version of deepEntityList(). In this base class, this is identical to deepEntityList(), except that if any contained composite is lazy, its contents are listed lazily. Derived classes may omit from the returned list any entities whose instantiation is deferred.

Returns:

A list of ComponentEntity objects.

lazyEntityList

public java.util.List lazyEntityList()

Lazy version of entityList(). In this base class, this is identical to entityList(), but derived classes may omit from the returned list any entities whose instantiation is deferred.

Returns:

A list of ComponentEntity objects.

lazyRelationList

public java.util.List lazyRelationList()

Lazy version of relationList(). In this base class, this is identical to relationList(), but derived classes may omit from the returned list any relations whose instantiation is deferred.

Returns:

A list of Relation objects.

newRelation

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

Create a new relation with the specified name, add it to the relation list, and return it. Derived classes can override this to create domain-specific subclasses of ComponentRelation. This method is write-synchronized on the workspace and increments its version number.

Parameters:

name - The name of the new relation.

Returns:

The new relation.

Throws:

IllegalActionException - If name argument is null.

NameDuplicationException - If name collides with a name already in the container.

numEntities

public int numEntities()

Deprecated. Use numberOfEntities

Return the number of contained entities, not including class definitions. This method is read-synchronized on the workspace.

Returns:

The number of entities.

See Also:

numberOfEntities()

numRelations

public int numRelations()

Deprecated. Use numberOfRelations.

Return the number of contained relations. This method is read-synchronized on the workspace.

Returns:

The number of relations.

numberOfEntities

public int numberOfEntities()

Return the number of contained entities, not including class definitions. This method is read-synchronized on the workspace.

Returns:

The number of entities.

numberOfRelations

public int numberOfRelations()

Return the number of contained relations. This method is read-synchronized on the workspace.

Returns:

The number of relations.

relationList

public java.util.List relationList()

List the relations contained by this entity. The returned list is static in the sense that it is not affected by any subsequent additions or removals of relations. This method is read-synchronized on the workspace.

Returns:

An unmodifiable list of ComponentRelation objects.

removeAllEntities

public void removeAllEntities()

Remove all contained entities and unlink them from all relations. This is done by setting their containers to null. This method is read-synchronized on the workspace and increments its version number.

removeAllRelations

public void removeAllRelations()

Remove all contained relations and unlink them from everything. This is done by setting their containers to null. 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. If the argument is true and this entity is not a class definition, then all level crossing relations that 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 Entity

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

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class so that if the argument is null, all level-crossing links from inside this composite to outside this composite are removed.

Overrides:

setContainer in class ComponentEntity

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace, or if the protected method _checkContainer() throws it, or if a contained Settable becomes invalid and the error handler throws it.

NameDuplicationException - If the name of this entity collides with a name already in the container.

See Also:

ComponentEntity.getContainer()

statistics

public java.lang.String statistics(java.lang.String className)
                            throws IllegalActionException

Return a string describing how many actors, parameters, ports, and relations are in this CompositeEntity. Entities whose instantiation is deferred are not included.

Parameters:

className - If non-null and non-empty, then also include the number of objects with the give name.

Returns:

a string describing the number of components.

Throws:

IllegalActionException - If the class named by actorClassName cannot be found.

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, port, class, entity, or relation. 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, port, class, entity, or relation. If this composite entity or any composite entity that it contains defers its MoML definition (i.e., it is an instance of a class or a subclass), then the prefix gets appended with "_n_", where n is the depth of this deferral. That is, if the object deferred to also defers, then n is incremented.

Note that this method should be called judiciously from when the CompositeEntity is large. The reason is that this method searches for matching attributes, ports, classes, entities and relations, which can result in slow performance.

Overrides:

uniqueName in class Entity

Parameters:

prefix - A prefix for the name.

Returns:

A unique name.

_addEntity

protected void _addEntity(ComponentEntity entity)
                   throws IllegalActionException,
                          NameDuplicationException

Add an entity or class definition to this container. This method should not be used directly. Call the setContainer() method of the entity instead. This method does not set the container of the entity to point to this composite entity. It assumes that the entity is in the same workspace as this container, but does not check. The caller should check. Derived classes may override this method to constrain the the entity to a subclass of ComponentEntity. This method is not synchronized on the workspace, so the caller should be.

Parameters:

entity - Entity to contain.

Throws:

IllegalActionException - If the entity has no name, or the action would result in a recursive containment structure.

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

_addRelation

protected void _addRelation(ComponentRelation relation)
                     throws IllegalActionException,
                            NameDuplicationException

Add a relation to this container. This method should not be used directly. Call the setContainer() method of the relation instead. This method does not set the container of the relation to refer to this container. This method is not synchronized on the workspace, so the caller should be.

Parameters:

relation - Relation to contain.

Throws:

IllegalActionException - If the relation has no name.

NameDuplicationException - If the name collides with a name already on the contained relations list.

_adjustDeferrals

protected void _adjustDeferrals()
                         throws IllegalActionException

Adjust the deferrals in this object. This method should be called on any newly created object that is created by cloning. While cloning, parent relations are set to null. That is, no object in the clone has a parent. This method identifies the correct parent for any object in the clone. To do this, it uses the class name. Specifically, if this object has a class name that refers to a class in scope, then it replaces the current parent with that object. To look for a class in scope, we go up the hierarchy, but no more times than the return value of getDerivedLevel(). The reason for this is that if the class from which this object is defined is above that level, then we do not want to establish a parent relationship with that class. This object is implied, and the parent relationship of the object from which it is implied is sufficient.

Derived classes that contain other objects should recursively call this method on contained objects.

Overrides:

_adjustDeferrals in class ComponentEntity

Throws:

IllegalActionException - If the class found in scope cannot be set.

_deepOpaqueEntityList

protected void _deepOpaqueEntityList(java.util.List result)

List the opaque entities that are directly or indirectly contained by this entity. The list will be empty if there are no such contained entities. This list does not include class definitions nor anything contained by them. This method is not read-synchronized on the workspace, its caller should be read-synchronized.

Parameters:

result - The list of opaque ComponentEntity objects.

See Also:

classDefinitionList(), allAtomicEntityList(), deepEntityList()

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

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, ports, contained relations, and contained entities, plus all links. The links are written in an order that respects the ordering in ports, but not necessarily the ordering in relations. 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 Entity

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)

_finishedAddEntity

protected void _finishedAddEntity(ComponentEntity entity)

Notify this entity that the given entity has been added inside it. This base class does nothing. Derived classes may override it to do something useful in responds to the notification. It is not synchronized on the workspace, so the caller should be.

Parameters:

entity - The contained entity.

_recordDecoratedAttributes

protected void _recordDecoratedAttributes(DecoratedAttributes attributes)

Record decorated attributes to store at the level of the container of the decorator.

Overrides:

_recordDecoratedAttributes in class NamedObj

Parameters:

attributes - The decorated attributes.

_removeEntity

protected void _removeEntity(ComponentEntity entity)

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

Parameters:

entity - The entity to remove.

_removeRelation

protected void _removeRelation(ComponentRelation relation)

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

Parameters:

relation - The relation to remove.

_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 entities and relations. Errors that are triggered by this validation are handled by calling handleModelError().

Overrides:

_validateSettables in class Entity

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, IllegalActionException)

_addAll

private static <T> void _addAll(java.util.Set<T> result,
                                java.util.Collection<?> sourceList)

Add all elements from the sourceList into the targetList.

_addIcon

private void _addIcon()

Add a default icon description.

_commonContainer

private NamedObj _commonContainer(NamedObj object1,
                                  NamedObj object2)

Find the least common container of the two objects.

Parameters:

object1 - The first object.

object2 - The second object.

Returns:

The least common container, or null if there isn't one.

_commonImplier

private boolean _commonImplier(NamedObj object1,
                               int depth1,
                               NamedObj object2,
                               int depth2)

Return true if the two specified objects are both derived, it is the same container above them whose parent-child relationship makes them derived, or if one of the containers contains the other, and those containers are no more than depth1 and depth2 above them, respectively.

Parameters:

object1 - The first object.

depth1 - The depth of the first object.

object2 - The second object.

depth2 - The depth of the second object.

Returns:

True if the two specified objects are both derived at a common level no more than depth above them.

_depthInside

private int _depthInside(NamedObj containee)

Return the depth of specified object inside this. That is, return 0 if the specified object is this, 1 if this contains it, 2 if this contains the container of it, etc.

Parameters:

containee - The object contained.

Returns:

The depth of the containment, or -1 if the specified object is not deeply contained by this.

_recordLevelCrossingLink

private void _recordLevelCrossingLink(Port port,
                                      Relation relation1,
                                      Relation relation2,
                                      int index)

Record a level-crossing link with the least common container if there is such a least common container and if that least common container is currently exporting MoML. Otherwise, do nothing.

Parameters:

port - The port, or null for a link between relations.

relation1 - The first relation.

relation2 - The second relation.

index - The index of the link.

_unlinkLevelCrossingLinksToOutside

private void _unlinkLevelCrossingLinksToOutside(CompositeEntity entity)

Remove all level-crossing links from relations contained by the specified entity to ports or relations outside this composite entity, and from ports contained by entities contained by the specified entity to relations outside this composite entity.

Parameters:

entity - The entity in which to look for relations or (if it is an instance of CompositeEntity), entities with ports.