Package ptolemy.actor.parameters

Class SharedParameter

  • All Implemented Interfaces:
    java.lang.Cloneable, Initializable, HasTypeConstraints, Typeable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, Settable, ValueListener
    Direct Known Subclasses:
    TestSharedParameter
    public class SharedParameter
extends Parameter
implements Initializable
    This parameter is shared throughout a model. Changing the expression of any one instance of the parameter will result in all instances that are shared being changed to the same expression. An instance elsewhere in the model (within the same top level) is shared if it has the same name and its container is of the class specified in the constructor (or of the container class, if no class is specified in the constructor). Note that two parameters with the same expression do not necessarily have the same value, since the expression may reference other parameters that are in scope.

    One exception is that if this parameter is (deeply) within an instance of EntityLibrary, then the parameter is not shared. Were this not the case, then opening a library containing this parameter would force expansion of all the sublibraries of EntityLibrary, which would defeat the lazy instantiation of EntityLibrary.

    When this parameter is constructed, the specified container will be used to infer the parameter value from the container. That is, if the container is within a model that has any parameters shared with this one, then the value will be set to the last of those encountered. If the container is subsequently changed, it is up to the code implementing the change to use the inferValueFromContext() method to reset the value to match the new context. Note that this really needs to be done if the container of the container, or its container, or any container above this parameter is changed. It is recommended to use the four-argument constructor, so you can specify a default value to use if there are no shared parameters.

    Note that it might be tempting to use a static parameter field to achieve this effect, but this would be problematic for two reasons. First, the parameter would only be able to have one container. Second, the parameter would be shared across all models in the same Java virtual machine, not just within a single model.

    Since:
    Ptolemy II 8.0
    Version:
    $Id$
    Author:
    Edward A. Lee, contributor: Christopher Brooks, Bert Rodiers
    Pt.AcceptedRating:
    Green (acataldo)
    Pt.ProposedRating:
    Green (eal)

    • Constructor Detail

      • SharedParameter

        public SharedParameter​(NamedObj container,
                       java.lang.String name)
                throws IllegalActionException,
                       NameDuplicationException
        Construct a parameter with the given container and name. The container class will be used to determine which other instances of SharedParameter are shared with this one.
        Parameters:
        container - The container.
        name - The name of the parameter.
        Throws:
        IllegalActionException - If the parameter is not of an acceptable class for the container.
        NameDuplicationException - If the name coincides with a parameter already in the container.

      • SharedParameter

        public SharedParameter​(NamedObj container,
                       java.lang.String name,
                       java.lang.Class<?> containerClass)
                throws IllegalActionException,
                       NameDuplicationException
        Construct a parameter with the given container, name, and container class. The specified class will be used to determine which other instances of SharedParameter are shared with this one.
        Parameters:
        container - The container.
        name - The name of the parameter.
        containerClass - The class used to determine shared instances.
        Throws:
        IllegalActionException - If the parameter is not of an acceptable class for the container.
        NameDuplicationException - If the name coincides with a parameter already in the container.

      • SharedParameter

        public SharedParameter​(NamedObj container,
                       java.lang.String name,
                       java.lang.Class<?> containerClass,
                       java.lang.String defaultValue)
                throws IllegalActionException,
                       NameDuplicationException
        Construct a parameter with the given container, name, container class, and default value. This is the preferred constructor to use. The specified class will be used to determine which other instances of SharedParameter are shared with this one.
        Parameters:
        container - The container.
        name - The name of the parameter.
        containerClass - The class used to determine shared instances. An argument of null means simply to use the class of the container, whatever that happens to be.
        defaultValue - The default value to use if the container's model has no shared parameters.
        Throws:
        IllegalActionException - If the parameter is not of an acceptable class for the container, or an empty string to specify no default value.
        NameDuplicationException - If the name coincides with a parameter already in the container.

    • Method Detail

      • getToken

        public Token getToken()
               throws IllegalActionException
        Get the token contained by this variable. The type of the returned token is always that returned by getType(). Calling this method will trigger evaluation of the expression, if the value has been given by setExpression(). Notice the evaluation of the expression can trigger an exception if the expression is not valid, or if the result of the expression violates type constraints specified by setTypeEquals() or setTypeAtMost(), or if the result of the expression is null and there are other variables that depend on this one. The returned value will be null if neither an expression nor a token has been set, or either has been set to null.
        Overrides:
        getToken in class Variable
        Returns:
        The token contained by this variable converted to the type of this variable, or null if there is none.
        Throws:
        IllegalActionException - If the expression cannot be parsed or cannot be evaluated, or if the result of evaluation violates type constraints, or if the result of evaluation is null and there are variables that depend on this one.
        See Also:
        setToken(Token)

      • getRoot

        public NamedObj getRoot()
        Return the top level of the containment hierarchy, unless one of the containers is an instance of EntityLibrary, in which case, return null.
        Returns:
        The top level, or null if this is within a library.

      • inferValueFromContext

        public void inferValueFromContext​(java.lang.String defaultValue)
        Infer the value of this parameter from the container context. That is, search for parameters that are shared with this one, and set the value of this parameter to match the first one encountered. If there are no shared parameters, then assign the default value given as an argument.
        Parameters:
        defaultValue - The default parameter value to use.

      • isFireFunctional

        public boolean isFireFunctional()
        Return true.
        Returns:
        True.

      • isStrict

        public boolean isStrict()
        Return false.
        Returns:
        False.

      • isSuppressingPropagation

        public boolean isSuppressingPropagation()
        Return true if this instance is suppressing propagation. Unless setSuppressingPropagation() has been called, this returns false.
        Returns:
        Returns whether this instance is suppressing propagation.
        See Also:
        setSuppressingPropagation(boolean)

      • setContainer

        public void setContainer​(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException
        Override the base class to register as an initializable slave with the new container. This results in the preinitialize(), initialize(), and wrapup() methods of this instance being invoked when the corresponding method of the container are invoked.
        Overrides:
        setContainer in class Variable
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace.
        NameDuplicationException - If the container already has an entity with the name of this entity.
        See Also:
        Attribute.getContainer()

      • setSuppressingPropagation

        public void setSuppressingPropagation​(boolean propagation)
        Specify whether this instance should be suppressing propagation. If this is called with value true, then changes to this parameter will not propagate to other shared instances in the model.
        Parameters:
        propagation - True to suppress propagation.
        See Also:
        isSuppressingPropagation()

      • sharedParameterSet

        public java.util.Collection sharedParameterSet()
        Return a collection of all the shared parameters within the same model as this parameter. If there are no such parameters or if this parameter is deeply contained within an EntityLibrary, then return an empty collection. Otherwise, the list will include this instance if this instance has a container. If this instance has no container, then return an empty collection. A shared parameter is one that is an instance of SharedParameter, has the same name as this one, and is contained by the container class specified in the constructor.
        Returns:
        A collection of parameters.

      • validate

        public java.util.Collection validate()
                              throws IllegalActionException
        Override the base class to also validate the shared instances.
        Specified by:
        validate in interface Settable
        Overrides:
        validate in class Variable
        Returns:
        A Collection of all the shared parameters within the same model as this parameter, see sharedParameterSet().
        Throws:
        IllegalActionException - If this variable or a variable dependent on this variable cannot be evaluated (and is not lazy) and the model error handler throws an exception. Also thrown if the change is not acceptable to the container.

      • _propagateValue

        protected void _propagateValue​(NamedObj destination)
                        throws IllegalActionException
        Override the base class to do the propagation only if the specified destination is not shared, because if it is shared, then the value will be propagated in through the sharing mechanism.
        Overrides:
        _propagateValue in class Variable
        Parameters:
        destination - Object to which to propagate the value.
        Throws:
        IllegalActionException - If the value cannot be propagated.