FilePortParameter
ptolemy.actor.parameters.FilePortParameter

This file parameter creates an associated port that can be used to update the current value of the parameter. The value of this parameter, accessed by getExpression(), is a string that names a file or URL, possibly containing references to variables defined in scope using the syntax $ID, ${ID} or $(ID). The value returned by getToken() is name of the file with such references resolved.

If the model containing this port parameter has been saved to a MoML file, then the file name can be given relative to the directory containing that MoML file. If the model has not been saved to a file, then the classpath is used for identifying relative file names.

Files can be given relative to a base, where the base is the URI of the first container above this one that has a URIAttribute. Normally, this URI specifies the file or URL containing the model definition. Thus, files that are referred to here can be kept in the same directory as the model, or in a related directory, and can moved together with the model.

The following special file names are understood:

Note, however, that these file names cannot be converted to URLs using the asURL() method. A file name can also contain the following strings that start with "$", which get substituted with the appropriate values. $CWDThe current working directoryuser.dir$HOMEThe user's home directoryuser.home$PTIIThe home directory of the Ptolemy II installationptolemy.ptII.dir$TMPDIRThe temporary directoryjava.io.tmpdir
String Description Property
The above properties are normally set when a Ptolemy II application starts.

If a file name begins with the reference "$CLASSPATH", then when the file is opened for reading, the openForReading() method will search for the file relative to the classpath (using the getResource() method of the current class loader). This will only work for a file that exists, and thus the openForWriting() method will not understand the "$CLASSPATH" string; this makes sense since the classpath typically has several directories, and it would not be obvious where to create the file. The asURL() method also recognizes the "$CLASSPATH" string, but not the asFile() method (which is typically used when accessing a file for writing). NOTE: If the container of this parameter also contains a variable named CLASSPATH, then the value of that variable is used instead of the Java classpath.

This parameter has two values, which may not be equal, a current value and a persistent value. The persistent value is returned by getExpression() and is set by any of three different mechanisms:

All three of these will also set the current value, which is then equal to the persistent value. The current value is returned by get getToken() and is set by any of three different mechanisms: These three techniques do not change the persistent value, so after these are used, the persistent value and current value may be different.

When using this parameter in an actor, care must be exercised to call update() exactly once per firing prior to calling getToken(). Each time update() is called, a new token will be consumed from the associated port (if the port is connected and has a token). If this is called multiple times in an iteration, it may result in consuming tokens that were intended for subsequent iterations. Thus, for example, update() should not be called in fire() and then again in postfire(). Moreover, in some domains (such as DE), it is essential that if a token is provided on a port, that it is consumed. In DE, the actor will be repeatedly fired until the token is consumed. Thus, it is an error to not call update() once per iteration. For an example of an actor that uses this mechanism, see Ramp.

If this actor is placed in a container that does not implement the TypedActor interface, then no associated port is created, and it functions as an ordinary file parameter. This is useful, for example, if this is put in a library, where one would not want the associated port to appear.

There are a few situations where FilePortParameter might not do what you expect:

  1. If it is used in a transparent composite actor, then a token provided to a FilePortParameter will never be read. A transparent composite actor is one without a director.
    Workaround: Put a director in the composite.
  2. Certain actors read parameter values only during initialization. During initialization, a FilePortParameter can only have a value set via the parameter (it can't have yet received a token). So if the initial value is set to the value of the FilePortParameter, then it will see only the parameter value, never the value provided via the port.
    Workaround: Use a RunCompositeActor to contain the model.


Author(s): Edward A. Lee
Version:$Id: FilePortParameter.java,v 1.17 2005/10/24 19:09:05 cxh Exp $
Pt.Proposed Rating:Yellow (eal)
Pt.Accepted Rating:Red (cxh)