ptolemy.actor.parameters
Class ParameterSet

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.data.expr.ScopeExtendingAttribute
              ptolemy.actor.parameters.ParameterSet

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Executable, Initializable, ScopeExtender, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class ParameterSet
extends ScopeExtendingAttribute
implements Executable

An attribute that reads multiple values from a file and sets corresponding parameters in the container. The values are in the form:

 attributeName = value
 

where variableName is the name of the attribute in a format suitable for NamedObj.setName(String) (i.e., does not contain periods) and value is the expression in the Ptolemy expression language. Comments are lines that begin with the # character. Each line in the file is interpreted as a separate assignment.

The attributes that are created will have the same visibility as parameters of the container of the attribute. They are shadowed, however, by parameters of the container. That is, if the container has a parameter with the same name as one in the parameter set, the one in the container provides the value to any observer.

If the file is modified during execution of a model, by default this will not be noticed until the next run. If you set the checkForFileUpdates parameter to true, then on each prefiring of the enclosing opaque composite actor, this parameter will check for updates of the file. Otherwise, it will only check between runs of the model or when the file name or URL gets changed.

Note that the order the parameters are created is arbitrary, this is because we read the file in using java.util.Properties.load(), which uses a HashMap to store the properties. We use a Properties.load() because it provides a nice parser for the files and can read and write values in both text and XML.

Since:

Ptolemy II 5.2

Version:

$Id: ParameterSet.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Christopher Brooks, contributor: Edward A. Lee

See Also:

Variable, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private long	_date Date of the file when last read.
private java.lang.String	_fileName The previously read file name.
private java.util.List<Initializable>	_initializables List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.
private java.util.Properties	_properties Cached copy of the last hashset of properties, used to remove old properties.
Parameter	checkForFileUpdates If this parameter is set to true, then the specified file or URL will be checked for updates on every prefiring of the enclosing opaque composite actor.
FileParameter	fileOrURL A parameter naming the file or URL to be read that contains attribute names and values.

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

ParameterSet(NamedObj container, java.lang.String name)
Construct an attribute with the given name contained by the specified entity.

Method Summary

private void	_reReadIfNeeded() If either the file name or the date on the file have changed since the last reading, then re-read the file.
void	addInitializable(Initializable initializable) Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	attributeChanged(Attribute attribute) If the parameter is fileOrURL, and the specified file name is not null, then open and read the file.
void	fire() Do nothing.
void	initialize() Do nothing except invoke the initialize methods of objects that have been added using addInitializable().
boolean	isFireFunctional() Return true.
boolean	isStrict() Return false.
int	iterate(int count) Check to see whether the specified file has changed, and if so, re-read it.
boolean	postfire() Do nothing.
boolean	prefire() Check to see whether the specified file has changed, and if so, re-read it.
void	preinitialize() Check to see whether the specified file has changed, and if so, re-read it, and invoke the preinitialize() methods of objects that have been added using addInitializable().
void	read() Read the contents of the file named by this parameter and create attributes in the current scope.
void	removeInitializable(Initializable initializable) Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	setContainer(NamedObj container) Override the base class to register as a piggyback with the nearest opaque composite actor above in the hierarchy.
void	stop() Do nothing.
void	stopFire() Do nothing.
void	terminate() Do nothing.
void	wrapup() Check to see whether the specified file has changed, and if so, re-read it, and invoke the wrapup() methods of objects that have been added using addInitializable().

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, clone, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.data.expr.ScopeExtender

attributeList, getAttribute

Field Detail

checkForFileUpdates

public Parameter checkForFileUpdates

If this parameter is set to true, then the specified file or URL will be checked for updates on every prefiring of the enclosing opaque composite actor. Otherwise, it will check for updates only between runs. This is a boolean that defaults to false.

fileOrURL

public FileParameter fileOrURL

A parameter naming the file or URL to be read that contains attribute names and values. The file should be in a format suitable for java.util.Properties.load(), see the class comment of this class for details. This initial default value is the empty string "", which means that no file will be read and no parameter values will be defined.

_date

private long _date

Date of the file when last read.

_fileName

private java.lang.String _fileName

The previously read file name.

_initializables

private transient java.util.List<Initializable> _initializables

