Package ptolemy.moml

Class EntityLibrary

  • All Implemented Interfaces:
    java.lang.Cloneable, Librariable, Changeable, Configurable, Debuggable, DebugListener, Derivable, Instantiable, LazyComposite, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    AccessorLibrary
    public class EntityLibrary
extends CompositeEntity
implements LazyComposite, Librariable
    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
 <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>
    Since:
    Ptolemy II 1.0
    Version:
    $Id$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Red (bilung)
    Pt.ProposedRating:
    Red (eal)

    • Field Detail

      • _base

        protected java.net.URL _base
        The base specified by the configure() method.

      • _cloning

        protected boolean _cloning
        Indicate that we are cloning.

      • _configureDone

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

      • _configureSource

        protected java.lang.String _configureSource
        URL specified to the configure() method.

      • _configureText

        protected java.lang.String _configureText
        Text specified to the configure() method.

      • _populated

        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.

      • _populating

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

    • 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.
        Specified by:
        populate in interface LazyComposite
        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)