ptolemy.kernel
Class InstantiableNamedObj

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

All Implemented Interfaces:

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

Direct Known Subclasses:

Entity

public class InstantiableNamedObj
extends NamedObj
implements Instantiable

An InstantiableNamedObj is a named object that can be either a class definition or an instance. If it is a class definition, then "instances" of that class definition can be created by the instantiate() method. Those instances are called the "children" of this "parent." Changes to the parent propagate automatically to the children as described in the Instantiable interface.

Note that the instantiate(NamedObj, String) permits instantiating an object into a workspace that is different from the one associated with this object. This means that some care must be exercised when propagating changes from a parent to a child, since they may be in different workspaces. Suppose for example that the change that has to propagate is made via a change request. Although it may be a safe time to execute a change request in the parent, it is not necessarily a safe time to execute a change request in the child. Classes that restrict these safe times should override the propagateExistence(), propagateValue(), and propagateValues() methods to ensure that the destinations of the propagation are in a state that they can accept changes.

Since:

Ptolemy II 4.0

Version:

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

Author:

Edward A. Lee

See Also:

Instantiable, Serialized Form

Accepted Rating:

Green (neuendor)

Proposed Rating:

Green (eal)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

private java.util.List	_children List of weak references to children for which this object is the parent.
private boolean	_isClassDefinition Indicator of whether this is a class definition.
private InstantiableNamedObj	_parent Parent to which this object defers its definition to, or null if there is none.

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

InstantiableNamedObj()
Construct an object in the default workspace with an empty string as its name.

InstantiableNamedObj(java.lang.String name)
Construct an object in the default workspace with the given name.

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

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

Method Summary

protected void	_setParent(Instantiable parent) Specify the parent for this object.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
void	exportMoML(java.io.Writer output, int depth, java.lang.String name) Write a MoML description of this object with the specified indentation depth and with the specified name substituting for the name of this object.
java.util.List	getChildren() Get a list of weak references to instances of Instantiable that are children of this object.
java.lang.String	getElementName() Get the MoML element name.
Instantiable	getParent() Return the parent of this object, or null if there is none.
java.util.List	getPrototypeList() Return a list of prototypes for this object.
Instantiable	instantiate(NamedObj container, java.lang.String name) Create an instance by (deeply) cloning this object and then adjusting the parent-child relationships between the clone and its parent.
boolean	isClassDefinition() Return true if this object is a class definition, which means that it can be instantiated.
boolean	isWithinClassDefinition() Return true if this object is a class definition or is within a class definition, which means that any container above it in the hierarchy is a class definition.
void	setClassDefinition(boolean isClass) Specify whether this object is a class definition.

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getContainedObject, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateExistence, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getContainer, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setName, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateExistence, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

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

Field Detail

_children

private java.util.List _children

List of weak references to children for which this object is the parent.

_parent

private InstantiableNamedObj _parent

Parent to which this object defers its definition to, or null if there is none.

_isClassDefinition

private boolean _isClassDefinition

Indicator of whether this is a class definition.

Constructor Detail

InstantiableNamedObj

public InstantiableNamedObj()

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

InstantiableNamedObj

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

Construct an object in the default workspace with the given name. If the name argument is null, then the name is set to the empty string. The object is added to the workspace directory. Increment the version number of the workspace.

Parameters:

name - The name of this object.

Throws:

IllegalActionException - If the name has a period.

InstantiableNamedObj

public InstantiableNamedObj(Workspace workspace)

Construct an object in the given workspace with an empty string as a name. If the workspace argument is null, use the default workspace. The object is added to the workspace directory. Increment the version of the workspace.

Parameters:

workspace - The workspace for synchronization and version tracking.

InstantiableNamedObj

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

Construct an object in the given workspace with the given name. If the workspace argument is null, use the default workspace. If the name argument is null, then the name is set to the empty string. The object is added to the workspace directory. Increment the version of the workspace.

Parameters:

workspace - The workspace for synchronization and version tracking.

name - The name of this object.

Throws:

IllegalActionException - If the name has a period.

Method Detail

clone

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

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new instance of InstantiableNamedObj that is a child of the parent of this object, if this object has a parent. The new instance has no children. This method gets read access on the workspace associated with this object.

Overrides:

clone in class NamedObj

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new instance of InstantiableNamedObj.

Throws:

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

See Also:

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

exportMoML

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

Write a MoML description of this object with the specified indentation depth and with the specified name substituting for the name of this object. The description has one of two forms, depending on whether this is a class definition. If it is, then the exported MoML looks like this:

      <class name="name" extends="classname source="source">
          body, determined by _exportMoMLContents()
      </class>
  

Otherwise, the exported MoML is that generated by the superclass method that this overrides.

If this object has no container and the depth argument is zero, then this method prepends XML file header information, which is:

  <?xml version="1.0" standalone="no"?>
  <!DOCTYPE entity PUBLIC "-//UC Berkeley//DTD MoML 1//EN"
      "http://ptolemy.eecs.berkeley.edu/xml/dtd/MoML_1.dtd">
  

In the above, "entity" may be replaced by "property" or "port" if what is being exported is an attribute or a port.

