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.

CompositeEntity

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

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.

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.

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.

clone

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.

connect

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

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.

deepCompositeEntityList

Return a list that consists of all the transparent and 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 opaque and transparent
CompositeEntities, whereas deepEntityList() returns opaque
ComponentEntities. The returned list of this method does not
include any entities that are class definitions.
The entityList(Class) method only returns entities in the
current level, this method traverses the hierarchy.

Returns:

a List of all transparent and opaque composite entities in the
model. A transparent composite is a composite that does not
contain a director. An opaque composite is a composite that does
contain a director. Note that class definitions are also returned.

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.

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.

deepNamedObjList

public java.util.List deepNamedObjList()

List the NamedObjs that are directly or indirectly
contained by this entity. The list will be empty if there
are no such contained NamedObjs. This list does not include
class definitions nor anything contained by them.
This method is read-synchronized on the workspace.
This method differs from deepEntityList() in that deepEntityList()
does not look inside opaques.

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

@Deprecated
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.

entityList

public <T> java.util.List<T> entityList(java.lang.Class<T> 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.

exportLinks

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

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.

getAttribute

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.

getEntities

@Deprecated
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

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

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.

getRelation

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

@Deprecated
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().

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 transparent ComponentEntity objects.

lazyAllCompositeTransparentAndOpaqueEntityList

public java.util.List lazyAllCompositeTransparentAndOpaqueEntityList()

Return all the transparent and opaque composites.
In this base class, 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 transparent 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

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.

numRelations

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

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.

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.

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.

_addEntity

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.

_addRelation

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.

_adjustDeferrals

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.

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

_description

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.

_exportMoMLContents

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.

_finishedAddEntity

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.

_removeEntity

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

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

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().