The File Object

A File object is an abstract representation of file and directory path names. The name uses the script file reference to identify the file. The name is required to create a File object but it does not have to represent an actual file.

This File object includes functions to interrogate and manipulate the file or directory represented by this object.

File objects are of class File.

File Object Properties

Property	Description
prototype	A reference to the Object Prototype. This property does not enumerate and can not be deleted but can be changed.

File Object Functions

Function	Description
canRead()	Returns true if the file specified by this abstract path name exists and can be read by the script.
canWrite()	Returns true if the file system actually contains a file denoted by this abstract path name and the script is allowed to write to the file.
del()	Deletes the file or directory denoted by this abstract path name. If this path name denotes a directory, then the directory must be empty in order to be deleted. Returns true if the file or directory is successfully deleted.
exists()	Returns true if the file denoted by this abstract path name exists.
getJavaPath()	Returns the path name string in Java format. This can then be used in Java file objects.
getName()	Returns the name of the file or directory denoted by this abstract path name
getParent()	Returns the path name string, in script file reference format, of the parent directory named by this abstract path name. The parent of an abstract path name consists of the path name's prefix, if any, and each name in the path name's name sequence except for the last.
getParentFile()	Returns a File object for the parent directory named by this abstract path name.
getPath()	Returns the path name string, in script file reference format. This can then be used in script file based objects.
isDirectory()	Returns true if the file denoted by this abstract path name exists and is a directory.
isFile()	Returns true if the file denoted by this abstract path name exists and is a normal file.
lastModified()	Returns a number representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970). Returns 0 if the file does not exist or if an I/O error occurs. Tip: This number can be used in Date objects.
length()	Returns the length, in bytes, of the file denoted by this abstract path name, or 0 if the file does not exist.
list()	Returns an array of strings naming the files and directories in the directory denoted by this abstract path name If this abstract path name does not denote a directory, then this function returns null. Otherwise an array of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path. There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.
listFiles([filter])	Returns an array of File objects denoting the files in the directory denoted by this abstract path name The filter is an optional function reference, if supplied then the function will be called with a single File object parameter (once for each File object) and if it returns true the file object will be included in the array. If this abstract path name does not denote a directory, then this function returns null. Otherwise an array of File objects is returned, one for each file or directory (if not filtered out) in the directory. There is no guarantee that the File objects in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.
setLastModified(number)	Sets the last-modified time of the file or directory named by this abstract path name
setReadOnly()	Marks the file or directory named by this abstract path name so that only read operations are allowed. After invoking this method the file or directory is guaranteed not to change until it is either deleted or marked to allow write access. Whether or not a read-only file or directory may be deleted depends upon the underlying system.

An Example of Using the File Object

Example:

function filter(myfile) {

if (myfile.getName().indexOf(“abc”) == 0) return true;

return false;

}

var file = new File(“/”);

writeln(“file.getName()=“+file.getName()+” ”);

writeln(“file.getParent()=“+file.getParent()+” ”);

writeln(“file.canRead()=“+file.canRead()+” ”);

writeln(“file.canWrite()=“+file.canWrite()+” ”);

writeln(“file.exists()=“+file.exists()+” ”);

writeln(“file.isDirectory()=“+file.isDirectory()+” ”);

writeln(“file.isFile()=“+file.isFile()+” ”);

writeln(“file.lastModified()=“+file.lastModified()+” ”);

list = file.list();

filteredList = file.listFiles(filter);

This example gets the File object for the servlet web application root, writes out its properties, gets a list of the files and directories in the web application root and then gets a filtered list of File objects. The filter will pass any File objects whose name starts with "abc". A example of the output this script might generate is shown below:

file.getName()=scriptRoot
file.getParent()=//C:/Program Files/Northgate/Concerto/appServer
file.canRead()=true
file.canWrite()=true
file.exists()=true
file.isDirectory()=true
file.isFile()=false
file.lastModified()=961148610604

The File Constructor

Using the new Operator with the File Constructor

The File constructor is used to create new File objects.

var myFile = new File(name);

A new File object for the file identified by the name is created. The name uses the script file reference to identify the file. The file can be anywhere on the host filing system. If the name argument is not present then a runtime error will be generated and the script page execution halted.

Shown below is the File object prototype chain.

Calling the File Constructor as a Function

When the constructor is run as a function without the new operator it has exactly the same behaviour as using the new operator.

File Constructor Properties

Constructor properties are read only (they can not be changed or deleted) and it is not possible to add new properties to the Constructor.

Property	Description
prototype	A reference to the Object Prototype. This property does not enumerate and can not be changed or deleted.

File Constructor Functions

Function	Description
getRootPath()	Returns the path name string of the script document root in Java format. This can then be used in Java file objects.

Write() Behaviour

When the response object is in binary mode; using the write() and writeln() functions to write a File object will result in all the bytes in the file being written to the requesting client.

Comment on this topic

Topic ID: 150054