List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.

_properties

private java.util.Properties _properties

Cached copy of the last hashset of properties, used to remove old properties.

Constructor Detail

ParameterSet

public ParameterSet(NamedObj container,
                    java.lang.String name)
             throws IllegalActionException,
                    NameDuplicationException

Construct an attribute with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This attribute will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace.

Parameters:

container - The container.

name - The name of this attribute.

Throws:

IllegalActionException - If the attribute is not of an acceptable class for the container, or if the name contains a period.

NameDuplicationException - If the name coincides with an attribute already in the container.

Method Detail

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.

Specified by:

addInitializable in interface Initializable

Parameters:

initializable - The object whose methods should be invoked.

See Also:

removeInitializable(Initializable), CompositeActor.addPiggyback(Executable)

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the parameter is fileOrURL, and the specified file name is not null, then open and read the file.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the superclass throws it, or if the file cannot be read, or if the file parameters cannot be evaluated.

fire

public void fire()
          throws IllegalActionException

Do nothing.

Specified by:

fire in interface Executable

Throws:

IllegalActionException - If firing is not permitted.

initialize

public void initialize()
                throws IllegalActionException

Do nothing except invoke the initialize methods of objects that have been added using addInitializable().

Specified by:

initialize in interface Initializable

Throws:

IllegalActionException - If one of the added objects throws it.

isFireFunctional

public boolean isFireFunctional()

Return true.

Specified by:

isFireFunctional in interface Executable

Returns:

True.

isStrict

public boolean isStrict()

Return false.

Specified by:

isStrict in interface Executable

Returns:

False.

iterate

public int iterate(int count)
            throws IllegalActionException

Check to see whether the specified file has changed, and if so, re-read it.

Specified by:

iterate in interface Executable

Parameters:

count - The number of iterations to perform, ignored by this method.

Returns:

Executable.COMPLETED.

Throws:

IllegalActionException - If re-reading the file fails.

postfire

public boolean postfire()

Do nothing.

Specified by:

postfire in interface Executable

Returns:

True.

prefire

public boolean prefire()
                throws IllegalActionException

Check to see whether the specified file has changed, and if so, re-read it.

Specified by:

prefire in interface Executable

Returns:

True.

Throws:

IllegalActionException - If re-reading the file fails.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Check to see whether the specified file has changed, and if so, re-read it, and invoke the preinitialize() methods of objects that have been added using addInitializable().

Specified by:

preinitialize in interface Initializable

Throws:

IllegalActionException - If one of the added objects throws it, or if re-reading the file fails.

read

public void read()
          throws IllegalActionException,
                 NameDuplicationException,
                 java.io.IOException

Read the contents of the file named by this parameter and create attributes in the current scope.

Throws:

java.io.IOException - If there is a problem reading the file.

IllegalActionException - If there is a problem reading the previous attribute or validating the settables

NameDuplicationException - If there is a problem removing a previous attribute or creating a new variable.

removeInitializable

public void removeInitializable(Initializable initializable)

Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object. If the specified object is not on the list, do nothing.

Specified by:

removeInitializable in interface Initializable

Parameters:

initializable - The object whose methods should no longer be invoked.

See Also:

addInitializable(Initializable), CompositeActor.removePiggyback(Executable)

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to register as a piggyback with the nearest opaque composite actor above in the hierarchy.

Overrides:

setContainer in class ScopeExtendingAttribute

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

stop

public void stop()

Do nothing.

Specified by:

stop in interface Executable

stopFire

public void stopFire()

Do nothing.

Specified by:

stopFire in interface Executable

terminate

public void terminate()

Do nothing.

Specified by:

terminate in interface Executable

wrapup

public void wrapup()
            throws IllegalActionException

Check to see whether the specified file has changed, and if so, re-read it, and invoke the wrapup() methods of objects that have been added using addInitializable().

Specified by:

wrapup in interface Initializable

Throws:

IllegalActionException - If one of the added objects throws it, or if re-reading the file fails.

_reReadIfNeeded

private void _reReadIfNeeded()
                      throws IllegalActionException

If either the file name or the date on the file have changed since the last reading, then re-read the file.

Throws:

IllegalActionException - If re-reading the file fails.