public class EntityLibrary extends CompositeEntity implements LazyComposite, Librariable
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 <group>[ ... MoML elements giving library contents ... </group> ?>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>
CompositeEntity.ContainedObjectsIterator
Modifier and Type | Field and Description |
---|---|
protected java.net.URL |
_base
The base specified by the configure() method.
|
protected boolean |
_cloning
Indicate that we are cloning.
|
protected boolean |
_configureDone
Indicate whether data given by configure() has been processed.
|
protected java.lang.String |
_configureSource
URL specified to the configure() method.
|
protected java.lang.String |
_configureText
Text specified to the configure() method.
|
protected 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.
|
protected boolean |
_populating
Indicator that we are in the midst of populating.
|
_levelCrossingLinks
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
_addEntity, _addRelation, _adjustDeferrals, _containedDecorators, _deepOpaqueEntityList, _description, _finishedAddEntity, _removeEntity, _removeRelation, _validateSettables, allAtomicEntityList, allowLevelCrossingConnect, connect, connect, containedObjectsIterator, deepCompositeEntityList, deepGetEntities, deepNamedObjList, deepOpaqueEntityList, deepRelationSet, entityList, exportLinks, exportMoML, getEntities, getPort, getRelation, getRelations, isAtomic, isOpaque, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyAllCompositeTransparentAndOpaqueEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, newRelation, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, setContainer, statistics, uniqueName
_checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, newPort, propagateExistence, setName
_addPort, _removePort, connectedPortList, connectedPorts, connectionsChanged, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts
_setParent, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition
_addAttribute, _adjustOverride, _cloneFixAttributeFields, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeChanged, attributeDeleted, attributeTypeChanged, clone, decorators, 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, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getDerivedLevel, getDerivedList, propagateValue
description, getDisplayName, getFullName, getName, getName
protected java.net.URL _base
protected boolean _cloning
protected boolean _configureDone
protected java.lang.String _configureSource
protected java.lang.String _configureText
protected boolean _populated
protected boolean _populating
public EntityLibrary()
public EntityLibrary(Workspace workspace)
workspace
- The workspace that will list the actor.public EntityLibrary(CompositeEntity container, java.lang.String name) throws NameDuplicationException, IllegalActionException
container
- The container.name
- The name of this library.IllegalActionException
- If the entity cannot be contained
by the proposed container.NameDuplicationException
- If the container already has an
actor with this name.public java.util.List attributeList()
attributeList
in class NamedObj
public java.util.List attributeList(java.lang.Class filter)
attributeList
in class NamedObj
filter
- The class of attribute of interest.public java.lang.Object clone(Workspace workspace) throws java.lang.CloneNotSupportedException
clone
in class CompositeEntity
workspace
- The workspace for the cloned object.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.NamedObj.exportMoML(Writer, int, String)
,
NamedObj.setDeferringChangeRequests(boolean)
public void configure(java.net.URL base, java.lang.String source, java.lang.String text)
configure
in interface Configurable
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.public java.util.List classDefinitionList()
classDefinitionList
in class CompositeEntity
CompositeEntity.entityList()
public boolean deepContains(NamedObj inside)
deepContains
in class NamedObj
inside
- The NamedObj that is searched for.CompositeEntity.isAtomic()
public java.util.List deepEntityList()
deepEntityList
in class CompositeEntity
CompositeEntity.classDefinitionList()
,
CompositeEntity.allAtomicEntityList()
public java.util.List entityList()
entityList
in class CompositeEntity
CompositeEntity.classDefinitionList()
public Attribute getAttribute(java.lang.String name)
getAttribute
in class CompositeEntity
name
- The name of the desired attribute.public ComponentEntity getEntity(java.lang.String name)
getEntity
in class CompositeEntity
name
- The name of the desired entity.public java.lang.String getConfigureSource()
getConfigureSource
in interface Configurable
public java.lang.String getConfigureText()
getConfigureText
in interface Configurable
public java.util.Iterator lazyContainedObjectsIterator()
lazyContainedObjectsIterator
in class NamedObj
public int numberOfEntities()
numberOfEntities
in class CompositeEntity
public void populate() throws InvalidStateException
populate
in interface LazyComposite
InvalidStateException
- If the source cannot be read, or if
an exception is thrown parsing its MoML data.protected void _attachText(java.lang.String name, java.lang.String text)
_attachText
in class NamedObj
name
- The name of the attribute.text
- The text with which to configure the attribute.protected void _exportMoMLContents(java.io.Writer output, int depth) throws java.io.IOException
_exportMoMLContents
in class CompositeEntity
output
- The output stream to write to.depth
- The depth in the hierarchy, to determine indenting.java.io.IOException
- If an I/O error occurs.NamedObj.exportMoML(Writer, int)