ptolemy.moml
Class EntityLibrary

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.kernel.CompositeEntity
                      ptolemy.moml.EntityLibrary

All Implemented Interfaces:

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

public class EntityLibrary
extends CompositeEntity
implements LazyComposite

This class provides a hierarchical library of components specified in MoML. The contents are typically specified via the configure() method, which is passed MoML code. The MoML is evaluated lazily; i.e. it is not actually evaluated until there is a request for its contents, via a call to getEntity(), numEntities(), entityList(), or any related method. You can also force evaluation of the MoML by calling populate(). When you export MoML for this object, the MoML description of the contents is wrapped in a configure element. This object contains an attribute with name "_libraryMarker", which marks it as a library. This is used by the library browser in vergil to know to expand the composite entity.

The contents of the library can be entities, ports, relations, or attributes. I.e., it can contain anything contained by a CompositeEntity. An attempt to access any of these will trigger populating the library.

The configure method can be given a URL or MoML text or both. If it is given MoML text, that text will normally be wrapped in a processing instruction, as follows:

 <?moml
 
 ... MoML elements giving library contents ...
 
 ?>
 

The processing instruction, which is enclosed in "<?" and "?>" prevents premature evaluation of the MoML. The processing instruction has a target, "moml", which specifies that it contains MoML code. The keyword "moml" in the processing instruction must be exactly as above, or the entire processing instruction will be ignored. The populate() method strips off the processing instruction and evaluates the MoML elements. The group element allows the library contents to be given as a set of elements (the MoML parser requires that there always be a single top-level element, which in this case will be the group element).

One subtlety in using this class arises because of a problem typical of lazy evaluation. A number of exceptions may be thrown because of errors in the MoML code when the MoML code is evaluated. However, since that code is evaluated lazily, it is evaluated in a context where these exceptions are not expected. There is no completely clean solution to this problem; our solution is to translate all exceptions to runtime exceptions in the populate() method. This method, therefore, violates the condition for using runtime exceptions in that the condition that causes these exceptions to be thrown is not a testable precondition.

A second subtlety involves cloning. When this class is cloned, if the configure MoML text has not yet been evaluated, then the clone is created with the same (unevaluated) MoML text, rather than being populated with the contents specified by that text. If the object is cloned after being populated, the clone will also be populated.

A third subtlety involves the doc element. Unfortunately, MoML semantics define the doc element to replace any previously existing doc elements. But to find out whether there is any previously existing doc element, the MoML parser calls getAttribute, which has the effect of populating the library. Thus, doc elements should go inside the group, not outside. For example, the following organization results in no deferred evaluation:

 <entity name="director library" class="ptolemy.moml.EntityLibrary">
 <doc>default director library</doc>
 <configure>
 <?moml
 <group>
 ...
 </group>
 ?>
 </configure>
 </entity>
 

The following, by contrast, is OK:

 <entity name="director library" class="ptolemy.moml.EntityLibrary">
 <configure>
 <?moml
 <group>
 <doc>default director library</doc>
 ...
 </group>
 ?>
 </configure>
 </entity>
 

Since:

Ptolemy II 1.0

Version:

$Id: EntityLibrary.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Red (bilung)

Proposed Rating:

