ptolemy.kernel.util
Class NamedObj

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

All Implemented Interfaces:

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

Direct Known Subclasses:

Attribute, CodeGeneratorHelper, InstantiableNamedObj, Manager, ODESolver, Port, Relation

public class NamedObj
extends java.lang.Object
implements Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, MoMLExportable, ModelErrorHandler, Moveable, java.io.Serializable

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 DecoratedAttributes. These are attributes that are added by another NamedObj, called a decorator to this NamedObj. An example is for example a code generator. This one has specific attributes for for example the generated code of the director in a model. These attributes are added by the Decorator (the code generator), to the director ("this" object). These attributes are stored seperately and can be retrieved by using getDecoratorAttributes(Decorator) or getDecoratorAttribute(Decorator, String).

Since:

Ptolemy II 0.2

Version:

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

Author:

Mudit Goel, Edward A. Lee, Neil Smyth, Contributor: Bert Rodiers

See Also:

Attribute, Workspace, Serialized Form

Accepted Rating:

Green (cxh)

Proposed Rating:

Green (eal)

Nested Class Summary

protected class	NamedObj.ContainedObjectsIterator This class is an iterator over all the contained objects (all instances of NamedObj).
private static class	NamedObj.SerializableObject Serializable version of the Java Object class.

Field Summary

