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 {@link #getAttribute(String)}, {@link #getAttribute(String,Class)}, {@link #attributeList()}and {@link #attributeList(Class)} methods.Classes derived from NamedObj may constrain attributes to be a subclass of Attribute. To do that, they should override the protected {@link #_addAttribute(Attribute)} method to throw an exception ifthe 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 {@link #requestChange(ChangeRequest)} method. By default, whena change is requested, the change is executed immediately. However, by calling {@link #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. @author Mudit Goel, Edward A. Lee, Neil Smyth @version $Id: NamedObj.java,v 1.335 2007/12/07 06:24:44 cxh Exp $ @since Ptolemy II 0.2 @Pt.ProposedRating Green (eal) @Pt.AcceptedRating Green (cxh) @see Attribute @see Workspace
| |