Red (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.CompositeEntity

CompositeEntity.ContainedObjectsIterator

Field Summary

private java.net.URL	_base The base specified by the configure() method.
private boolean	_cloning Indicate that we are cloning.
private boolean	_configureDone Indicate whether data given by configure() has been processed.
private java.lang.String	_configureSource URL specified to the configure() method.
private java.lang.String	_configureText Text specified to the configure() method.
private boolean	_populated Flag indicating populate() has been called, and hence the configuration should be obtained from the current contents (in case they have changed) rather than from the _configureText.
private boolean	_populating Indicator that we are in the midst of populating.

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

EntityLibrary()
Construct a library in the default workspace with no container and an empty string as its name.

EntityLibrary(CompositeEntity container, java.lang.String name)
Construct a library with the given container and name.

EntityLibrary(Workspace workspace)
Construct a library in the specified workspace with no container and an empty string as a name.

Method Summary

protected void	_attachText(java.lang.String name, java.lang.String text) Override the base class to prevent triggering a populate() call when this occurs.
protected void	_exportMoMLContents(java.io.Writer output, int depth) Write a MoML description of the contents of this object, wrapped in a configure element.
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.
java.util.List	classDefinitionList() List the contained class definitions in the order they were added (using their setContainer() method).
java.lang.Object	clone(Workspace workspace) Clone the library into the specified workspace.
void	configure(java.net.URL base, java.lang.String source, java.lang.String text) Specify the library contents by giving either a URL (the source argument), or by directly giving the MoML text (the text argument), or both.
boolean	deepContains(NamedObj inside) Return true if this object contains the specified object, directly or indirectly.
java.util.List	deepEntityList() List the opaque entities that are directly or indirectly contained by this entity.
java.util.List	entityList() List the contained entities in the order they were added (using their setContainer() method).
Attribute	getAttribute(java.lang.String name) Get the attribute with the given name.
java.lang.String	getConfigureSource() Return the input source that was specified the last time the configure method was called.
java.lang.String	getConfigureText() Return the text string that represents the current configuration of this object.
ComponentEntity	getEntity(java.lang.String name) Get a contained entity by name.
java.util.Iterator	lazyContainedObjectsIterator() Override the base class to prevent populating.
int	numberOfEntities() Return the number of contained entities.
void	populate() Populate the actor by reading the file specified by the source parameter.

Methods inherited from class ptolemy.kernel.CompositeEntity

_addEntity, _addRelation, _adjustDeferrals, _deepOpaqueEntityList, _description, _finishedAddEntity, _recordDecoratedAttributes, _removeEntity, _removeRelation, _validateSettables, allAtomicEntityList, allCompositeEntityList, allowLevelCrossingConnect, connect, connect, containedObjectsIterator, deepGetEntities, deepOpaqueEntityList, deepRelationSet, entityList, exportLinks, exportMoML, getEntities, getPort, getRelation, getRelations, isAtomic, isOpaque, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, newRelation, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, setContainer, statistics, uniqueName

Methods inherited from class ptolemy.kernel.ComponentEntity

_addPort, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, newPort, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_removePort, connectedPortList, connectedPorts, connectionsChanged, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeTypeChanged, clone, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getDisplayName, getFullName, getName, getName

Field Detail

_base

private java.net.URL _base

The base specified by the configure() method.

_cloning

private boolean _cloning

Indicate that we are cloning.

_configureDone

private boolean _configureDone

Indicate whether data given by configure() has been processed.

_configureSource

private java.lang.String _configureSource

URL specified to the configure() method.

_configureText

private java.lang.String _configureText

Text specified to the configure() method.

_populated

private boolean _populated

Flag indicating populate() has been called, and hence the configuration should be obtained from the current contents (in case they have changed) rather than from the _configureText.

_populating

private boolean _populating

Indicator that we are in the midst of populating.

Constructor Detail

EntityLibrary

public EntityLibrary()

Construct a library in the default workspace with no container and an empty string as its name. Add the library to the workspace directory. Increment the version number of the workspace.

EntityLibrary

public EntityLibrary(Workspace workspace)

Construct a library in the specified workspace with no container and an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. Add the actor to the workspace directory. Increment the version number of the workspace.

Parameters:

workspace - The workspace that will list the actor.

EntityLibrary

public EntityLibrary(CompositeEntity container,
                     java.lang.String name)
              throws NameDuplicationException,
                     IllegalActionException

Construct a library with the given container and name.

Parameters:

container - The container.

name - The name of this library.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

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 overrides the base class to first populate the library, if necessary, by calling populate(). This method is read-synchronized on the workspace.

Overrides:

attributeList in class NamedObj

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 overrides the base class to first populate the library, if necessary, by calling populate(). This method is read-synchronized on the workspace.

Overrides:

attributeList in class NamedObj

Parameters:

filter - The class of attribute of interest.

Returns:

A list of instances of specified class.

clone

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

Clone the library 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). If the library has not yet been populated, then the clone will also not have been populated.

Overrides:

clone in class CompositeEntity

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new EntityLibrary.

Throws:

java.lang.CloneNotSupportedException - If the library contains level crossing transitions so that its connections cannot be cloned, or if one of the attributes cannot be cloned.

See Also:

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

configure

public void configure(java.net.URL base,
                      java.lang.String source,
                      java.lang.String text)

Specify the library contents by giving either a URL (the source argument), or by directly giving the MoML text (the text argument), or both. The MoML is evaluated when the populate() method is called. This occurs lazily, when there is a request for the contents of the library.

Specified by:

configure in interface Configurable

Parameters:

base - The base relative to which references within the input are found, or null if this is not known, or there is none.

source - The input source, which specifies a URL, or null if none.

text - Configuration information given as text, or null if none.

classDefinitionList

public java.util.List classDefinitionList()

List the contained class definitions in the order they were added (using their setContainer() method). The returned list is static in the sense that it is not affected by any subsequent additions or removals of entities. This overrides the base class to first populate the library, if necessary, by calling populate(). Note that this may result in a runtime exception being thrown (if there is an error evaluating the MoML). This method is read-synchronized on the workspace.

