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:

System.in: Standard input.

System.out: Standard output.

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.

String

Description

Property

$CWD

The current working directory

user.dir

$HOME

The user's home directory

user.home

$PTII

The home directory of the Ptolemy II installation

ptolemy.ptII.dir

$TMPDIR

The temporary directory

java.io.tmpdir

$USERNAME

The user's account name

user.name

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:

calling setExpression();

calling setToken(); and

specifying a value as a constructor argument.

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:

calling setCurrentValue();

calling update() sets the current value if there is an associated
port, and that port has a token to consume; and

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:

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.

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.

Constructor Detail

FilePortParameter

Construct a parameter with the given name contained by the specified
entity. The container argument must not be null, or a
NullPointerException will be thrown. This parameter will create
an associated port in the same container.

FilePortParameter

Construct a Parameter with the given container, name, and Token.
The token defines the initial persistent and current values.
The container argument must not be null, or a
NullPointerException will be thrown. This parameter 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.
The object is not added to the list of objects in the workspace
unless the container is null.
Increment the version of the workspace.
If the name argument is null, then the name is set to the empty
string.

Method Detail

asFile

Return the file as a File object. This method first attempts
to directly use the file name to construct the File. If the
resulting File is not absolute, then it attempts to resolve it
relative to the base directory returned by getBaseDirectory().
If there is no such base URI, then it simply returns the
relative File object.

The file need not exist for this method to succeed. Thus,
this method can be used to determine whether a file with a given
name exists, prior to calling openForWriting().
A typical usage looks like this:

asURL

Return the file as a URL. If the file name is relative, then
it is interpreted as being relative to the directory returned
by getBaseDirectory(). If the name begins with "$CLASSPATH",
then search for the file relative to the classpath.
If no file is found, then it throws an exception.

close

Close the file. If it has not been opened using openForReading()
or openForWriting(), then do nothing. Also, if the file is
System.in or System.out, then do not close it (it does not make
sense to close these files).

getBaseDirectory

public java.net.URI getBaseDirectory()

Return the directory to use as the base for relative file or URL names.
If setBaseDirectory() has been called, then that directory is
returned. Otherwise, the directory containing the file returned
by URIAttribute.getModelURI() is returned, which is the URI
of the first container above this attribute in the hierarchy that
has a URIAttribute, or null if there none.

openForReading

Open the file or URL for reading. If the name begins with
"$CLASSPATH", then search for the file relative to the classpath.
If the name is relative, then it is relative to the directory
returned by getBaseDirectory().

openForWriting

Open the file for writing. If the file does not exist, then
create it. If the file name is not absolute, the it is assumed
to be relative to the base directory returned by getBaseDirectory().
If permitted, this method will return a Writer that will simply
overwrite the contents of the file. It is up to the user of this
method to check whether this is OK (by first calling asFile()
and calling exists() on the returned value).

openForWriting

Open the file for writing or appending.
If the file does not exist, then
create it. If the file name is not absolute, the it is assumed
to be relative to the base directory returned by getBaseDirectory().
If permitted, this method will return a Writer that will simply
overwrite the contents of the file. It is up to the user of this
method to check whether this is OK (by first calling asFile()
and calling exists() on the returned value).

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.