ptolemy.kernel
Class ComponentEntity

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

All Implemented Interfaces:

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

Direct Known Subclasses:

AtomicActor, CompositeEntity, State, State

public class ComponentEntity
extends Entity

A ComponentEntity is a component in a CompositeEntity. It might itself be composite, but in this base class it is assumed to be atomic (meaning that it cannot contain components).

Derived classes may further constrain the container to be a subclass of CompositeEntity. To do this, they should override the protected method _checkContainer() to throw an exception.

A ComponentEntity can contain instances of ComponentPort. Derived classes may further constrain 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:

Ptolemy II 0.2

Version:

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

Author:

John S. Davis II, Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Green (cxh)

Proposed Rating:

Green (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

private CompositeEntity	_container The container.
private static java.lang.String	_defaultIcon The default value icon.

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

ComponentEntity()
Construct an entity in the default workspace with an empty string The object is added to the workspace directory.

ComponentEntity(CompositeEntity container, java.lang.String name)
Construct an entity with the given name contained by the specified entity.

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

Method Summary

private void	_addIcon() Define the icon.
protected void	_addPort(Port port) Add a port to this entity.
protected void	_adjustDeferrals() Adjust the deferrals in this object.
protected void	_checkContainer(InstantiableNamedObj container) Check the specified container.
protected NamedObj	_getContainedObject(NamedObj container, java.lang.String relativeName) Get an entity with the specified name in the specified container.
protected NamedObj	_propagateExistence(NamedObj container) Propagate existence of this object to the specified object.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
NamedObj	getContainer() Get the container entity.
Instantiable	instantiate(NamedObj container, java.lang.String name) Create an instance by cloning this object and then adjusting the parent-child relationships between the clone and its parent.
boolean	isAtomic() Return true if the entity is atomic.
boolean	isOpaque() Return true if the entity is opaque.
int	moveDown() Move this object down by one in the list of entities of its container.
int	moveToFirst() Move this object to the first position in the list of entities of the container.
int	moveToIndex(int index) Move this object to the specified position in the list of entities of the container.
int	moveToLast() Move this object to the last position in the list of entities of the container.
int	moveUp() Move this object up by one in the list of entities of the container.
Port	newPort(java.lang.String name) Create a new port with the specified name.
java.util.List	propagateExistence() Propagate the existence of this object.
void	setContainer(CompositeEntity container) Specify the container, adding the entity to the list of entities in the container.
void	setName(java.lang.String name) Set the name of the ComponentEntity.

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, connectionsChanged, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, 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, _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, 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

_container

private CompositeEntity _container

The container.

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

Constructor Detail

ComponentEntity

public ComponentEntity()

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

ComponentEntity

public ComponentEntity(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. The object is added to the workspace directory. Increment the version number of the workspace.

Parameters:

workspace - The workspace that will list the entity.

ComponentEntity

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

Construct an entity with the given name contained by the specified entity. 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. This constructor write-synchronizes on the workspace.

Parameters:

container - The container entity.

name - The name of the entity.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

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

Method Detail

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new component entity that defers its definition to the same object as this one (or to none) that has no container.

Overrides:

clone in class Entity

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new instance of ComponentEntity.

Throws:

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

See Also:

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

getContainer

public NamedObj getContainer()

Get the container entity.

Specified by:

getContainer in interface Nameable

Overrides:

getContainer in class NamedObj

Returns:

The container, which is an instance of CompositeEntity.

See Also:

setContainer(CompositeEntity)

instantiate

public Instantiable instantiate(NamedObj container,
                                java.lang.String name)
                         throws java.lang.CloneNotSupportedException,
                                IllegalActionException,
                                NameDuplicationException

Create an instance by cloning this object and then adjusting the parent-child relationships between the clone and its parent. Specifically, the clone defers its definition to this object, which becomes its "parent." It inherits all the objects contained by this object. If this object is a composite, then this method adjusts any deferral relationships that are entirely contained within the clone. That is, for any parent-child relationship that is entirely contained within this object (i.e., both the parent and the child are deeply contained by this object), a corresponding parent-child relationship is created within the clone such that both the parent and the child are entirely contained within the clone.

The new object is not a class definition (it is by default an "instance" rather than a "class"). To make it a class definition (a "subclass"), call setClassDefinition(true).

This method overrides the base class to use setContainer() to specify the container.

Specified by:

instantiate in interface Instantiable

Overrides:

instantiate in class InstantiableNamedObj

Parameters:

container - The container for the instance, or null to instantiate it at the top level.

name - The name for the clone.

Returns:

A new instance that is a clone of this object with adjusted deferral relationships.

Throws:

java.lang.CloneNotSupportedException - If this object cannot be cloned.

IllegalActionException - If this object is not a class definition or the proposed container is not acceptable.

NameDuplicationException - If the name collides with an object already in the container.

See Also:

Entity.setClassDefinition(boolean)

isAtomic

public boolean isAtomic()

Return true if the entity is atomic. An atomic entity is one that cannot have components. Instances of this base class are always atomic. Derived classes that return false are assumed to be instances of CompositeEntity or a class derived from that.

Returns:

True if the entity is atomic.

See Also:

CompositeEntity

isOpaque

public boolean isOpaque()

Return true if the entity is opaque. An opaque entity is one that either is atomic or hides its components behind opaque ports. Instances of this base class are always opaque. Derived classes may be transparent, in which case they return false to this method and to isAtomic().

Returns:

True if the entity is opaque.

See Also:

CompositeEntity

moveDown

public int moveDown()
             throws IllegalActionException

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

Specified by:

moveDown in interface Moveable

Overrides:

moveDown in class NamedObj

Returns:

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

Throws:

IllegalActionException - If this object has no container.

moveToFirst

public int moveToFirst()
                throws IllegalActionException

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

Specified by:

moveToFirst in interface Moveable

Overrides:

moveToFirst in class NamedObj

Returns:

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

Throws:

IllegalActionException - If this object has no container.

moveToIndex

public int moveToIndex(int index)
                throws IllegalActionException

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

Specified by:

moveToIndex in interface Moveable

Overrides:

moveToIndex in class NamedObj

Parameters:

index - The position to move this object to.

Returns:

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

Throws:

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

moveToLast

public int moveToLast()
               throws IllegalActionException

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

Specified by:

moveToLast in interface Moveable

Overrides:

moveToLast in class NamedObj

Returns:

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

Throws:

IllegalActionException - If this object has no container.

moveUp

public int moveUp()
           throws IllegalActionException

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

Specified by:

moveUp in interface Moveable

Overrides:

moveUp in class NamedObj

Returns:

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

Throws:

IllegalActionException - If this object has no container.

newPort

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

Create a new port with the specified name. The container of the port is set to this entity. This overrides the base class to create an instance of ComponentPort. Derived classes may override this to further constrain the ports. This method is write-synchronized on the workspace and increments its version number.

Overrides:

newPort in class Entity

Parameters:

name - The new port name.

Returns:

The new port

Throws:

IllegalActionException - If the argument is null.

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

propagateExistence

public java.util.List propagateExistence()
                                  throws IllegalActionException

Propagate the existence of this object. If this object has a container, then ensure that all objects derived from the container contain an object with the same class and name as this one. Create that object when needed. Return the list of objects that are created. This overrides the base class to adjust deferrals within the objects that are created by cloning this one.

Specified by:

propagateExistence in interface Derivable

Overrides:

propagateExistence in class NamedObj

Returns:

A list of derived objects of the same class as this object that are created.

Throws:

IllegalActionException - If the object does not exists and cannot be created.

See Also:

Derivable, NamedObj.setDerivedLevel(int)

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Specify the container, adding the entity to the list of entities in the container. If the container already contains an entity with the same name, then throw an exception and do not make any changes. Similarly, if the container is not in the same workspace as this entity, throw an exception. If this entity is a class element and the proposed container does not match the current container, then also throw an exception. If the entity is already contained by the container, do nothing. If this entity already has a container, remove it from that container first. Otherwise, remove it from the directory of the workspace, if it is present. If the argument is null, then unlink the ports of the entity from any relations and remove it from its container. It is not added to the workspace directory, so this could result in this entity being garbage collected.

Note that for entities that are created by parsing MoML, it may be necessary to call MoMLParser.purgeModelRecord(). This is especially critical when the MoML file imports MoML classes. See Effigy.setContainer() for details.

Derived classes may further constrain the container to subclasses of CompositeEntity by overriding the protected method _checkContainer(). This method validates all deeply contained instances of Settable, since they may no longer be valid in the new context. This method is write-synchronized to the workspace and increments its version number.

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:

getContainer()

setName

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

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

Specified by:

setName in interface Nameable

Overrides:

setName in class NamedObj

Parameters:

name - The new name.

Throws:

IllegalActionException - If the name has a period.

NameDuplicationException - If there already is an entity in the container with the same name.

See Also:

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

_addPort

protected void _addPort(Port port)
                 throws IllegalActionException,
                        NameDuplicationException

Add a port to this entity. This overrides the base class to throw an exception if the added port is not an instance of ComponentPort. 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 may override this method to further constrain to a subclass of ComponentPort. This method is not synchronized on the workspace, so the caller should be.

Overrides:

_addPort in class Entity

Parameters:

port - The port to add to this entity.

Throws:

IllegalActionException - If the port class is not acceptable to this entity, or the port has no name.

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

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

Throws:

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

_checkContainer

protected void _checkContainer(InstantiableNamedObj container)
                        throws IllegalActionException

Check the specified container.

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the container is not an instance of CompositeEntity, or if the proposed container is null and there are other objects that defer their definitions to this one.

_getContainedObject

protected NamedObj _getContainedObject(NamedObj container,
                                       java.lang.String relativeName)
                                throws IllegalActionException

Get an entity with the specified name in the specified container. The returned object is assured of being an instance of the same class as this object.

Overrides:

_getContainedObject in class NamedObj

Parameters:

relativeName - The name relative to the container.

container - The container expected to contain the object, which must be an instance of CompositeEntity.

Returns:

An object of the same class as this object, or null if there is none.

Throws:

IllegalActionException - If the object exists and has the wrong class, or if the specified container is not an instance of CompositeEntity.

_propagateExistence

protected NamedObj _propagateExistence(NamedObj container)
                                throws IllegalActionException

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

Overrides:

_propagateExistence in class NamedObj

Parameters:

container - Object to contain the new object.

Returns:

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

Throws:

IllegalActionException - If the object cannot be cloned.

_addIcon

private void _addIcon()

Define the icon.