public class LazyTypedCompositeActor extends TypedCompositeActor implements LazyComposite
The lazy contents of this composite are specified via the configure() method, which is called by the MoML parser and 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(), relationList(), or any related method. You can also force evaluation of the MoML by calling populate(). Accessing the attributes or ports of this composite does not trigger a populate() call, so a visual editor can interact with the actor from the outside in the usual way, enabling connections to its ports, editing of its parameters, and rendering of its custom icon, if any.
The configure method can be passed 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. Cloning is used in actor-oriented classes to create subclasses or instances of a class. When a LazyTypedCompositeActor contained by a subclass or an instance is populated, it delegates to the instance in the class definition. When that instance is populated, all of the derived instances in subclasses and instances of the class will also be populated as a side effect.
A third subtlety is that parameters of this actor cannot refer to contained entities or relations, nor to attributes contained by those. This is a rather esoteric use of expressions, so this limitation may not be onerous. You probably didn't know you could do that anyway. An attempt to make such references will simply result in the expression failing to evaluate.
To convert a preexisting model, see ptolemy.moml.ConvertToLazy.
Red (cxh) |
Red (eal) |
Modifier and Type | Class and Description |
---|---|
protected class |
LazyTypedCompositeActor.ContainedObjectsIterator
This class is an iterator over all the contained objects
(all instances of NamedObj) except those that have not yet
been instantiated because of laziness.
|
Modifier and Type | Field and Description |
---|---|
protected boolean |
_configureDone
Indicate whether data given by configure() has been processed.
|
protected boolean |
_populating
Indicator that we are in the midst of populating.
|
_actorFiringListeners, _causalityInterface, _derivedPiggybacks, _initializables, _notifyingActorFiring, _piggybacks, _publishedPorts, _publisherRelations, _stopRequested, _subscribedPorts
_levelCrossingLinks
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
COMPLETED, NOT_READY, STOP_ITERATING
Constructor and Description |
---|
LazyTypedCompositeActor()
Construct a library in the default workspace with no
container and an empty string as its name.
|
LazyTypedCompositeActor(CompositeEntity container,
java.lang.String name)
Construct a library with the given container and name.
|
LazyTypedCompositeActor(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 |
_addEntity(ComponentEntity entity)
Add an entity or class definition to this container.
|
protected void |
_addRelation(ComponentRelation relation)
Add a relation to this container.
|
protected void |
_exportMoMLContents(java.io.Writer output,
int depth)
Write a MoML description of the contents of this object, wrapped
in a configure element.
|
protected void |
_removeEntity(ComponentEntity entity)
Remove the specified entity.
|
protected void |
_removeRelation(ComponentRelation relation)
Remove the specified relation.
|
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 |
deepOpaqueEntityList()
List the opaque entities that are directly or indirectly
contained by this entity.
|
java.util.Set<ComponentRelation> |
deepRelationSet()
Return a set with the relations 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).
|
java.util.List |
entityList(java.lang.Class filter)
Return a list of the component entities contained by this object that
are instances of the specified Java class.
|
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 |
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.
|
ComponentRelation |
getRelation(java.lang.String name)
Get a contained relation by name.
|
java.util.List |
lazyAllAtomicEntityList()
Return a list that consists of all the atomic entities in a model
that have been already instantiated.
|
java.util.List |
lazyAllCompositeEntityList()
Lazy version of {#link #allCompositeEntityList()}.
|
java.util.List |
lazyClassDefinitionList()
Lazy version of
classDefinitionList() . |
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".
|
java.util.List |
lazyDeepEntityList()
Lazy version of
deepEntityList() . |
java.util.List |
lazyEntityList()
Lazy version of
entityList() . |
java.util.List |
lazyRelationList()
Lazy version of
relationList() . |
ComponentRelation |
newRelation(java.lang.String name)
Create a new relation with the specified name, add it to the
relation list, and return it.
|
int |
numberOfEntities()
Return the number of contained entities.
|
int |
numberOfRelations()
Return the number of contained relations.
|
void |
populate()
Populate the actor by reading the file specified by the
source parameter.
|
java.util.List |
relationList()
List the relations contained by this entity.
|
void |
setClassDefinition(boolean isClass)
Specify whether this object is a class definition.
|
java.lang.String |
uniqueName(java.lang.String prefix)
Return a name that is guaranteed to not be the name of
any contained attribute, port, class, entity, or relation.
|
_addPort, _checkTypesFromTo, _destinationTypeConstraints, attributeChanged, attributeTypeChanged, isBackwardTypeInferenceEnabled, newPort, resolveTypes, typeConstraintList, typeConstraints
_actorFiring, _actorFiring, _finishedAddEntity, _setDirector, _transferPortParameterInputs, addActorFiringListener, addInitializable, addPiggyback, connectionsChanged, createReceivers, createSchedule, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, getPublishedPort, getPublishedPortChannel, getPublishedPorts, getSubscribedPortChannel, inferringWidths, inferWidths, initialize, inputPortList, isFireFunctional, isOpaque, isPublishedPort, isStrict, iterate, linkToPublishedPort, linkToPublishedPort, linkToPublishedPort, linkToPublishedPort, needsWidthInference, newInsideReceiver, newReceiver, notifyConnectivityChange, outputPortList, postfire, prefire, preinitialize, recordFiring, registerPublisherPort, registerPublisherPort, removeActorFiringListener, removeInitializable, removePiggyback, requestChange, setContainer, setDirector, setManager, stop, stopFire, terminate, unlinkToPublishedPort, unlinkToPublishedPort, unlinkToPublishedPort, unlinkToPublishedPort, unregisterPublisherPort, unregisterPublisherPort, wrapup
_adjustDeferrals, _containedDecorators, _deepOpaqueEntityList, _description, _validateSettables, allAtomicEntityList, allowLevelCrossingConnect, connect, connect, containedObjectsIterator, deepCompositeEntityList, deepGetEntities, deepNamedObjList, exportLinks, getAttribute, getEntities, getPort, getRelations, isAtomic, lazyAllCompositeTransparentAndOpaqueEntityList, numEntities, numRelations, removeAllEntities, removeAllRelations, statistics
_checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName
_removePort, connectedPortList, connectedPorts, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts
_setParent, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition
_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, 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, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList
fire, isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate
addInitializable, initialize, preinitialize, removeInitializable, wrapup
description, getContainer, getDisplayName, getFullName, getName, getName, setName
getDerivedLevel, getDerivedList, propagateValue
protected boolean _configureDone
protected boolean _populating
public LazyTypedCompositeActor()
public LazyTypedCompositeActor(Workspace workspace)
workspace
- The workspace that will list the actor.public LazyTypedCompositeActor(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.lang.Object clone(Workspace workspace) throws java.lang.CloneNotSupportedException
clone
in class CompositeActor
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.Set<ComponentRelation> deepRelationSet()
deepRelationSet
in class CompositeEntity
public java.util.List deepOpaqueEntityList()
deepOpaqueEntityList
in class CompositeEntity
classDefinitionList()
,
CompositeEntity.allAtomicEntityList()
public java.util.List entityList()
entityList
in class CompositeEntity
CompositeEntity.classDefinitionList()
public java.util.List entityList(java.lang.Class filter)
entityList
in class CompositeEntity
filter
- The class of ComponentEntity of interest.classDefinitionList()
public void exportMoML(java.io.Writer output, int depth, java.lang.String name) throws java.io.IOException
exportMoML
in interface MoMLExportable
exportMoML
in class CompositeEntity
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.java.io.IOException
- If an I/O error occurs.MoMLExportable
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 ComponentRelation getRelation(java.lang.String name)
getRelation
in class CompositeEntity
name
- The name of the desired relation.public java.util.List lazyAllAtomicEntityList()
deepEntityList()
in that
this method looks inside opaque entities, whereas deepEntityList()
does not. The returned list does not include any entities that
are class definitions.lazyAllAtomicEntityList
in class CompositeEntity
public java.util.List lazyAllCompositeEntityList()
lazyAllCompositeEntityList
in class CompositeEntity
public java.util.List lazyClassDefinitionList()
classDefinitionList()
.
In this base class, this is identical to classDefinitionList(),
but derived classes may omit from the returned list any class
definitions whose instantiation is deferred.lazyClassDefinitionList
in class CompositeEntity
public java.util.Iterator lazyContainedObjectsIterator()
CompositeEntity.containedObjectsIterator()
.
If derived classes override it, they must guarantee that any omitted
objects are genuinely not needed in whatever uses this method.lazyContainedObjectsIterator
in class NamedObj
public java.util.List lazyDeepEntityList()
deepEntityList()
.
This method omits from the returned list any entities
whose instantiation is deferred.lazyDeepEntityList
in class CompositeEntity
public java.util.List lazyEntityList()
entityList()
.
In this base class, this is identical to entityList(),
but derived classes may omit from the returned list any
entities whose instantiation is deferred.lazyEntityList
in class CompositeEntity
public java.util.List lazyRelationList()
relationList()
.
In this base class, this is identical to relationList(),
but derived classes may omit from the returned list any
relations whose instantiation is deferred.lazyRelationList
in class CompositeEntity
public ComponentRelation newRelation(java.lang.String name) throws NameDuplicationException
newRelation
in class TypedCompositeActor
name
- The name of the new relation.NameDuplicationException
- If name collides with a name
already in the container.public int numberOfEntities()
numberOfEntities
in class CompositeEntity
public int numberOfRelations()
numberOfRelations
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.public java.util.List relationList()
relationList
in class CompositeEntity
public void setClassDefinition(boolean isClass) throws IllegalActionException
setClassDefinition
in class CompositeEntity
isClass
- True to make this object a class definition, false
to make it an instance.IllegalActionException
- If there are subclasses and/or
instances and the argument is false.InstantiableNamedObj.isClassDefinition()
,
Instantiable
public java.lang.String uniqueName(java.lang.String prefix)
Note that this method should be called judiciously from when the CompositeEntity is large. The reason is that this method searches for matching attributes, ports, classes, entities and relations, which can result in slow performance. This overrides the base class to first populate the actor, if necessary, by calling populate(). Note that this may result in a runtime exception being thrown (if there is an error evaluating the MoML).
uniqueName
in class CompositeEntity
prefix
- A prefix for the name.protected void _addEntity(ComponentEntity entity) throws IllegalActionException, NameDuplicationException
_addEntity
in class TypedCompositeActor
entity
- Entity to contain.IllegalActionException
- If the entity has no name, or the
action would result in a recursive containment structure.NameDuplicationException
- If the name collides with a name
already in the entity.protected void _addRelation(ComponentRelation relation) throws IllegalActionException, NameDuplicationException
_addRelation
in class TypedCompositeActor
relation
- Relation to contain.IllegalActionException
- If the relation has no name.NameDuplicationException
- If the name collides with a name
already on the contained relations list.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)
protected void _removeEntity(ComponentEntity entity)
_removeEntity
in class CompositeEntity
entity
- The entity to remove.protected void _removeRelation(ComponentRelation relation)
_removeRelation
in class CompositeEntity
relation
- The relation to remove.