Overrides:

classDefinitionList in class CompositeEntity

Returns:

An unmodifiable list of ComponentEntity objects.

See Also:

CompositeEntity.entityList()

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.

Overrides:

deepContains in class NamedObj

Parameters:

inside - The NamedObj that is searched for.

Returns:

True if this contains the argument, directly or indirectly.

See Also:

CompositeEntity.isAtomic()

deepEntityList

public java.util.List deepEntityList()

List the opaque entities that are directly or indirectly contained by this entity. The list will be empty if there are no such contained entities. This overrides the base class to first populate the library, if necessary, by calling populate(). Note that this may result in a runtime exception being thrown (if there is an error evaluating the MoML). This method is read-synchronized on the workspace.

Overrides:

deepEntityList in class CompositeEntity

Returns:

A list of opaque ComponentEntity objects.

See Also:

CompositeEntity.classDefinitionList(), CompositeEntity.allAtomicEntityList()

entityList

public java.util.List entityList()

List the contained entities in the order they were added (using their setContainer() method). The returned list is static in the sense that it is not affected by any subsequent additions or removals of entities. This overrides the base class to first populate the library, if necessary, by calling populate(). Note that this may result in a runtime exception being thrown (if there is an error evaluating the MoML). This method is read-synchronized on the workspace.

Overrides:

entityList in class CompositeEntity

Returns:

An unmodifiable list of ComponentEntity objects.

See Also:

CompositeEntity.classDefinitionList()

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. This overrides the base class to first populate the library, if necessary, by calling populate(). This method is read-synchronized on the workspace.

Overrides:

getAttribute in class CompositeEntity

Parameters:

name - The name of the desired attribute.

Returns:

The requested attribute if it is found, null otherwise.

getEntity

public ComponentEntity getEntity(java.lang.String name)

Get a contained entity by name. The name may be compound, with fields separated by periods, in which case the entity returned is contained by a (deeply) contained entity. This overrides the base class to first populate the library, if necessary, by calling populate(). Note that this may result in a runtime exception being thrown (if there is an error evaluating the MoML). This method is read-synchronized on the workspace.

Overrides:

getEntity in class CompositeEntity

Parameters:

name - The name of the desired entity.

Returns:

An entity with the specified name, or null if none exists.

getConfigureSource

public java.lang.String getConfigureSource()

Return the input source that was specified the last time the configure method was called.

Specified by:

getConfigureSource in interface Configurable

Returns:

The string representation of the input URL, or null if the no source has been used to configure this object, or null if no external source need be used to configure this object.

getConfigureText

public java.lang.String getConfigureText()

Return the text string that represents the current configuration of this object. Note that any configuration that was previously specified using the source attribute need not be represented here as well.

Specified by:

getConfigureText in interface Configurable

Returns:

A configuration string, or null if no configuration has been used to configure this object, or null if no configuration string need be used to configure this object.

lazyContainedObjectsIterator

public java.util.Iterator lazyContainedObjectsIterator()

Override the base class to prevent populating.

Overrides:

lazyContainedObjectsIterator in class NamedObj

Returns:

An iterator over instances of NamedObj contained by this object.

numberOfEntities

public int numberOfEntities()

Return the number of contained entities. This overrides the base class to first populate the library, if necessary, by calling populate(). Note that this may result in a runtime exception being thrown (if there is an error evaluating the MoML). This method is read-synchronized on the workspace.

Overrides:

numberOfEntities in class CompositeEntity

Returns:

The number of entities.

populate

public void populate()
              throws InvalidStateException

Populate the actor by reading the file specified by the source parameter. Note that the exception thrown here is a runtime exception, inappropriately. This is because execution of this method is deferred to the last possible moment, and it is often evaluated in a context where a compile-time exception cannot be thrown. Thus, extra care should be exercised to provide valid MoML specifications.

Throws:

InvalidStateException - If the source cannot be read, or if an exception is thrown parsing its MoML data.

_attachText

protected void _attachText(java.lang.String name,
                           java.lang.String text)

Override the base class to prevent triggering a populate() call when this occurs.

Overrides:

_attachText in class NamedObj

Parameters:

name - The name of the attribute.

text - The text with which to configure the attribute.

_exportMoMLContents

protected void _exportMoMLContents(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException

Write a MoML description of the contents of this object, wrapped in a configure element. This is done by first populating the model, and then exporting its contents into a configure element. This method is called by exportMoML(). Each description is indented according to the specified depth and terminated with a newline character.

Overrides:

_exportMoMLContents in class CompositeEntity

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:

NamedObj.exportMoML(Writer, int)