ptolemy.kernel.attributes

Interface FileOrURLAccessor

All Superinterfaces:

Nameable, Settable

All Known Implementing Classes:

DefaultModelAttribute, FileAttribute, FileParameter, FilePortParameter, LiveLink

public interface FileOrURLAccessor
extends Settable

An interface for Attributes and Parameters that access files or URLs.

This interface is necessary because Java does not support multiple inheritance and we have two classes (FileParameter and FilePortParameter) that have a common interface, but do not have an immediate parent class. In addition, FileAttribute shares this interface.

This interface is implemented by an Attribute or Parameter that specifies a file or URL. The value of this Attribute or Parameter, accessed by getExpression(), is a string that names a file or URL. If the model containing this attribute 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

Preset 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

The above properties are normally set when a Ptolemy II application starts.

If a file name begins with the string "$CLASSPATH", followed by either "/" or "\", 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).

Since:

Ptolemy II 6.1

Version:

$Id: FileOrURLAccessor.java 70398 2014-10-22 23:44:32Z cxh $

Author:

Christopher Brooks, based on FileAttribute by Edward A. Lee

See Also:

URIAttribute

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (cxh)

Nested Class Summary

Nested classes/interfaces inherited from interface ptolemy.kernel.util.Settable

Settable.Visibility

Field Summary

Fields inherited from interface ptolemy.kernel.util.Settable

EXPERT, FULL, NONE, NOT_EDITABLE

Method Summary

Modifier and Type	Method and Description
java.io.File	asFile() Return the file as a File object.
java.net.URL	asURL() Return the file as a URL.
void	close() Close the file.
java.net.URI	getBaseDirectory() Return the directory to use as the base for relative file or URL names.
java.io.BufferedReader	openForReading() Open the file or URL for reading.
java.io.Writer	openForWriting() Open the file for writing.
java.io.Writer	openForWriting(boolean append) Open the file for writing or appending.
void	setBaseDirectory(java.net.URI directory) Set the directory to use as the base for relative file or URL names.

Methods inherited from interface ptolemy.kernel.util.Settable

addValueListener, getDefaultExpression, getDisplayName, getExpression, getValueAsString, getVisibility, removeValueListener, setExpression, setVisibility, validate

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getFullName, getName, getName, setName

Method Detail

asFile

java.io.File asFile()
             throws IllegalActionException

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:

      FileAttribute fileAttribute;
      ...
      File file = fileAttribute.asFile();
      if (file.exists()) {
         ... Ask the user if it's OK to overwrite...
         ... Throw an exception if not...
      }
      // The following will overwrite an existing file.
      Writer writer = new PrintWriter(fileAttribute.openForWriting());
  

Returns:

A File, or null if no file name has been specified.

Throws:

IllegalActionException - If a parse error occurs reading the file name.

See Also:

getBaseDirectory()

asURL

java.net.URL asURL()
            throws IllegalActionException

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.

Returns:

A URL, or null if no file name or URL has been specified.

Throws:

IllegalActionException - If the file cannot be read, or if the file cannot be represented as a URL (e.g. System.in).

close

void close()
    throws IllegalActionException

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

Throws:

IllegalActionException - If the file or URL cannot be closed.

getBaseDirectory

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.

Returns:

A directory name, or null if there is none.

See Also:

setBaseDirectory(URI), URIAttribute.getModelURI(NamedObj)

openForReading

java.io.BufferedReader openForReading()
                               throws IllegalActionException

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

Returns:

A buffered reader.

Throws:

IllegalActionException - If the file or URL cannot be opened.

See Also:

getBaseDirectory()

openForWriting

java.io.Writer openForWriting()
                       throws IllegalActionException

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

Returns:

A writer, or null if no file name has been specified.

Throws:

IllegalActionException - If the file cannot be opened or created.

See Also:

getBaseDirectory(), asFile()

openForWriting

java.io.Writer openForWriting(boolean append)
                       throws IllegalActionException

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

Parameters:

append - If true, then append to the file rather than overwriting.

Returns:

A writer, or null if no file name has been specified.

Throws:

IllegalActionException - If the file cannot be opened or created.

See Also:

getBaseDirectory(), asFile()

setBaseDirectory

void setBaseDirectory(java.net.URI directory)

Set the directory to use as the base for relative file or URL names. If this is not called, then the default is the directory containing the file returned by URIAttribute.getModelURI().

Parameters:

directory - The base directory.

See Also:

getBaseDirectory(), URIAttribute.getModelURI(NamedObj)