Package ptolemy.actor

Class LazyTypedCompositeActor

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Configurable, Debuggable, DebugListener, Derivable, Instantiable, LazyComposite, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    ModularCodeGenLazyTypedCompositeActor
    public class LazyTypedCompositeActor
extends TypedCompositeActor
implements LazyComposite
    An aggregation of typed actors with lazy evaluation. The contents of this actor can be created in the usual way via visual editor by dragging in other actors and ports and connecting them. When it exports a MoML description of itself, it describes its ports and parameters in the usual way, but contained actors, relations, and their interconnections are exported within <configure> </configure> tags. When reloading the MoML description, evaluation of the MoML within the configure tags is deferred until there is an explicit request for the contents. This behavior is useful for large complicated models where the time it takes to instantiate the entire model is large. It permits opening and browsing the model without a long wait. However, the cost comes typically when running the model. The instantiation time will be added to the time it takes to preinitialize the model.

    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.

    Since:
    Ptolemy II 8.0
    Version:
    $Id$
    Author:
    Christopher Brooks and Edward A. Lee
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (eal)

    • Field Detail

      • _configureDone

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

      • _populating

        protected boolean _populating
        Indicator that we are in the midst of populating.

    • Constructor Detail

      • LazyTypedCompositeActor

        public LazyTypedCompositeActor()
        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.

      • LazyTypedCompositeActor

        public LazyTypedCompositeActor​(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.

    • Method Detail

      • 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 CompositeActor
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new LazyTypedCompositeActor.
        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 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). 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 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). 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()

      • deepRelationSet

        public java.util.Set<ComponentRelation> deepRelationSet()
        Return a set with the relations that are directly or indirectly contained by this entity. The set will be empty if there are no such contained relations. 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). This method is read-synchronized on the workspace.
        Overrides:
        deepRelationSet in class CompositeEntity
        Returns:
        A set of ComponentRelation objects.

      • deepOpaqueEntityList

        public java.util.List deepOpaqueEntityList()
        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 list does not include class definitions nor anything contained by them. This method is read-synchronized on the workspace.
        Overrides:
        deepOpaqueEntityList in class CompositeEntity
        Returns:
        A list of opaque ComponentEntity objects.
        See Also:
        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 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). This method is read-synchronized on the workspace.
        Overrides:
        entityList in class CompositeEntity
        Returns:
        An unmodifiable list of ComponentEntity objects.
        See Also:
        CompositeEntity.classDefinitionList()

      • entityList

        public 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. If there are no such instances, then return an empty list. The returned list does not include class definitions. This method is read-synchronized on the workspace.
        Overrides:
        entityList in class CompositeEntity
        Parameters:
        filter - The class of ComponentEntity of interest.
        Returns:
        A list of instances of specified class.
        See Also:
        classDefinitionList()

      • 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.
        Specified by:
        exportMoML in interface MoMLExportable
        Overrides:
        exportMoML in class CompositeEntity
        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

      • 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 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). 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. This will include whatever classes, entities, and relations have been previously instantiated. FIXME: Shouldn't this also include connections???
        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.

      • getRelation

        public ComponentRelation getRelation​(java.lang.String name)
        Get a contained relation by name. The name may be compound, with fields separated by periods, in which case the relation returned is contained by a (deeply) contained entity. 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). This method is read-synchronized on the workspace.
        Overrides:
        getRelation in class CompositeEntity
        Parameters:
        name - The name of the desired relation.
        Returns:
        A relation with the specified name, or null if none exists.

      • lazyAllAtomicEntityList

        public java.util.List lazyAllAtomicEntityList()
        Return a list that consists of all the atomic entities in a model that have been already instantiated. This method differs from 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.
        Overrides:
        lazyAllAtomicEntityList in class CompositeEntity
        Returns:
        a List of all atomic entities in the model.

      • lazyAllCompositeEntityList

        public java.util.List lazyAllCompositeEntityList()
        Lazy version of {#link #allCompositeEntityList()}. In this base class, this is identical to allCompositeEntityList() but derived classes may omit from the returned list any class definitions whose instantiation is deferred.
        Overrides:
        lazyAllCompositeEntityList in class CompositeEntity
        Returns:
        A list of ComponentEntity objects.

      • lazyClassDefinitionList

        public java.util.List lazyClassDefinitionList()
        Lazy version of 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.
        Overrides:
        lazyClassDefinitionList in class CompositeEntity
        Returns:
        A list of ComponentEntity objects.

      • 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 CompositeEntity.containedObjectsIterator(). If derived classes override it, they must guarantee that any omitted objects are genuinely not needed in whatever uses this method.
        Overrides:
        lazyContainedObjectsIterator in class NamedObj
        Returns:
        An iterator over instances of NamedObj contained by this object.

      • lazyDeepEntityList

        public java.util.List lazyDeepEntityList()
        Lazy version of deepEntityList(). This method omits from the returned list any entities whose instantiation is deferred.
        Overrides:
        lazyDeepEntityList in class CompositeEntity
        Returns:
        A list of ComponentEntity objects.

      • lazyEntityList

        public java.util.List lazyEntityList()
        Lazy version of 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.
        Overrides:
        lazyEntityList in class CompositeEntity
        Returns:
        A list of ComponentEntity objects.

      • lazyRelationList

        public java.util.List lazyRelationList()
        Lazy version of 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.
        Overrides:
        lazyRelationList in class CompositeEntity
        Returns:
        A list of ComponentEntity objects.

      • newRelation

        public ComponentRelation newRelation​(java.lang.String name)
                              throws NameDuplicationException
        Create a new relation with the specified name, add it to the relation list, and return it. Derived classes can override this to create domain-specific subclasses of ComponentRelation. This method is write-synchronized on the workspace and increments its version number. This overrides the base class to force evaluation of any deferred MoML. This is necessary so that name collisions are detected deterministically and so that order of relations does not change depending on whether evaluation has occurred.
        Overrides:
        newRelation in class TypedCompositeActor
        Parameters:
        name - The name of the new relation.
        Returns:
        The new relation.
        Throws:
        NameDuplicationException - If name collides with a name already in the container.

      • numberOfEntities

        public int numberOfEntities()
        Return the number of contained entities. 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). This method is read-synchronized on the workspace.
        Overrides:
        numberOfEntities in class CompositeEntity
        Returns:
        The number of entities.

      • numberOfRelations

        public int numberOfRelations()
        Return the number of contained relations. 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). This method is read-synchronized on the workspace.
        Overrides:
        numberOfRelations in class CompositeEntity
        Returns:
        The number of relations.

      • 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.
        Specified by:
        populate in interface LazyComposite
        Throws:
        InvalidStateException - If the source cannot be read, or if an exception is thrown parsing its MoML data.

      • relationList

        public java.util.List relationList()
        List the relations contained by this entity. The returned list is static in the sense that it is not affected by any subsequent additions or removals of relations. 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). This method is read-synchronized on the workspace.
        Overrides:
        relationList in class CompositeEntity
        Returns:
        An unmodifiable list of ComponentRelation objects.

      • 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, port, class, entity, or relation. 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, port, class, entity, or relation. If this composite entity or any composite entity that it contains defers its MoML definition (i.e., it is an instance of a class or a subclass), then the prefix gets appended with "_n_", where n is the depth of this deferral. That is, if the object deferred to also defers, then n is incremented.

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

        Overrides:
        uniqueName in class CompositeEntity
        Parameters:
        prefix - A prefix for the name.
        Returns:
        A unique name.

      • _addEntity

        protected void _addEntity​(ComponentEntity entity)
                   throws IllegalActionException,
                          NameDuplicationException
        Add an entity or class definition to this container. This method should not be used directly. Call the setContainer() method of the entity instead. This method does not set the container of the entity to point to this composite entity. It assumes that the entity is in the same workspace as this container, but does not check. The caller should check. Derived classes may override this method to constrain the the entity to a subclass of ComponentEntity. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the entity being added now appears in order after the ones previously specified and lazily instantiated.
        Overrides:
        _addEntity in class TypedCompositeActor
        Parameters:
        entity - Entity to contain.
        Throws:
        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.

      • _addRelation

        protected void _addRelation​(ComponentRelation relation)
                     throws IllegalActionException,
                            NameDuplicationException
        Add a relation to this container. This method should not be used directly. Call the setContainer() method of the relation instead. This method does not set the container of the relation to refer to this container. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the relation being added now appears in order after the ones previously specified and lazily instantiated.
        Overrides:
        _addRelation in class TypedCompositeActor
        Parameters:
        relation - Relation to contain.
        Throws:
        IllegalActionException - If the relation has no name.
        NameDuplicationException - If the name collides with a name already on the contained relations list.

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

      • _removeEntity

        protected void _removeEntity​(ComponentEntity entity)
        Remove the specified entity. This method should not be used directly. Call the setContainer() method of the entity instead with a null argument. The entity is assumed to be contained by this composite (otherwise, nothing happens). This does not alter the entity in any way. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the entity being removed now actually exists.
        Overrides:
        _removeEntity in class CompositeEntity
        Parameters:
        entity - The entity to remove.

      • _removeRelation

        protected void _removeRelation​(ComponentRelation relation)
        Remove the specified relation. This method should not be used directly. Call the setContainer() method of the relation instead with a null argument. The relation is assumed to be contained by this composite (otherwise, nothing happens). This does not alter the relation in any way. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the relation being removed now actually exists.
        Overrides:
        _removeRelation in class CompositeEntity
        Parameters:
        relation - The relation to remove.