(package private) NamedList	_attributes The Attributes attached to this object.
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.
private java.lang.String	_className The class name for MoML exports.
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.
private java.util.Map<Decorator,DecoratedAttributes>	_decoratedAttributes The decorated attributes decorated by a certain decorator.
private static Workspace	_DEFAULT_WORKSPACE Instance of a workspace that can be used if no other is specified.
private boolean	_deferChangeRequests Flag indicating that we should not immediately execute a change request.
private int	_derivedLevel
private java.lang.String	_displayName The display name, if set.
protected java.lang.String	_elementName The MoML element name.
private java.lang.String	_fullNameCache
private long	_fullNameVersion
protected java.lang.Boolean	_isPersistent Boolean variable to indicate the persistence of the object.
private ModelErrorHandler	_modelErrorHandler
private java.lang.String	_name The name
private java.util.List<java.lang.Integer>	_override List indicating whether and how this derived object has been modified.
private java.lang.String	_source The value for the source MoML attribute.
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

	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

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 void	_debug(DebugEvent event) Send a debug event to all debug listeners that have registered.
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 java.lang.String	_description(int detail, int indent, int bracket) Return a description of the object.
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.
private java.util.List<NamedObj>	_getDerivedList(java.util.Collection<NamedObj> visited, boolean propagate, boolean force, NamedObj context, int depth, java.util.List<java.lang.Integer> override, java.lang.String relativeName) Return a list of derived objects.
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.
private boolean	_isShadowed(java.util.List<java.lang.Integer> candidate, java.util.List<java.lang.Integer> changer) Return true if the first argument (an _override list) indicates that the object owning that override list should be shadowed relative to a change made via the path defined by the second override list.
protected void	_markContentsDerived(int depth) Mark the contents of this object as being derived objects.
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	_recordDecoratedAttributes(DecoratedAttributes attributes) Record decorated attributes to store at the level of the container of the decorator.
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	attributeChanged(Attribute attribute) React to a change in an attribute.
java.util.List	attributeList() Return a list of the attributes contained by this object.
java.util.List	attributeList(java.lang.Class 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.
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.
java.lang.String	exportMoML(java.lang.String name) Get a MoML description of this object with its name replaced by the specified name.
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	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 decorated attribute with the given name for the decorator.
DecoratedAttributes	getDecoratorAttributes(Decorator decorator) Return the decorated attributes of this Named Object, decorated by 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.
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	removeChangeListener(ChangeListener listener) Remove a change listener.
void	removeDebugListener(DebugListener listener) Unregister a debug listener.
void	requestChange(ChangeRequest change) Request that the given change be executed.
void	setClassName(java.lang.String name) Set the MoML class name.
boolean	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.

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

_attributes

NamedList _attributes

The Attributes attached to this object.

_className

private java.lang.String _className

The class name for MoML exports.

_decoratedAttributes

private java.util.Map<Decorator,DecoratedAttributes> _decoratedAttributes

The decorated attributes decorated by a certain decorator.

_DEFAULT_WORKSPACE

private static Workspace _DEFAULT_WORKSPACE

Instance of a workspace that can be used if no other is specified.

_deferChangeRequests

private transient boolean _deferChangeRequests

Flag indicating that we should not immediately execute a change request.

_derivedLevel

private int _derivedLevel

_displayName

private java.lang.String _displayName

The display name, if set.

_fullNameCache

private java.lang.String _fullNameCache

_fullNameVersion

private long _fullNameVersion

_modelErrorHandler

private ModelErrorHandler _modelErrorHandler

_name

private java.lang.String _name

The name

_override

private java.util.List<java.lang.Integer> _override

List indicating whether and how this derived object has been modified.

_source

private java.lang.String _source

The value for the source MoML attribute.

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)

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

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 java.util.List attributeList(java.lang.Class 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.

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.

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

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

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

executeChangeRequests

public void executeChangeRequests()

Execute previously requested changes. If there is a container, then delegate the request to the container. Otherwise, this method will execute all pending changes (even if isDeferringChangeRequests() returns true. Listeners will be notified of success or failure.

Specified by:

executeChangeRequests in interface Changeable

See Also:

addChangeListener(ChangeListener), requestChange(ChangeRequest), isDeferringChangeRequests(), Changeable

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

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.

getDecoratorAttributes

public DecoratedAttributes getDecoratorAttributes(Decorator decorator)

Return the decorated attributes of this Named Object, decorated by decorator. DecoratedAttributes are attributes that have been added by calling _addAttribute(Attribute). If the DecoratedAttributes for this NamedObj do not contain the decorated named by the decorator parameter, then the a DecoratedAttribute is created, see Decorator.createDecoratedAttributes(NamedObj).

Parameters:

decorator - The decorator.

Returns:

The decorated attributes.

getDecoratorAttribute

public Attribute getDecoratorAttribute(Decorator decorator,
                                       java.lang.String name)

Return the decorated attribute with the given name for the decorator. Return null if the attribute cannot be found.

Parameters:

decorator - The decorator.

name - The name of the attribute.

Returns:

The attribute with the given name for the decorator. .

See Also:

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.

getModelErrorHandler

public ModelErrorHandler getModelErrorHandler()

Get the model error handler specified by setErrorHandler().

Returns:

The error handler, or null if none.

See Also:

setModelErrorHandler(ModelErrorHandler handler)

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.

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.

removeChangeListener

public void removeChangeListener(ChangeListener listener)

Remove a change listener. If there is a container, delegate the request to the container. If the specified listener is not on the list of listeners, do nothing.

Specified by:

removeChangeListener in interface Changeable

Parameters:

listener - The listener to remove.

See Also:

addChangeListener(ChangeListener), Changeable

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)

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

Returns:

True if this object was previously deferring 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 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.

If the attribute is an instance of DecoratedAttributes, then it is added to the Map of decorators for this NamedObj. The key in the map is the Decorator for the attribute, the value is the attribute. The DecoratedAttribute may be read using getDecoratorAttributes(Decorator) or getDecoratorAttribute(Decorator, String).

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

_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

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

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.

_recordDecoratedAttributes

protected void _recordDecoratedAttributes(DecoratedAttributes attributes)

Record decorated attributes to store at the level of the container of the decorator.

Parameters:

attributes - The decorated attributes.

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

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

_getDerivedList

private java.util.List<NamedObj> _getDerivedList(java.util.Collection<NamedObj> visited,
                                                 boolean propagate,
                                                 boolean force,
                                                 NamedObj context,
                                                 int depth,
                                                 java.util.List<java.lang.Integer> override,
                                                 java.lang.String relativeName)
                                          throws IllegalActionException

Return a list of derived objects. If the propagate argument is true, then this list will contain only those derived objects whose values are not overridden and that are not shadowed by objects whose values are overridden. Also, if that argument is true, then the value of this object is propagated to those returned objects during the construction of the list. This method is read-synchronized on the workspace. If the force argument is true, then if an expected derived object does not exist, then it is created by calling the _propagateExistence() protected method.

Parameters:

visited - A set of objects that have previously been visited. This should be non-null only on the recursive calls to this method.

propagate - True to propagate the value of this object (if any) to derived objects that have not been overridden while the list is being constructed.

force - Force derived objects to exist where they should be if they do not already exist.

context - The context (this except in recursive calls).

depth - The depth (0 except in recursive calls).

relativeName - The name of the object relative to the context (null except in recursive calls).

override - The list of override breadths (one per depth). If propagate is true, then this should be a list with a single Integer 0 for outside callers, and otherwise it should be null.

Returns:

A list of instances of the same class as this object which are derived from this object. The list is empty in this base class, but subclasses that override _getContainedObject() can return non-empty lists.

Throws:

IllegalActionException - If propagate is true and propagation fails.

_isShadowed

private boolean _isShadowed(java.util.List<java.lang.Integer> candidate,
                            java.util.List<java.lang.Integer> changer)

Return true if the first argument (an _override list) indicates that the object owning that override list should be shadowed relative to a change made via the path defined by the second override list.

Parameters:

candidate - The override list of the candidate for a change.

changer - The override list for a path for the change.

Returns:

True if the candidate is shadowed.