Class NamedObj

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    Attribute, CertiRtig, CodeGeneratorAdapter, InstantiableNamedObj, Manager, Memory, Port, Relation, TestInstantiableNamedObj, TestNullNamedObj

    public class NamedObj
    extends java.lang.Object
    implements Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, MoMLExportable, ModelErrorHandler, Moveable
    This is a base class for almost all Ptolemy II objects.

    This class supports a naming scheme, change requests, a persistent file format (MoML), a mutual exclusion mechanism for models (the workspace), an error handler, and a hierarchical class mechanism with inheritance.

    An instance of this class can also be parameterized by attaching instances of the Attribute class. Instances of Attribute can be attached by calling their setContainer() method and passing this object as an argument. Those instances will then be reported by the getAttribute(String), getAttribute(String, Class), attributeList() and attributeList(Class) methods. Classes derived from NamedObj may constrain attributes to be a subclass of Attribute. To do that, they should override the protected _addAttribute(Attribute) method to throw an exception if the object provided is not of the right class.

    An instance of this class has a name. A name is an arbitrary string with no periods. If no name is provided, the name is taken to be an empty string (not a null reference). An instance also has a full name, which is a concatenation of the container's full name and the simple name, separated by a period. If there is no container, then the full name begins with a period. The full name is used for error reporting throughout Ptolemy II.

    Instances of this class are associated with a workspace, specified as a constructor argument. The reference to the workspace is immutable. It cannot be changed during the lifetime of this object. It is used for synchronization of methods that depend on or modify the state of objects within it. If no workspace is specified, then the default workspace is used. Note that the workspace should not be confused with the container. The workspace never serves as a container.

    In this base class, the container is null by default, and no method is provided to change it. Derived classes that support hierarchy provide one or more methods that set the container. By convention, if the container is set, then the instance should be removed from the workspace directory, if it is present. The workspace directory is expected to list only top-level objects in a hierarchy. The NamedObj can still use the workspace for synchronization. Any object contained by another uses the workspace of its container as its own workspace by default.

    This class supports change requests or mutations, which are changes to a model that are performed in a disciplined fashion. In particular, a mutation can be requested via the requestChange(ChangeRequest) method. By default, when a change is requested, the change is executed immediately. However, by calling setDeferringChangeRequests(boolean), you can ensure that change requests are queued to be executed only when it is safe to execute them.

    This class supports the notion of a model error, which is an exception that is handled by a registered model error handler, or passed up the container hierarchy if there is no registered model error handler. This mechanism complements the exception mechanism in Java. Instead of unraveling the calling stack to handle exceptions, this mechanism passes control up the Ptolemy II hierarchy.

    Derived classes should override the _description() method to append new fields if there is new information that should be included in the description.

    A NamedObj can contain instances of DecoratorAttributes. These are attributes that are added by another NamedObj that implements the Decorator interface. These attributes are stored separately and can be retrieved by using getDecoratorAttributes(Decorator) or getDecoratorAttribute(Decorator, String).

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Mudit Goel, Edward A. Lee, Neil Smyth, Contributor: Bert Rodiers
    See Also:
    Attribute, Workspace
    Pt.AcceptedRating:
    Green (cxh)
    Pt.ProposedRating:
    Green (eal)
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected class  NamedObj.ContainedObjectsIterator
      This class is an iterator over all the contained objects (all instances of NamedObj).
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.List _changeListeners
      A list of weak references to change listeners.
      protected java.lang.Object _changeLock
      Object for locking accesses to change request list and status.
      protected java.util.List _changeRequests
      A list of pending change requests.
      protected boolean _debugging
      Flag that is true if there are debug listeners.
      protected java.util.LinkedList _debugListeners
      The list of DebugListeners registered with this object.
      protected boolean _deferChangeRequests
      Flag indicating that we should not immediately execute a change request.
      protected java.lang.String _elementName
      The MoML element name.
      protected java.lang.Boolean _isPersistent
      Boolean variable to indicate the persistence of the object.
      protected boolean _verbose
      Flag that is true if detailed debug information is necessary.
      protected Workspace _workspace
      The workspace for this object.
      static int ATTRIBUTES
      Indicate that the description(int) method should include attributes (if any).
      static int CLASSNAME
      Indicate that the description(int) method should include the class name.
      static int COMPLETE
      Indicate that the description(int) method should include everything.
      static int CONTENTS
      Indicate that the description(int) method should include the contained objects (if any) that the object has.
      static int DEEP
      Indicate that the description(int) method should include the contained objects (if any) that the contained objects have.
      static int FULLNAME
      Indicate that the description(int) method should include the full name.
      static int LINKS
      Indicate that the description(int) method should include the links (if any) that the object has.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        NamedObj()
      Construct an object in the default workspace with an empty string as its name.
        NamedObj​(java.lang.String name)
      Construct an object in the default workspace with the given name.
        NamedObj​(Workspace workspace)
      Construct an object in the specified workspace with an empty string as its name.
        NamedObj​(Workspace workspace, java.lang.String name)
      Construct an object in the given workspace with the given name.
      protected NamedObj​(Workspace workspace, java.lang.String name, boolean incrementWorkspaceVersion)
      Construct an object in the given workspace with the given name.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected void _addAttribute​(Attribute attribute)
      Add an attribute.
      protected void _adjustOverride​(int depth)
      Adjust the _override field of this object, if there is one, by incrementing the value at the specified depth by one, and do the same for all contained objects, with one larger depth.
      protected void _attachText​(java.lang.String name, java.lang.String text)
      Attach the specified text as an attribute with the specified name.
      protected void _cloneFixAttributeFields​(NamedObj newObject)
      Fix the fields of the given object which point to Attributes.
      protected java.util.List<Decorator> _containedDecorators()
      Return a list of decorators contained by this object.
      protected java.util.List<ChangeRequest> _copyChangeRequestList()
      Return a copy of the current list of change requests, or return null if there aren't any pending change requests.
      protected void _debug​(java.lang.String message)
      Send a debug message to all debug listeners that have registered.
      protected void _debug​(java.lang.String part1, java.lang.String part2)
      Send a debug message to all debug listeners that have registered.
      protected void _debug​(java.lang.String part1, java.lang.String part2, java.lang.String part3)
      Send a debug message to all debug listeners that have registered.
      protected void _debug​(java.lang.String part1, java.lang.String part2, java.lang.String part3, java.lang.String part4)
      Send a debug message to all debug listeners that have registered.
      protected void _debug​(DebugEvent event)
      Send a debug event to all debug listeners that have registered.
      protected java.lang.String _description​(int detail, int indent, int bracket)
      Return a description of the object.
      protected void _executeChangeRequests​(java.util.List<ChangeRequest> changeRequests)
      Execute the specified list of change requests.
      protected void _exportMoMLContents​(java.io.Writer output, int depth)
      Write a MoML description of the contents of this object, which in this base class is the attributes.
      protected NamedObj _getContainedObject​(NamedObj container, java.lang.String relativeName)
      Get an object with the specified name in the specified container.
      protected static java.lang.String _getIndentPrefix​(int level)
      Return a number of spaces that is proportional to the argument.
      protected boolean _isMoMLSuppressed​(int depth)
      Return true if describing this class in MoML is redundant.
      protected void _markContentsDerived​(int depth)
      Mark the contents of this object as being derived objects.
      protected void _notifyHierarchyListenersAfterChange()
      If any hierarchy listeners are registered, notify them that a change has occurred in the hierarchy.
      protected void _notifyHierarchyListenersBeforeChange()
      If any hierarchy listeners are registered, notify them that a change is about to occur in the hierarchy.
      protected NamedObj _propagateExistence​(NamedObj container)
      Propagate existence of this object to the specified object.
      protected void _propagateValue​(NamedObj destination)
      Propagate the value of this object (if any) to the specified object.
      protected void _removeAttribute​(Attribute param)
      Remove the given attribute.
      protected static java.lang.String[] _splitName​(java.lang.String name)
      Split the specified name at the first period and return the two parts as a two-element array.
      protected static java.lang.String _stripNumericSuffix​(java.lang.String string)
      Return a string that is identical to the specified string except any trailing digits are removed.
      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.
      void addChangeListener​(ChangeListener listener)
      Add a change listener.
      void addDebugListener​(DebugListener listener)
      Append a listener to the current set of debug listeners.
      void addHierarchyListener​(HierarchyListener listener)
      Add a hierarchy listener.
      void attributeChanged​(Attribute attribute)
      React to a change in an attribute.
      void attributeDeleted​(Attribute attribute)
      React to the deletion of an attribute.
      java.util.List attributeList()
      Return a list of the attributes contained by this object.
      <T> java.util.List<T> attributeList​(java.lang.Class<T> filter)
      Return a list of the attributes contained by this object that are instances of the specified class.
      void attributeTypeChanged​(Attribute attribute)
      React to a change in the type of an attribute.
      java.lang.Object clone()
      Clone the object into the current workspace by calling the clone() method that takes a Workspace argument.
      java.lang.Object clone​(Workspace workspace)
      Clone the object into the specified workspace.
      java.util.Iterator containedObjectsIterator()
      Return an iterator over contained objects.
      java.util.Set<Decorator> decorators()
      Return the set of decorators that decorate this object.
      boolean deepContains​(NamedObj inside)
      Return true if this object contains the specified object, directly or indirectly.
      int depthInHierarchy()
      Return the depth in the hierarchy of this object.
      java.lang.String description()
      Return a full description of the object.
      java.lang.String description​(int detail)
      Return a description of the object.
      void event​(DebugEvent event)
      React to the given debug event by relaying to any registered debug listeners.
      void executeChangeRequests()
      Execute previously requested changes.
      java.lang.String exportMoML()
      Get a MoML description of this object.
      void exportMoML​(java.io.Writer output)
      Write a MoML description of this object using the specified Writer.
      void exportMoML​(java.io.Writer output, int depth)
      Write a MoML description of this entity with the specified indentation depth.
      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.lang.String exportMoML​(java.lang.String name)
      Get a MoML description of this object with its name replaced by the specified name.
      java.lang.String exportMoMLPlain()
      Get a MoML description of this object without any XML headers.
      Attribute getAttribute​(java.lang.String name)
      Get the attribute with the given name.
      Attribute getAttribute​(java.lang.String name, java.lang.Class attributeClass)
      Get the attribute with the given name and class.
      java.util.Enumeration getAttributes()
      Deprecated.
      Use attributeList() instead.
      java.util.List getChangeListeners()
      Return a list of weak references to change listeners, or null if there is none.
      java.lang.String getClassName()
      Return the MoML class name.
      NamedObj getContainer()
      Get the container.
      Attribute getDecoratorAttribute​(Decorator decorator, java.lang.String name)
      Return the decorator attribute with the specified name for the specified decorator, or null the specified decorator provides no attribute with the specified name or the decorator does not decorate this object.
      DecoratorAttributes getDecoratorAttributes​(Decorator decorator)
      Return the decorated attributes of this NamedObj, as decorated by the specified decorator.
      int getDerivedLevel()
      Get the minimum level above this object in the hierarchy where a parent-child relationship implies the existence of this object.
      java.util.List getDerivedList()
      Return a list of objects derived from this one.
      java.lang.String getDisplayName()
      Return a name to present to the user.
      java.lang.String getElementName()
      Get the MoML element name.
      java.lang.String getFullName()
      Return a string of the form ".name1.name2...nameN".
      ModelErrorHandler getModelErrorHandler()
      Get the model error handler specified by setErrorHandler().
      java.lang.String getName()
      Get the name.
      java.lang.String getName​(NamedObj parent)
      Get the name of this object relative to the specified container.
      java.util.List getPrototypeList()
      Return a list of prototypes for this object.
      java.lang.String getSource()
      Get the source, which gives an external URL associated with an entity (presumably from which the entity was defined).
      boolean handleModelError​(NamedObj context, IllegalActionException exception)
      Handle a model error.
      boolean isDeferringChangeRequests()
      Return true if setDeferringChangeRequests(true) has been called to specify that change requests should be deferred.
      boolean isOverridden()
      Return true if propagateValue() has been called, which indicates that the value of this object (if any) has been overridden from the default defined by its class definition.
      boolean isPersistent()
      Return true if this object is persistent.
      java.util.Iterator lazyContainedObjectsIterator()
      Return an iterator over contained object that currently exist, omitting any objects that have not yet been instantiated because they are "lazy".
      void message​(java.lang.String message)
      React to a debug message by relaying it to any registered debug listeners.
      int moveDown()
      Move this object down by one in the list of objects in its container.
      int moveToFirst()
      Move this object to the first position in the list of attributes of the container.
      int moveToIndex​(int index)
      Move this object to the specified position in the list of attributes of the container.
      int moveToLast()
      Move this object to the last position in the list of attributes of the container.
      int moveUp()
      Move this object up by one in the list of attributes of the container.
      void notifyOfNameChange​(NamedObj object)
      React to a change in a contained named object.
      java.util.List propagateExistence()
      Propagate the existence of this object.
      java.util.List propagateValue()
      Propagate the value (if any) held by this object to derived objects that have not been overridden.
      void propagateValues()
      If this object has a value that has been set directly, or if it has a value that has propagated in, then propagate that value to all derived objects, and then repeat this for all objects this object contains.
      void removeAttribute​(Attribute param)
      Remove attribute from list of attributes.
      void removeChangeListener​(ChangeListener listener)
      Remove a change listener.
      void removeDebugListener​(DebugListener listener)
      Unregister a debug listener.
      void removeHierarchyListener​(HierarchyListener listener)
      Remove a hierarchy listener.
      void requestChange​(ChangeRequest change)
      Request that the given change be executed.
      void setClassName​(java.lang.String name)
      Set the MoML class name.
      void setDeferringChangeRequests​(boolean isDeferring)
      Specify whether change requests made by calls to requestChange() should be executed immediately.
      void setDerivedLevel​(int level)
      Set the level above this object in the hierarchy where a parent-child relationship implies the existence of this object.
      void setDisplayName​(java.lang.String name)
      Set a name to present to the user.
      void setModelErrorHandler​(ModelErrorHandler handler)
      Set the model error handler.
      void setName​(java.lang.String name)
      Set or change the name.
      void setPersistent​(boolean persistent)
      Set the persistence of this object.
      void setSource​(java.lang.String source)
      Set the source, which gives an external URL associated with an entity (presumably from which the entity was defined).
      java.util.List sortContainedObjects​(java.util.Collection filter)
      Return an ordered list of contained objects filtered by the specified filter.
      NamedObj toplevel()
      Return the top level of the containment hierarchy.
      java.lang.String toString()
      Return the class name and the full name of the object, with syntax "className {fullName}".
      java.lang.String uniqueName​(java.lang.String prefix)
      Return a name that is guaranteed to not be the name of any contained attribute.
      void validateSettables()
      Validate attributes deeply contained by this object if they implement the Settable interface by calling their validate() method.
      Workspace workspace()
      Get the workspace.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • COMPLETE

        public static final int COMPLETE
        Indicate that the description(int) method should include everything.
        See Also:
        Constant Field Values
      • CLASSNAME

        public static final int CLASSNAME
        Indicate that the description(int) method should include the class name.
        See Also:
        Constant Field Values
      • FULLNAME

        public static final int FULLNAME
        Indicate that the description(int) method should include the full name. The full name is surrounded by braces "{name}" in case it has spaces.
        See Also:
        Constant Field Values
      • LINKS

        public static final int LINKS
        Indicate that the description(int) method should include the links (if any) that the object has. This has the form "links {...}" where the list is a list of descriptions of the linked objects. This may force some of the contents to be listed. For example, a description of an entity will include the ports if this is set, irrespective of whether the CONTENTS bit is set.
        See Also:
        Constant Field Values
      • CONTENTS

        public static final int CONTENTS
        Indicate that the description(int) method should include the contained objects (if any) that the object has. This has the form "keyword {{class {name}} {class {name}} ... }" where the keyword can be ports, entities, relations, or anything else that might indicate what the object contains.
        See Also:
        Constant Field Values
      • DEEP

        public static final int DEEP
        Indicate that the description(int) method should include the contained objects (if any) that the contained objects have. This has no effect if CONTENTS is not also specified. The returned string has the form "keyword {{class {name} keyword {...}} ... }".
        See Also:
        Constant Field Values
      • ATTRIBUTES

        public static final int ATTRIBUTES
        Indicate that the description(int) method should include attributes (if any).
        See Also:
        Constant Field Values
      • _changeListeners

        protected java.util.List _changeListeners
        A list of weak references to change listeners.
      • _changeLock

        protected java.lang.Object _changeLock
        Object for locking accesses to change request list and status. NOTE: We could have used _changeRequests or _changeListeners, but those lists are only created when needed. A simple Object here is presumably cheaper than a list, but it is truly unfortunate to have to carry this in every NamedObj.
      • _changeRequests

        protected java.util.List _changeRequests
        A list of pending change requests.
      • _debugging

        protected boolean _debugging
        Flag that is true if there are debug listeners.
      • _debugListeners

        protected java.util.LinkedList _debugListeners
        The list of DebugListeners registered with this object. NOTE: Because of the way we synchronize on this object, it should never be reset to null after the first list is created.
      • _deferChangeRequests

        protected transient boolean _deferChangeRequests
        Flag indicating that we should not immediately execute a change request.
      • _elementName

        protected java.lang.String _elementName
        The MoML element name. This defaults to "entity". Subclasses that wish this to be different should set it in their constructor, or override getElementName() to return the desired value.
      • _isPersistent

        protected java.lang.Boolean _isPersistent
        Boolean variable to indicate the persistence of the object. If this is null (the default), then instances of NamedObj are persistent unless they are inferrable through propagation. We use Boolean here rather than boolean because a null value is used to indicate that no persistence has been specified.
      • _workspace

        protected Workspace _workspace
        The workspace for this object. This should be set by the constructor and never changed.
      • _verbose

        protected boolean _verbose
        Flag that is true if detailed debug information is necessary.
    • Constructor Detail

      • NamedObj

        public NamedObj()
        Construct an object in the default workspace with an empty string as its name. The object is added to the list of objects in the workspace. Increment the version number of the workspace.
      • NamedObj

        public NamedObj​(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 list of objects in the workspace. Increment the version number of the workspace.
        Parameters:
        name - Name of this object.
        Throws:
        IllegalActionException - If the name has a period.
      • NamedObj

        public NamedObj​(Workspace workspace)
        Construct an object in the specified workspace with an empty string as its name. The object is added to the list of objects in the workspace. Increment the version number of the workspace.
        Parameters:
        workspace - Object for synchronization and version tracking
      • NamedObj

        public NamedObj​(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. The object is added to the list of objects in the workspace. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.
        Parameters:
        workspace - Object for synchronization and version tracking
        name - Name of this object.
        Throws:
        IllegalActionException - If the name has a period.
      • NamedObj

        protected NamedObj​(Workspace workspace,
                           java.lang.String name,
                           boolean incrementWorkspaceVersion)
                    throws IllegalActionException
        Construct an object in the given workspace with the given name. If the workspace argument is null, use the default workspace. The object is added to the list of objects in the workspace. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.
        Parameters:
        workspace - Object for synchronization and version tracking
        name - Name of this object.
        incrementWorkspaceVersion - False to not add this to the workspace or do anything else that might change the workspace version number.
        Throws:
        IllegalActionException - If the name has a period.
    • Method Detail

      • addChangeListener

        public void addChangeListener​(ChangeListener listener)
        Add a change listener. If there is a container, then delegate to the container. Otherwise, add the listener to the list of change listeners in this object. Each listener will be notified of the execution (or failure) of each change request that is executed via the requestChange() method. Note that in this implementation, only the top level of a hierarchy executes changes, which is why this method delegates to the container if there is one.

        If the listener is already in the list, remove the previous instance and add it again in the first position. This listener is also notified before other listeners that have been previously registered with the top-level object.

        Specified by:
        addChangeListener in interface Changeable
        Parameters:
        listener - The listener to add.
        See Also:
        removeChangeListener(ChangeListener), requestChange(ChangeRequest), Changeable
      • addDebugListener

        public void addDebugListener​(DebugListener listener)
        Append a listener to the current set of debug listeners. If the listener is already in the set, do not add it again.
        Specified by:
        addDebugListener in interface Debuggable
        Parameters:
        listener - The listener to which to send debug messages.
        See Also:
        removeDebugListener(DebugListener)
      • addHierarchyListener

        public void addHierarchyListener​(HierarchyListener listener)
        Add a hierarchy listener. If the listener is already added, do nothing. This will cause the object to also be added as a hierarchy listener in the container of this object, if there is one, and in its container, up to the top of the hierarchy.
        Parameters:
        listener - The listener to add.
        See Also:
        removeHierarchyListener(HierarchyListener)
      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                              throws IllegalActionException
        React to a change in an attribute. This method is called by a contained attribute when its value changes. In this base class, the method does nothing. In derived classes, this method may throw an exception, indicating that the new attribute value is invalid. It is up to the caller to restore the attribute to a valid value if an exception is thrown.
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).
      • attributeDeleted

        public void attributeDeleted​(Attribute attribute)
                              throws IllegalActionException
        React to the deletion of an attribute. This method is called by a contained attributed when it is deleted. In this base class, the method does nothing. In derived classes, this method may deal with consequences of deletion, for instance, update local variables.
        Parameters:
        attribute - The attribute that was deleted.
        Throws:
        IllegalActionException - If the deletion is not acceptable to this container (not thrown in this base class).
      • attributeList

        public java.util.List attributeList()
        Return a list of the attributes contained by this object. If there are no attributes, return an empty list. This method is read-synchronized on the workspace.
        Returns:
        An unmodifiable list of instances of Attribute.
      • attributeList

        public <T> java.util.List<T> attributeList​(java.lang.Class<T> filter)
        Return a list of the attributes contained by this object that are instances of the specified class. If there are no such instances, then return an empty list. This method is read-synchronized on the workspace.
        Type Parameters:
        T - The type of that class.
        Parameters:
        filter - The class of attribute of interest.
        Returns:
        A list of instances of specified class.
      • attributeTypeChanged

        public void attributeTypeChanged​(Attribute attribute)
                                  throws IllegalActionException
        React to a change in the type of an attribute. This method is called by a contained attribute when its type changes. In this base class, the method does nothing.
        Parameters:
        attribute - The attribute whose type changed.
        Throws:
        IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).
      • clone

        public java.lang.Object clone()
                               throws java.lang.CloneNotSupportedException
        Clone the object into the current workspace by calling the clone() method that takes a Workspace argument. This method read-synchronizes on the workspace.
        Overrides:
        clone in class java.lang.Object
        Returns:
        A new NamedObj.
        Throws:
        java.lang.CloneNotSupportedException - If any of the attributes cannot be cloned.
      • 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 uses the clone() method of java.lang.Object, which makes a field-by-field copy. It then adjusts the workspace reference and clones the attributes on the attribute list, if there is one. The attributes are set to the attributes of the new object. The new object will be set to defer change requests, so change requests can be safely issued during cloning. However, it is up to the caller of this clone() method to then execute the the change requests, or to call setDeferringChangeRequests(false). This method read-synchronizes on the workspace.
        Parameters:
        workspace - The workspace for the new object.
        Returns:
        A new NamedObj.
        Throws:
        java.lang.CloneNotSupportedException - If any of the attributes cannot be cloned.
        See Also:
        exportMoML(Writer, int, String), setDeferringChangeRequests(boolean)
      • containedObjectsIterator

        public java.util.Iterator containedObjectsIterator()
        Return an iterator over contained objects. In this base class, this is simply an iterator over attributes. In derived classes, the iterator will also traverse ports, entities, classes, and relations.
        Returns:
        An iterator over instances of NamedObj contained by this object.
      • decorators

        public java.util.Set<Decorator> decorators()
                                            throws IllegalActionException
        Return the set of decorators that decorate this object.
        Returns:
        The decorators that decorate this object (which may be an empty set).
        Throws:
        IllegalActionException - If a decorator referenced by a DecoratorAttributes cannot be found.
        See Also:
        Decorator
      • deepContains

        public boolean deepContains​(NamedObj inside)
        Return true if this object contains the specified object, directly or indirectly. That is, return true if the specified object is contained by an object that this contains, or by an object contained by an object contained by this, etc. This method ignores whether the entities report that they are atomic (see CompositeEntity), and always returns false if the entities are not in the same workspace. This method is read-synchronized on the workspace.
        Parameters:
        inside - The object to check for inside this object.
        Returns:
        True if this contains the argument, directly or indirectly.
      • depthInHierarchy

        public int depthInHierarchy()
        Return the depth in the hierarchy of this object. If this object has no container, then return 0. If its container has no container, then return 1. Etc.
        Returns:
        The depth in the hierarchy of this object.
      • description

        public java.lang.String description()
                                     throws IllegalActionException
        Return a full description of the object. This is accomplished by calling the description method with an argument for full detail. This method read-synchronizes on the workspace.
        Specified by:
        description in interface Nameable
        Returns:
        A description of the object.
        Throws:
        IllegalActionException - Not thrown in this base class, but derived classes could throw an exception if there is a problem accessing subcomponents of this object.
        See Also:
        exportMoML(Writer, int, String)
      • description

        public java.lang.String description​(int detail)
                                     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 this class (NamedObj). This method returns an empty string (not null) if there is nothing to report. It read-synchronizes on the workspace.
        Parameters:
        detail - The level of detail.
        Returns:
        A description of the object.
        Throws:
        IllegalActionException - Not thrown in this base class, but derived classes could throw an exception if there is a problem accessing subcomponents of this object.
        See Also:
        exportMoML(Writer, int, String)
      • event

        public void event​(DebugEvent event)
        React to the given debug event by relaying to any registered debug listeners.
        Specified by:
        event in interface DebugListener
        Parameters:
        event - The event.
        Since:
        Ptolemy II 2.3
      • exportMoML

        public final java.lang.String exportMoML()
        Get a MoML description of this object. This might be an empty string if there is no MoML description of this object or if this object is not persistent or if this object is a derived object. This uses the three-argument version of this method. It is final to ensure that derived classes only need to override that method to change the MoML description.
        Specified by:
        exportMoML in interface MoMLExportable
        Returns:
        A MoML description, or an empty string if there is none.
        See Also:
        MoMLExportable, exportMoML(Writer, int, String), isPersistent(), getDerivedLevel()
      • exportMoML

        public final java.lang.String exportMoML​(java.lang.String name)
        Get a MoML description of this object with its name replaced by the specified name. The description might be an empty string if there is no MoML description of this object or if this object is not persistent, or this object a derived object. This uses the three-argument version of this method. It is final to ensure that derived classes only override that method to change the MoML description.
        Specified by:
        exportMoML in interface MoMLExportable
        Parameters:
        name - The name of we use when exporting the description.
        Returns:
        A MoML description, or the empty string if there is none.
        See Also:
        MoMLExportable, exportMoML(Writer, int, String), isPersistent(), getDerivedLevel()
      • exportMoML

        public final void exportMoML​(java.io.Writer output)
                              throws java.io.IOException
        Write a MoML description of this object using the specified Writer. If there is no MoML description, or if the object is not persistent, or if this object is a derived object, then nothing is written. To write to standard out, do
              exportMoML(new OutputStreamWriter(System.out))
          
        This method uses the three-argument version of this method. It is final to ensure that derived classes only need to override that method to change the MoML description.
        Specified by:
        exportMoML in interface MoMLExportable
        Parameters:
        output - The stream to write to.
        Throws:
        java.io.IOException - If an I/O error occurs.
        See Also:
        MoMLExportable, exportMoML(Writer, int, String), isPersistent(), getDerivedLevel()
      • exportMoML

        public final void exportMoML​(java.io.Writer output,
                                     int depth)
                              throws java.io.IOException
        Write a MoML description of this entity with the specified indentation depth. This calls the three-argument version of this method with getName() as the third argument. This method is final to ensure that derived classes only override the three-argument method to change the MoML description. If the object is not persistent, or if there is no MoML description, or if this object is a class instance, then write nothing.
        Specified by:
        exportMoML in interface MoMLExportable
        Parameters:
        output - The output stream to write to.
        depth - The depth in the hierarchy, to determine indenting.
        Throws:
        java.io.IOException - If an I/O error occurs.
        See Also:
        MoMLExportable, exportMoML(Writer, int, String), isPersistent(), getDerivedLevel()
      • 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 class name is determined by getClassName(), the source is determined by getSource(). The description has the form:
              <element name="name" class="classname" source="source">>
                  body, determined by _exportMoMLContents()
              </element>
          
        By default, the element name is "entity." The default class name is the Java classname of this instance. The source attribute is by default left off altogether.

        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 somehow a top-level property or port is exported.

        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 a class instance, then write nothing.

        Specified by:
        exportMoML in interface MoMLExportable
        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, clone(Workspace), isPersistent(), getDerivedLevel()
      • exportMoMLPlain

        public final java.lang.String exportMoMLPlain()
        Get a MoML description of this object without any XML headers. This differs significantly from exportMoML() only if this object has no container, because if it has a container, then it will not export MoML headers anyway.
        Returns:
        A MoML description, or the empty string if there is none.
        See Also:
        exportMoML()
      • 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. If the given name is null, then an InternalErrorException is thrown. This method is read-synchronized on the workspace.
        Parameters:
        name - The name of the desired attribute.
        Returns:
        The requested attribute if it is found, null otherwise.
      • getAttribute

        public Attribute getAttribute​(java.lang.String name,
                                      java.lang.Class attributeClass)
                               throws IllegalActionException
        Get the attribute with the given name and class. If an attribute is found that has the specified name, but the class does not match, then throw an IllegalActionException. The name may be compound, with fields separated by periods, in which case the attribute returned is contained by a (deeply) contained attribute. This method is read-synchronized on the workspace.
        Parameters:
        name - The name of the desired attribute.
        attributeClass - The class of the desired attribute.
        Returns:
        The requested attribute if it is found, null otherwise.
        Throws:
        IllegalActionException - If an attribute is found with the specified name that is not an instance of the specified class.
      • getAttributes

        @Deprecated
        public java.util.Enumeration getAttributes()
        Deprecated.
        Use attributeList() instead.
        Return an enumeration of the attributes attached to this object. This method is read-synchronized on the workspace.
        Returns:
        An enumeration of instances of Attribute.
      • getChangeListeners

        public java.util.List getChangeListeners()
        Return a list of weak references to change listeners, or null if there is none.
        Returns:
        A list of weak references to change listeners, or null if there is none.
      • getClassName

        public java.lang.String getClassName()
        Return the MoML class name. This is either the class of which this object is an instance, or if this object is itself a class, then the class that it extends. By default, it will be the Java class name of this object. This method never returns null.
        Specified by:
        getClassName in interface MoMLExportable
        Returns:
        The MoML class name.
        See Also:
        MoMLExportable, setClassName(String)
      • getContainer

        public NamedObj getContainer()
        Get the container. Always return null in this base class. A null returned value should be interpreted as indicating that there is no container.
        Specified by:
        getContainer in interface Nameable
        Returns:
        null.
      • getDecoratorAttribute

        public Attribute getDecoratorAttribute​(Decorator decorator,
                                               java.lang.String name)
                                        throws IllegalActionException
        Return the decorator attribute with the specified name for the specified decorator, or null the specified decorator provides no attribute with the specified name or the decorator does not decorate this object. This method is normally called by the decorator itself to retrieve its decorated parameter values for this NamedObj. If this object has no decorator attributes, then calling this method will cause them to be created and assigned default values, if the specified decorator decorates this object.
        Parameters:
        decorator - The decorator.
        name - The name of the attribute.
        Returns:
        The attribute with the given name for the decorator, or null if the specified decorator does not provide an attribute with the specified name.
        Throws:
        IllegalActionException - If a decorator referenced by a DecoratorAttributes cannot be found.
        See Also:
        Decorator.createDecoratorAttributes(NamedObj), getDecoratorAttributes(Decorator)
      • getDerivedLevel

        public int getDerivedLevel()
        Get the minimum level above this object in the hierarchy where a parent-child relationship implies the existence of this object. A value Integer.MAX_VALUE is used to indicate that this object is not a derived object. A value of 1 indicates that the container of the object is a child, and that the this object is derived from a prototype in the parent of the container. Etc.
        Specified by:
        getDerivedLevel in interface Derivable
        Returns:
        The level above this object in the containment hierarchy where a parent-child relationship implies this object.
        See Also:
        Derivable, setDerivedLevel(int)
      • getDerivedList

        public java.util.List getDerivedList()
        Return a list of objects derived from this one. This is the list of objects that are "inherited" by their containers from a container of this object. The existence of these derived objects is "implied" by a parent-child relationship somewhere above this object in the containment hierarchy. This method returns a complete list, including objects that have been overridden.
        Specified by:
        getDerivedList in interface Derivable
        Returns:
        A list of objects of the same class as the object on which this is called, or an empty list if there are none.
        See Also:
        Derivable
      • getDisplayName

        public java.lang.String getDisplayName()
        Return a name to present to the user. If setDisplayName(String) has been called, then return the name specified there, and otherwise return the name returned by getName().
        Specified by:
        getDisplayName in interface Nameable
        Returns:
        A name to present to the user.
        See Also:
        setDisplayName(String)
      • getElementName

        public java.lang.String getElementName()
        Get the MoML element name. This defaults to "entity" but can be set to something else by subclasses.
        Specified by:
        getElementName in interface MoMLExportable
        Returns:
        The MoML element name for this object.
        See Also:
        MoMLExportable
      • getFullName

        public java.lang.String getFullName()
        Return a string of the form ".name1.name2...nameN". Here, "nameN" is the name of this object, and the intervening names are the names of the containers of this other name of this object, if there are containers. A recursive structure, where this object is directly or indirectly contained by itself, results in a runtime exception of class InvalidStateException. Note that it is not possible to construct a recursive structure using this class alone, since there is no container. But derived classes might erroneously permit recursive structures, so this error is caught here. This method is read-synchronized on the workspace.
        Specified by:
        getFullName in interface Nameable
        Returns:
        The full name of the object.
      • getName

        public java.lang.String getName()
        Get the name. If no name has been given, or null has been given, then return an empty string, "".
        Specified by:
        getName in interface Nameable
        Returns:
        The name of the object.
        See Also:
        setName(String)
      • getName

        public java.lang.String getName​(NamedObj parent)
                                 throws InvalidStateException
        Get the name of this object relative to the specified container. If this object is contained directly by the specified container, this is just its name, as returned by getName(). If it is deeply contained by the specified container, then the relative name is x1.x2. ... .name, where x1 is directly contained by the specified container, x2 is contained by x1, etc. If this object is not deeply contained by the specified container, then this method returns the full name of this object, as returned by getFullName().

        A recursive structure, where this object is directly or indirectly contained by itself, may result in a runtime exception of class InvalidStateException if it is detected. Note that it is not possible to construct a recursive structure using this class alone, since there is no container. But derived classes might erroneously permit recursive structures, so this error is caught here.

        This method is read-synchronized on the workspace.

        Specified by:
        getName in interface Nameable
        Parameters:
        parent - The object relative to which you want the name.
        Returns:
        A string of the form "name2...nameN".
        Throws:
        InvalidStateException - If a recursive structure is encountered, where this object directly or indirectly contains itself. Note that this is a runtime exception so it need not be declared explicitly.
        See Also:
        setName(String)
      • 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 the container has a parent, and that parent contains an object whose name matches the name of this object, then that object is the first prototype listed. 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
        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
      • getSource

        public java.lang.String getSource()
        Get the source, which gives an external URL associated with an entity (presumably from which the entity was defined). This becomes the value in the "source" attribute of exported MoML.
        Specified by:
        getSource in interface MoMLExportable
        Returns:
        The source, or null if there is none.
        See Also:
        setSource(String), MoMLExportable
      • handleModelError

        public boolean handleModelError​(NamedObj context,
                                        IllegalActionException exception)
                                 throws IllegalActionException
        Handle a model error. If a model error handler has been registered with setModelErrorHandler(), then handling is delegated to that handler. Otherwise, or if the registered error handler declines to handle the error by returning false, then if there is a container, handling is delegated to the container. If there is no container and no handler that agrees to handle the error, then return false.

        A typical use of this facility is where a subclass of NamedObj does the following:

             handleModelError(this, new IllegalActionException(this, message));
          
        instead of this:
             throw new IllegalActionException(this, message);
          
        The former allows a container in the hierarchy to intercept the exception, whereas the latter simply throws the exception.
        Specified by:
        handleModelError in interface ModelErrorHandler
        Parameters:
        context - The object in which the error occurred.
        exception - An exception that represents the error.
        Returns:
        True if the error is handled, false otherwise.
        Throws:
        IllegalActionException - If the handler handles the error by throwing an exception.
        See Also:
        setModelErrorHandler(ModelErrorHandler handler)
      • isDeferringChangeRequests

        public boolean isDeferringChangeRequests()
        Return true if setDeferringChangeRequests(true) has been called to specify that change requests should be deferred. If there is a container, this delegates to the container.
        Specified by:
        isDeferringChangeRequests in interface Changeable
        Returns:
        True if change requests are being deferred.
        See Also:
        setDeferringChangeRequests(boolean), Changeable
      • isOverridden

        public boolean isOverridden()
        Return true if propagateValue() has been called, which indicates that the value of this object (if any) has been overridden from the default defined by its class definition. Note that if setDerivedLevel() is called after propagateValue(), then this method will return false, since setDerivedLevel() resets the override property.
        Returns:
        True if propagateValues() has been called.
        See Also:
        propagateValue(), setDerivedLevel(int)
      • isPersistent

        public boolean isPersistent()
        Return true if this object is persistent. A persistent object has a MoML description that can be stored in a file and used to re-create the object. A non-persistent object has an empty MoML description.
        Specified by:
        isPersistent in interface MoMLExportable
        Returns:
        True if the object is persistent.
        See Also:
        setPersistent(boolean), MoMLExportable
      • lazyContainedObjectsIterator

        public java.util.Iterator lazyContainedObjectsIterator()
        Return an iterator over contained object that currently exist, omitting any objects that have not yet been instantiated because they are "lazy". A lazy object is one that is instantiated when it is needed, but not before. In this base class, this method returns the same iterator returned by containedObjectsIterator(). If derived classes override it, they must guarantee that any omitted objects are genuinely not needed in whatever uses this method.
        Returns:
        An iterator over instances of NamedObj contained by this object.
      • message

        public void message​(java.lang.String message)
        React to a debug message by relaying it to any registered debug listeners.
        Specified by:
        message in interface DebugListener
        Parameters:
        message - The debug message.
        Since:
        Ptolemy II 2.3
      • moveDown

        public int moveDown()
                     throws IllegalActionException
        Move this object down by one in the list of objects in its container. If this object is already last, do nothing. In this base class, this method throws an IllegalActionException because this base class does not have a setContainer() method, and hence cannot be contained. Any derived object that implements setContainer() should also implement this method.
        Specified by:
        moveDown in interface Moveable
        Returns:
        This base class does not return. In derived classes, it should return the index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - Always thrown in this base class.
      • moveToFirst

        public int moveToFirst()
                        throws IllegalActionException
        Move this object to the first position in the list of attributes of the container. If this object is already first, do nothing. In this base class, this method throws an IllegalActionException because this base class does not have a setContainer() method, and hence cannot be contained. Any derived object that implements setContainer() should also implement this method.
        Specified by:
        moveToFirst in interface Moveable
        Returns:
        This base class does not return. In derived classes, it should return the index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - Always thrown in this base class.
      • moveToIndex

        public int moveToIndex​(int index)
                        throws IllegalActionException
        Move this object to the specified position in the list of attributes of the container. If this object is already at the specified position, do nothing. In this base class, this method throws an IllegalActionException because this base class does not have a setContainer() method, and hence cannot be contained. Any derived object that implements setContainer() should also implement this method.
        Specified by:
        moveToIndex in interface Moveable
        Parameters:
        index - The position to move this object to.
        Returns:
        This base class does not return. In derived classes, it should return the index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - Always thrown in this base class.
      • moveToLast

        public int moveToLast()
                       throws IllegalActionException
        Move this object to the last position in the list of attributes of the container. If this object is already last, do nothing. In this base class, this method throws an IllegalActionException because this base class does not have a setContainer() method, and hence cannot be contained. Any derived object that implements setContainer() should also implement this method.
        Specified by:
        moveToLast in interface Moveable
        Returns:
        This base class does not return. In derived classes, it should return the index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - Always thrown in this base class.
      • moveUp

        public int moveUp()
                   throws IllegalActionException
        Move this object up by one in the list of attributes of the container. If this object is already first, do nothing. In this base class, this method throws an IllegalActionException because this base class does not have a setContainer() method, and hence cannot be contained. Any derived object that implements setContainer() should also implement this method.
        Specified by:
        moveUp in interface Moveable
        Returns:
        This base class does not return. In derived classes, it should return the index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - Always thrown in this base class.
      • notifyOfNameChange

        public void notifyOfNameChange​(NamedObj object)
        React to a change in a contained named object. This method is called by a contained named object when its name or display name changes. In this base class, the method does nothing.
        Parameters:
        object - The object that changed.
      • 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. The contents of each so created object is marked as derived using setDerivedLevel(). Return the list of objects that are created.
        Specified by:
        propagateExistence in interface Derivable
        Returns:
        A list of derived objects of the same class as this object that are created.
        Throws:
        IllegalActionException - If the object does not exist and cannot be created.
        See Also:
        Derivable, setDerivedLevel(int)
      • propagateValue

        public java.util.List propagateValue()
                                      throws IllegalActionException
        Propagate the value (if any) held by this object to derived objects that have not been overridden. This leaves all derived objects unchanged if any single derived object throws an exception when attempting to propagate the value to it. This also marks this object as overridden.
        Specified by:
        propagateValue in interface Derivable
        Returns:
        The list of objects to which this propagated.
        Throws:
        IllegalActionException - If propagation fails.
        See Also:
        Derivable, isOverridden()
      • propagateValues

        public void propagateValues()
                             throws IllegalActionException
        If this object has a value that has been set directly, or if it has a value that has propagated in, then propagate that value to all derived objects, and then repeat this for all objects this object contains. Unlike propagateValue(), this does not assume this object or any of its contained objects is having its value set directly. Instead, it uses the current state of override of this object as the starting point.
        Throws:
        IllegalActionException - If propagation fails.
      • removeDebugListener

        public void removeDebugListener​(DebugListener listener)
        Unregister a debug listener. If the specified listener has not been previously registered, then do nothing.
        Specified by:
        removeDebugListener in interface Debuggable
        Parameters:
        listener - The listener to remove from the list of listeners to which debug messages are sent.
        See Also:
        addDebugListener(DebugListener)
      • removeHierarchyListener

        public void removeHierarchyListener​(HierarchyListener listener)
        Remove a hierarchy listener. If the listener is already removed, do nothing. This will cause the object to also be removed as a hierarchy listener in the container of this object, if there is one, and in its container, up to the top of the hierarchy.
        Parameters:
        listener - The listener to remove.
        See Also:
        addHierarchyListener(HierarchyListener)
      • requestChange

        public void requestChange​(ChangeRequest change)
        Request that the given change be executed. In this base class, delegate the change request to the container, if there is one. If there is no container, then execute the request immediately, unless this object is deferring change requests. If setDeferChangeRequests() has been called with a true argument, then simply queue the request until either setDeferChangeRequests() is called with a false argument or executeChangeRequests() is called. If this object is already in the middle of executing a change request, then that execution is finished before this one is performed. Change listeners will be notified of success (or failure) of the request when it is executed.
        Specified by:
        requestChange in interface Changeable
        Parameters:
        change - The requested change.
        See Also:
        executeChangeRequests(), setDeferringChangeRequests(boolean), Changeable
      • setClassName

        public void setClassName​(java.lang.String name)
        Set the MoML class name. This is either the class of which this object is an instance, or if this object is itself a class, then the class that it extends.
        Parameters:
        name - The MoML class name.
        See Also:
        getClassName()
      • setDeferringChangeRequests

        public void setDeferringChangeRequests​(boolean isDeferring)
        Specify whether change requests made by calls to requestChange() should be executed immediately. If there is a container, then this request is delegated to the container. Otherwise, if the argument is true, then requests are simply queued until either this method is called again with argument false, or until executeChangeRequests() is called. If the argument is false, then execute any pending change requests and set a flag requesting that future requests be executed immediately.
        Specified by:
        setDeferringChangeRequests in interface Changeable
        Parameters:
        isDeferring - If true, defer change requests.
        See Also:
        addChangeListener(ChangeListener), executeChangeRequests(), isDeferringChangeRequests(), requestChange(ChangeRequest), Changeable
      • setDerivedLevel

        public final void setDerivedLevel​(int level)
        Set the level above this object in the hierarchy where a parent-child relationship implies the existence of this object. When this object is originally created by a constructor or by the clone method, the level is set to the default Integer.MAX_VALUE, which indicates that the object is not implied. When this is called multiple times, the level will be the minimum of all the levels specified. Thus, a value of 1 indicates that the container of the object is a child, and that this object is implied by a like object in the parent of the container, for example. If an object is implied, then it normally has no persistent representation when it is exported to MoML (unless it is overridden), and normally it cannot have its name or container changed. An exception, however, is that the object may appear in the MoML if the exported MoML does not include the level of the hierarchy above this with the parent-child relationship that implies this object. Calling this method also has the side effect of resetting the flag used to determine whether the value of this object overrides some inherited value. So this method should only be called when object is first being constructed.

        NOTE: This method is tricky to use correctly. It is public because the MoML parser needs access to it. It should not be considered part of the public interface, however, in that only very sophisticated users should use it.

        Parameters:
        level - The minimum level above this object in the containment hierarchy where a parent-child relationship implies this object.
        See Also:
        getDerivedLevel(), setPersistent(boolean), Derivable
      • setDisplayName

        public void setDisplayName​(java.lang.String name)
        Set a name to present to the user.
        Parameters:
        name - A name to present to the user.
        See Also:
        getDisplayName()
      • setModelErrorHandler

        public void setModelErrorHandler​(ModelErrorHandler handler)
        Set the model error handler.
        Parameters:
        handler - The error handler, or null to specify no handler.
        See Also:
        getModelErrorHandler()
      • setName

        public void setName​(java.lang.String name)
                     throws IllegalActionException,
                            NameDuplicationException
        Set or change the name. If a null argument is given the name is set to an empty string. Increment the version of the workspace. This method is write-synchronized on the workspace.
        Specified by:
        setName in interface Nameable
        Parameters:
        name - The new name.
        Throws:
        IllegalActionException - If the name contains a period or if the object is a derived object and the name argument does not match the current name.
        NameDuplicationException - Not thrown in this base class. May be thrown by derived classes if the container already contains an object with this name.
        See Also:
        getName(), getName(NamedObj)
      • setPersistent

        public void setPersistent​(boolean persistent)
        Set the persistence of this object. If the persistence is not specified with this method, then by default the object will be persistent unless it is derivable by derivation from a class. A persistent object has a non-empty MoML description that can be used to re-create the object. To make an instance non-persistent, call this method with the argument false. To force it to always be persistent, irrespective of its relationship to a class, then call this with argument true. Note that this will have the additional effect that it no longer inherits properties from the class, so in effect, calling this with true overrides values given by the class.
        Specified by:
        setPersistent in interface MoMLExportable
        Parameters:
        persistent - False to make this object non-persistent.
        See Also:
        isPersistent(), MoMLExportable
      • setSource

        public void setSource​(java.lang.String source)
        Set the source, which gives an external URL associated with an entity (presumably from which the entity was defined). This becomes the value in the "source" attribute of exported MoML. Call this with null to prevent any source attribute from being generated.
        Specified by:
        setSource in interface MoMLExportable
        Parameters:
        source - The source, or null if there is none.
        See Also:
        getSource(), MoMLExportable
      • sortContainedObjects

        public java.util.List sortContainedObjects​(java.util.Collection filter)
        Return an ordered list of contained objects filtered by the specified filter. The attributes are listed first, followed by ports, classes, entities, and relations, in that order. Within each category, objects are listed in the order they were created (or as later modified by methods like moveDown()). The filter gives a collection of objects to include. Only objects contained by the filter are included.
        Parameters:
        filter - A collection specifying which objects to include in the returned list.
        Returns:
        A list of contained instances of NamedObj that are in the specified filter, or an empty list if there are none.
      • toString

        public java.lang.String toString()
        Return the class name and the full name of the object, with syntax "className {fullName}".
        Overrides:
        toString in class java.lang.Object
        Returns:
        The class name and the full name.
      • toplevel

        public NamedObj toplevel()
        Return the top level of the containment hierarchy.
        Returns:
        The top level, or this if this has no container.
      • 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. In derived classes, this should be overridden so that the returned name is guaranteed to not conflict with any contained object. 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.
        Parameters:
        prefix - A prefix for the name.
        Returns:
        A unique name, which will be exactly the prefix if possible, or the prefix extended by a number.
      • validateSettables

        public void validateSettables()
                               throws IllegalActionException
        Validate attributes deeply contained by this object if they implement the Settable interface by calling their validate() method. Errors that are triggered by this validation are handled by calling handleModelError(). Normally this should be called after constructing a model or after making changes to it. It is called, for example, by the MoMLParser.
        Throws:
        IllegalActionException - If there is a problem validating the deeply contained attributes.
        See Also:
        handleModelError(NamedObj context, IllegalActionException exception)
      • workspace

        public final Workspace workspace()
        Get the workspace. This method never returns null, since there is always a workspace.
        Returns:
        The workspace responsible for this object.
      • _addAttribute

        protected void _addAttribute​(Attribute attribute)
                              throws NameDuplicationException,
                                     IllegalActionException
        Add an attribute. This method should not be used directly. Instead, call setContainer() on the attribute. Derived classes may further constrain the class of the attribute. To do this, they should override this method to throw an exception when the argument is not an instance of the expected class.

        This method is write-synchronized on the workspace and increments its version number.

        Parameters:
        attribute - The attribute to be added.
        Throws:
        NameDuplicationException - If this object already has an attribute with the same name.
        IllegalActionException - If the attribute is not an an instance of the expect class (in derived classes).
      • _adjustOverride

        protected void _adjustOverride​(int depth)
        Adjust the _override field of this object, if there is one, by incrementing the value at the specified depth by one, and do the same for all contained objects, with one larger depth.
        Parameters:
        depth - The depth.
      • _attachText

        protected void _attachText​(java.lang.String name,
                                   java.lang.String text)
        Attach the specified text as an attribute with the specified name. This is a convenience method (syntactic sugar) that creates an instance of TransientSingletonConfigurableAttribute and configures it with the specified text. This attribute is transient, meaning that it is not described by exported MoML. Moreover, it is a singleton, meaning that it will replace any previously contained instance of SingletonAttribute that has the same name.

        Note that attribute names beginning with an underscore "_" are reserved for system use. This method is used in several places to set the value of such attributes.

        Parameters:
        name - The name of the attribute.
        text - The text with which to configure the attribute.
      • _cloneFixAttributeFields

        protected void _cloneFixAttributeFields​(NamedObj newObject)
                                         throws java.lang.CloneNotSupportedException
        Fix the fields of the given object which point to Attributes. The object is assumed to be a clone of this one. The fields are fixed to point to the corresponding attribute of the clone, instead of pointing to attributes of this object.
        Parameters:
        newObject - The object in which we fix the fields.
        Throws:
        java.lang.CloneNotSupportedException - If there is a problem getting the attribute
      • _containedDecorators

        protected java.util.List<Decorator> _containedDecorators()
        Return a list of decorators contained by this object. In this base class, this list consists of Attributes that implement the Decorator interface. In subclasses, it can contain other objects that implement the Decorator interface, such as Entities.
        Returns:
        A list of contained decorators.
      • _copyChangeRequestList

        protected java.util.List<ChangeRequest> _copyChangeRequestList()
        Return a copy of the current list of change requests, or return null if there aren't any pending change requests.
        Returns:
        A copy of the change request list, or null if there aren't any.
      • _debug

        protected final void _debug​(DebugEvent event)
        Send a debug event to all debug listeners that have registered.
        Parameters:
        event - The event.
      • _debug

        protected final void _debug​(java.lang.String message)
        Send a debug message to all debug listeners that have registered. By convention, messages should not include a newline at the end. The newline will be added by the listener, if appropriate.
        Parameters:
        message - The message.
      • _debug

        protected final void _debug​(java.lang.String part1,
                                    java.lang.String part2)
        Send a debug message to all debug listeners that have registered. The message is a concatenation of the two parts, with a space between them. By convention, messages should not include a newline at the end. The newline will be added by the listener, if appropriate.
        Parameters:
        part1 - The first part of the message.
        part2 - The second part of the message.
      • _debug

        protected final void _debug​(java.lang.String part1,
                                    java.lang.String part2,
                                    java.lang.String part3)
        Send a debug message to all debug listeners that have registered. The message is a concatenation of the three parts, with a space between them. By convention, messages should not include a newline at the end. The newline will be added by the listener, if appropriate.
        Parameters:
        part1 - The first part of the message.
        part2 - The second part of the message.
        part3 - The third part of the message.
      • _debug

        protected final void _debug​(java.lang.String part1,
                                    java.lang.String part2,
                                    java.lang.String part3,
                                    java.lang.String part4)
        Send a debug message to all debug listeners that have registered. The message is a concatenation of the four parts, with a space between them. By convention, messages should not include a newline at the end. The newline will be added by the listener, if appropriate.
        Parameters:
        part1 - The first part of the message.
        part2 - The second part of the message.
        part3 - The third part of the message.
        part4 - The fourth part of the message.
      • _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 this class (NamedObj). Lines are indented according to to the level argument using the static 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.
        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 - Not thrown in this base class, but derived classes could throw an exception if there is a problem accessing subcomponents of this object.
      • _executeChangeRequests

        protected void _executeChangeRequests​(java.util.List<ChangeRequest> changeRequests)
        Execute the specified list of change requests.
        Parameters:
        changeRequests - The list of change requests to execute.
      • _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 base class is the attributes. This method is called by exportMoML(). If there are attributes, then each attribute description is indented according to the specified depth and terminated with a newline character. Callers of this method should hold read access before calling this method. Note that exportMoML() does this for us.
        Parameters:
        output - The output stream to write to.
        depth - The depth in the hierarchy, to determine indenting.
        Throws:
        java.io.IOException - If an I/O error occurs.
        See Also:
        exportMoML(Writer, int)
      • _getContainedObject

        protected NamedObj _getContainedObject​(NamedObj container,
                                               java.lang.String relativeName)
                                        throws IllegalActionException
        Get an object with the specified name in the specified container. The type of object sought is an instance of the same class as this object. In this base class, return null, as there is no containment mechanism. Derived classes should override this method to return an object of their same type.
        Parameters:
        relativeName - The name relative to the container.
        container - The container expected to contain the object.
        Returns:
        null.
        Throws:
        IllegalActionException - If the object exists and has the wrong class. Not thrown in this base class.
      • _getIndentPrefix

        protected static java.lang.String _getIndentPrefix​(int level)
        Return a number of spaces that is proportional to the argument. If the argument is negative or zero, return an empty string.
        Parameters:
        level - The level of indenting represented by the spaces.
        Returns:
        A string with zero or more spaces.
      • _isMoMLSuppressed

        protected boolean _isMoMLSuppressed​(int depth)
        Return true if describing this class in MoML is redundant. This will return true if setPersistent() has been called with argument false, irrespective of other conditions. If setPersistent() has not been called, or has been called with argument true, then things are more complicated. If the depth argument is 0 or if this object is not derived, then this method returns false, indicating that MoML should be exported. Otherwise, whether to export MoML depends on whether the MoML specifies information that should be created by propagation rather than explicitly represented in MoML. If this is a derived object, then whether its information can be created by propagation depends on whether the object from which that propagation would occur is included in the MoML, which depends on the depth argument. This method uses the depth argument to determine whether the exported MoML both contains an object that implies the existence of this object and contains an object that implies the value of this object. If both conditions are satisfied, then it returns false. Finally, if we haven't already returned false, then check all the contained objects, and if any of them requires a MoML description, then return false. Otherwise, return true.
        Parameters:
        depth - The depth of the requested MoML.
        Returns:
        Return true to suppress MoML export.
      • _markContentsDerived

        protected void _markContentsDerived​(int depth)
        Mark the contents of this object as being derived objects. Specifically, the derivation depth of the immediately contained objects is set to one greater than the depth argument, and then this method is called on that object with an argument one greater than the depth argument. For the contained objects, this will also cancel any previous call to setPersistent(true), since it's a derived object.
        Parameters:
        depth - The derivation depth for this object, which should be 0 except on recursive calls.
        See Also:
        setDerivedLevel(int)
      • _propagateExistence

        protected NamedObj _propagateExistence​(NamedObj container)
                                        throws IllegalActionException
        Propagate existence of this object to the specified object. The specified object is required to be an instance of the same class as the container of this one, or an exception will be thrown. In this base class, this object is cloned, and its name is set to the same as this object. Derived classes with a setContainer() method are responsible for ensuring that this returned object has its container set to the specified container. This base class ensures that the returned object is in the same workspace as the container.

        NOTE: Any object that creates objects in its constructor that it does not contain must override this method and call propagateExistence() on those objects. Otherwise, those objects will not be propagated to subclasses or instances when this object is contained by a class definition. See PortParameter for an example.

        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.
      • _propagateValue

        protected void _propagateValue​(NamedObj destination)
                                throws IllegalActionException
        Propagate the value of this object (if any) to the specified object. The specified object is required to be an instance of the same class as this one, or an exception will be thrown. In this base class, there is no value, and so nothing needs to be done. Derived classes that have values should override this method.
        Parameters:
        destination - Object to which to propagate the value.
        Throws:
        IllegalActionException - If the value cannot be propagated.
      • _removeAttribute

        protected void _removeAttribute​(Attribute param)
        Remove the given attribute. If there is no such attribute, do nothing. This method is write-synchronized on the workspace and increments its version. It should only be called by setContainer() in Attribute.
        Parameters:
        param - The attribute to be removed.
      • removeAttribute

        public void removeAttribute​(Attribute param)
        Remove attribute from list of attributes.
        Parameters:
        param - Attribute to remove.
      • _splitName

        protected static final java.lang.String[] _splitName​(java.lang.String name)
        Split the specified name at the first period and return the two parts as a two-element array. If there is no period, the second element is null.
        Parameters:
        name - The name to split.
        Returns:
        The name before and after the first period as a two-element array.
      • _stripNumericSuffix

        protected static java.lang.String _stripNumericSuffix​(java.lang.String string)
        Return a string that is identical to the specified string except any trailing digits are removed.
        Parameters:
        string - The string to strip of its numeric suffix.
        Returns:
        A string with no numeric suffix.
      • _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. Errors that are triggered by this validation are handled by calling handleModelError().
        Parameters:
        attributesValidated - A collection of Settables that have already been validated. For example, Settables that implement the ShareableSettable interface are validated only once.
        Throws:
        IllegalActionException - If there is a problem validating the deeply contained attributes.
        See Also:
        handleModelError(NamedObj context, IllegalActionException exception)