Package ptolemy.kernel

Class InstantiableNamedObj

  • All Implemented Interfaces:
    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$
    Author:
    Edward A. Lee
    See Also:
    Instantiable
    Pt.AcceptedRating:
    Green (neuendor)
    Pt.ProposedRating:
    Green (eal)

    • 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

      • 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. Note that this base class does not set the container. It uses the container argument to get the workspace. Derived classes are responsible for setting the container.
        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

      • 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