public class FileParameter extends StringParameter implements FileOrURLAccessor
This is an attribute that specifies a file or URL. The value of this attribute, 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 the name of the file with such references resolved.
If this attribute contains a parameter named allowFiles with value false, then when a file browser is used to select a file, that file browser will be set to not show files (only directories will be shown). If this attribute contains a parameter named allowDirectories with value true, then the file browser will permit the user to select directories (the default behavior is that when a directory is selected, that directory is opened and its contained files and directories are listed).
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:
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.
URIAttributeVariable.CircularDependencyError, Variable.VariableScopeNamedObj.ContainedObjectsIteratorSettable.Visibility_currentExpression, _needsEvaluation, _parserScope, _parseTreeValid, _suppressVariableSubstitution, _valueListeners_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKSEXPERT, FULL, NONE, NOT_EDITABLE| Constructor and Description |
|---|
FileParameter(NamedObj container,
java.lang.String name)
Construct an attribute with the given name contained by the
specified container.
|
FileParameter(NamedObj container,
java.lang.String name,
boolean isOutput)
Construct an attribute with the given name contained by the
specified container.
|
| 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.
|
java.lang.Object |
clone(Workspace workspace)
Clone the attribute into the specified workspace.
|
void |
close()
Close the file.
|
java.net.URI |
getBaseDirectory()
Return the directory to use as the base for relative file or URL names.
|
boolean |
isOutput()
Return whether the file is to be written to.
|
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.
|
stringValueaddChoice, exportMoML, getChoices, removeAllChoices, removeChoice_description, _evaluate, _getCurrentExpression, _notifyValueListeners, _parseIfNecessary, _propagate, _propagateToValueListeners, _propagateValue, _setToken, _setTokenAndNotify, addValueListener, attributeChanged, getDeclaredType, getExpression, getFreeIdentifiers, getParserScope, getScope, getScope, getToken, getType, getTypeTerm, getValueAsString, getVariable, getVisibility, invalidate, isKnown, isLazy, isStringMode, isSuppressVariableSubstitution, isTypeAcceptable, removeValueListener, reset, setContainer, setExpression, setLazy, setName, setParseTreeEvaluator, setStringMode, setSuppressVariableSubstitution, setToken, setToken, setTypeAtLeast, setTypeAtLeast, setTypeAtMost, setTypeEquals, setTypeSameAs, setUnknown, setValueListenerAsWeakDependency, setVisibility, stringRepresentation, toString, typeConstraintList, typeConstraints, validate, valueChangedgetDefaultExpression_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, updateContent_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, 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, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, uniqueName, validateSettables, workspaceequals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitaddValueListener, getDefaultExpression, getDisplayName, getExpression, getValueAsString, getVisibility, removeValueListener, setExpression, setVisibility, validatedescription, getContainer, getFullName, getName, getName, setNamepublic FileParameter(NamedObj container, java.lang.String name) throws IllegalActionException, NameDuplicationException
container - The container.name - The name of this attribute.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.public FileParameter(NamedObj container, java.lang.String name, boolean isOutput) throws IllegalActionException, NameDuplicationException
container - The container.name - The name of this attribute.isOutput - Whether the file is to be written to.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.public java.io.File asFile()
throws IllegalActionException
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:
FileParameter fileParameter;
...
File file = fileParameter.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(fileParameter.openForWriting());
If the name begins with "$CLASSPATH", then search for the file relative to the classpath. If the name begins with $CLASSPATH and a file is not found in the CLASSPATH, then the value of $PTII is substituted in a returned. If this is not done, then the File that is created would have $CLASSPATH or xxxxxxCLASSPATHxxxxxx in the file pathname, which is unlikely to be useful.
asFile in interface FileOrURLAccessorIllegalActionException - If a parse error occurs
reading the file name.getBaseDirectory()public java.net.URL asURL()
throws IllegalActionException
asURL in interface FileOrURLAccessorIllegalActionException - If the file cannot be read, or
if the file cannot be represented as a URL (e.g. System.in), or
the name specification cannot be parsed.public java.lang.Object clone(Workspace workspace) throws java.lang.CloneNotSupportedException
public void close()
throws IllegalActionException
close in interface FileOrURLAccessorIllegalActionException - If the file or URL cannot be
closed.public java.net.URI getBaseDirectory()
getBaseDirectory in interface FileOrURLAccessorsetBaseDirectory(URI),
URIAttribute.getModelURI(NamedObj)public boolean isOutput()
public java.io.BufferedReader openForReading()
throws IllegalActionException
openForReading in interface FileOrURLAccessorIllegalActionException - If the file or URL cannot be
opened.getBaseDirectory()public java.io.Writer openForWriting()
throws IllegalActionException
openForWriting in interface FileOrURLAccessorIllegalActionException - If the file cannot be opened
or created.getBaseDirectory(),
asFile()public java.io.Writer openForWriting(boolean append)
throws IllegalActionException
openForWriting in interface FileOrURLAccessorappend - If true, then append to the file rather than
overwriting.IllegalActionException - If the file cannot be opened
or created.getBaseDirectory(),
asFile()public void setBaseDirectory(java.net.URI directory)
setBaseDirectory in interface FileOrURLAccessordirectory - The base directory.getBaseDirectory(),
URIAttribute.getModelURI(NamedObj)