The text that is written is indented according to the specified depth, with each line (including the last one) terminated with a newline. Derived classes can override this method to change the MoML description of an object. They can override the protected method _exportMoMLContents() if they need to only change which contents are described.

If this object is not persistent, or if there is no MoML description of this object, or if this object is implied by a parent-child relationship that less than depth levels up in the containment hierarchy and it has not been overridden, then write nothing.

Specified by:

exportMoML in interface MoMLExportable

Overrides:

exportMoML in class NamedObj

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

getChildren

public java.util.List getChildren()

Get a list of weak references to instances of Instantiable that are children of this object. This method may return null or an empty list to indicate that there are no children.

Specified by:

getChildren in interface Instantiable

Returns:

An unmodifiable list of instances of java.lang.ref.WeakReference that refer to instances of Instantiable or null if this object has no children.

See Also:

Instantiable, WeakReference

getElementName

public java.lang.String getElementName()

Get the MoML element name. If this is a class definition, then return "class". Otherwise, defer to the base class.

Specified by:

getElementName in interface MoMLExportable

Overrides:

getElementName in class NamedObj

Returns:

The MoML element name for this object.

See Also:

MoMLExportable

getParent

public Instantiable getParent()

Return the parent of this object, or null if there is none.

Specified by:

getParent in interface Instantiable

Returns:

The parent of this object, or null if there is none.

See Also:

_setParent(Instantiable), Instantiable

getPrototypeList

public java.util.List getPrototypeList()
                                throws IllegalActionException

Return a list of prototypes for this object. The list is ordered so that more local prototypes are listed before more remote prototypes. Specifically, if this object has a parent, then the parent is listed first. If the container has a parent, and that parent contains an object whose name matches the name of this object, then that object is listed next. If the container of the container has a parent, and that parent (deeply) contains a prototype, then that prototype is listed next. And so on up the hierarchy.

Specified by:

getPrototypeList in interface Derivable

Overrides:

getPrototypeList in class NamedObj

Returns:

A list of prototypes for this object, each of which is assured of being an instance of the same (Java) class as this object, or an empty list if there are no prototypes.

Throws:

IllegalActionException - If a prototype with the right name but the wrong class is found.

See Also:

Derivable

instantiate

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

Create an instance by (deeply) 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." The "child" inherits all the objects contained by this object. If this object is a composite, then this method adjusts any parent-child relationships that are entirely contained within the child. 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 by default (it is an "instance" rather than a "class"). To make it a class definition (a "subclass"), call setClassDefinition(boolean) with a true argument.

In this base class, the container argument is ignored except that it provides the workspace into which to clone this object. Derived classes with setContainer() methods are responsible for overriding this and calling setContainer().

Note that the workspace for the instantiated object can be different from the workspace for this object. This means that propagation of changes from a parent to a child may not be able to be safely performed in the child even when they are safely performed in the parent. Subclasses that restrict when changes are performed are therefore required to check whether the workspaces are the same before propagating changes.

Specified by:

instantiate in interface Instantiable

Parameters:

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

name - The name for the instance.

Returns:

A new instance that is a clone of this object with adjusted parent-child 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:

setClassDefinition(boolean), Instantiable

isClassDefinition

public final boolean isClassDefinition()

Return true if this object is a class definition, which means that it can be instantiated.

Specified by:

isClassDefinition in interface Instantiable

Returns:

True if this object is a class definition.

See Also:

setClassDefinition(boolean), Instantiable

isWithinClassDefinition

public final boolean isWithinClassDefinition()

Return true if this object is a class definition or is within a class definition, which means that any container above it in the hierarchy is a class definition.

Returns:

True if this object is within a class definition.

See Also:

setClassDefinition(boolean), Instantiable

setClassDefinition

public void setClassDefinition(boolean isClass)
                        throws IllegalActionException

Specify whether this object is a class definition. This method is write synchronized on the workspace.

Parameters:

isClass - True to make this object a class definition, false to make it an instance.

Throws:

IllegalActionException - If there are subclasses and/or instances and the argument is false.

See Also:

isClassDefinition(), Instantiable

_setParent

protected void _setParent(Instantiable parent)
                   throws IllegalActionException

Specify the parent for this object. This method should be called to make this object either an instance or a subclass of the other object. When generating a MoML description of this object, instead of giving a detailed description, this object will henceforth refer to the specified other object. The name of that other object goes into the "class" or "extends" attribute of the MoML element defining this object (depending on whether this is an instance or a subclass). This method is called when this object is constructed using the instantiate(NamedObj, String) method. This method is write synchronized on the workspace because it modifies the object that is the argument to refer back to this one.

Note that a parent references a child via a weak reference. This means that the parent will not prevent the child from being garbage collected. However, as long as the child has not been garbage collected, changes to the parent will propagate to the child even if there are no other live references to the child. If there are a large number of such dangling children, this could create performance problems when making changes to the parent.

Parameters:

parent - The parent, or null to specify that there is no parent.

Throws:

IllegalActionException - If the parent is not an instance of InstantiableNamedObj.

See Also:

NamedObj.exportMoML(Writer, int), getParent(), Instantiable