Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.io.File

java.lang.Object
    |
    +----java.io.File

public class File
extends Object
implements Serializable, Comparable
Instances of this class represent the name of a file or directory on the host file system. A file is specified by a pathname, which can either be an absolute pathname or a pathname relative to the current working directory. The pathname must follow the naming conventions of the host platform.

The File class is intended to provide an abstraction that deals with most of the machine dependent complexities of files and pathnames in a machine-independent fashion.

Note that whenever a filename or path is used it is assumed that the host's file naming conventions are used.

Since:
JDK1.0

Field Summary
static String  pathSeparator
The system-dependent path separator string.
static char  pathSeparatorChar
The system-dependent path separator character.
static String  separator
The system-dependent path separator string.
static char  separatorChar
The system-dependent path separator character.
 

Constructor Summary
 File(String path)
Creates a File instance that represents the file whose pathname is the given path argument.
 File(String path, String name)
Creates a File instance whose pathname is the pathname of the specified directory, followed by the separator character, followed by the name argument.
 File(File dir, String name)
Creates a File instance that represents the file with the specified name in the specified directory.
 

Method Summary
boolean  canRead()
Tests if the application can read from the specified file.
boolean  canWrite()
Tests if the application can write to this file.
int  compareTo(File file)
Compares two Files lexicographically according to their canonical paths.
int  compareTo(Object o)
Compares this File to another Object according to their canonical paths.
static File  createTempFile(String pattern, File directory)

Creates an empty temporary file in the specified directory after a specified pattern.

static File  createTempFile(String prefix)
Creates an empty temporary file in the default temporary directory, after the specified pattern.
boolean  delete()
Deletes the file specified by this object.
void  deleteOnExit()
Requests that this File be deleted when the virtual machine terminates.
boolean  equals(Object obj)
Compares this object against the specified object.
boolean  exists()
Tests if this File exists.
String  getAbsolutePath()
Returns the absolute pathname of the file represented by this object.
String  getCanonicalPath()
Returns the canonical form of this File object's pathname.
String  getName()
Returns the name of the file represented by this object.
String  getParent()
Returns the parent part of the pathname of this File object, or null if the name has no parent part.
String  getPath()
Returns the pathname of the file represented by this object.
int  hashCode()
Computes a hashcode for the file.
boolean  isAbsolute()
Tests if the file represented by this File object is an absolute pathname.
boolean  isDirectory()
Tests if the file represented by this File object is a directory.
boolean  isFile()
Tests if the file represented by this File object is a "normal" file.
long  lastModified()
Returns the time that the file represented by this File object was last modified.
long  length()
Returns the length of the file represented by this File object.
String[]  list()
Returns a list of the files in the directory specified by this File object.
String[]  list(FilenameFilter filter)
Returns a list of the files in the directory specified by this File that satisfy the specified filter.
boolean  mkdir()
Creates a directory whose pathname is specified by this File object.
boolean  mkdirs()
Creates a directory whose pathname is specified by this File object, including any necessary parent directories.
boolean  renameTo(File dest)
Renames the file specified by this File object to have the pathname given by the File argument.
String  toString()
Returns a string representation of this object.
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

separator

public static final String separator
The system-dependent path separator string. This field is initialized to contain the value of the system property file.separator.
See Also:
getProperty(java.lang.String)

separatorChar

public static final char separatorChar
The system-dependent path separator character. This field is initialized to contain the first character of the value of the system property file.separator. This character separates the directory and file components in a filename.
See Also:
getProperty(java.lang.String)

pathSeparator

public static final String pathSeparator
The system-dependent path separator string. This field is initialized to contain the value of the system property path.separator.
See Also:
getProperty(java.lang.String)

pathSeparatorChar

public static final char pathSeparatorChar
The system-dependent path separator character. This field is initialized to contain the first character of the value of the system property path.separator. This character is often used to separate filenames in a sequence of files given as a "path list".
See Also:
getProperty(java.lang.String)
Constructor Detail

File

public File(String path)
Creates a File instance that represents the file whose pathname is the given path argument.
Parameters:
path - the file pathname.
Throws:
NullPointerException - if the file path is equal to null.
See Also:
getPath()

File

public File(String path,
            String name)
Creates a File instance whose pathname is the pathname of the specified directory, followed by the separator character, followed by the name argument.
Parameters:
path - the directory pathname.
name - the file pathname.
See Also:
getPath(), separator

File

public File(File dir,
            String name)
Creates a File instance that represents the file with the specified name in the specified directory.

If the directory argument is null, the resulting File instance represents a file in the (system-dependent) current directory whose pathname is the name argument. Otherwise, the File instance represents a file whose pathname is the pathname of the directory, followed by the separator character, followed by the name argument.

Parameters:
dir - the directory.
name - the file pathname.
See Also:
getPath(), separator
Method Detail

getName

public String getName()
Returns the name of the file represented by this object. The name is everything in the pathame after the last occurrence of the separator character.
Returns:
the name of the file (without any directory components) represented by this File object.
See Also:
getPath(), separator

getPath

public String getPath()
Returns the pathname of the file represented by this object.
Returns:
the pathname represented by this File object.

getAbsolutePath

public String getAbsolutePath()
Returns the absolute pathname of the file represented by this object. If this object represents an absolute pathname, then return the pathname. Otherwise, return a pathname that is a concatenation of the current user directory, the separator character, and the pathname of this file object.

The system property user.dir contains the current user directory.

Returns:
a system-dependent absolute pathname for this File.
See Also:
getPath(), isAbsolute(), getProperty(java.lang.String)

getCanonicalPath

public String getCanonicalPath() throws IOException
Returns the canonical form of this File object's pathname. The precise definition of canonical form is system-dependent, but it usually specifies an absolute pathname in which all relative references and references to the current user directory have been completely resolved. The canonical form of a pathname of a nonexistent file may not be defined.
Throws:
IOException - If an I/O error occurs, which is possible because the construction of the canonical path may require filesystem queries.

getParent

public String getParent()
Returns the parent part of the pathname of this File object, or null if the name has no parent part. The parent part is generally everything leading up to the last occurrence of the separator character, although the precise definition is system dependent. On UNIX, for example, the parent part of "/usr/lib" is "/usr", whose parent part is "/", which in turn has no parent. On Windows platforms, the parent part of "c:\java" is "c:\", which in turn has no parent.
See Also:
getPath(), getCanonicalPath(), separator

createTempFile

public static File createTempFile(String pattern,
                                  File directory) throws IOException

Creates an empty temporary file in the specified directory after a specified pattern.

Temporary files are created in the specified directory. If the specified directory is null, the default temporary directory is used. The default temporary directory may be specified using the java.io.tmpdir property. If it is not explicitely specified, it is defaulted to the underlying platform's temporary directory (such as /tmp or /var/tmp on UNIX and c:\temp on Windows).

Parameters:
pattern - a patterns after which to create the temp file name. The pattern is a string with the following syntax: prefix{#suffix}. Assuming that the # sign may be substituted with 8 characters, the complete pattern must result in a legal Java filename. The prefix is mandatory. It is recommended that the prefix be a short, meaningful string such as "hjb" or "mail". The suffix is optional, and must be delimited with a # character (Unicode 35). If a delimited character is to be included in either the prefix or the suffix, it must be escaped with the \ (Unicode 92) character. If no suffix is specified, the file will have the ".tmp" extension. Case may not be preserved, and if a suffix is provided, the suffix may be truncated. If the suffix contains an extension, only the first three characters in the extension are guaranteed to be preserved.
directory - the directory in which the temporary file is to be created. If this argument is not null, the directory must exist or an exception will be thrown. If the argument is null, it will be defaulted to the standard temporary directory.
Throws:
IllegalArgumentException - if the pattern is not valid.
IOException - if the runtime is unable to create the temporary file because of an unexpected condition, such as when the directory specified does not exist, there is no space left on the device, etc.
SecurityException - if a security manager exists, its checkWrite method is called with the result argument to see if the application is allowed read access to the file.

createTempFile

public static File createTempFile(String prefix) throws IOException
Creates an empty temporary file in the default temporary directory, after the specified pattern.

This call is equivalent to calling createTempFile(String, File) with a null argument for the directory.

Parameters:
pattern - a patterns after which to create the temp file name.
Throws:
IllegalArgumentException - if the pattern is not valid.
IOException - if the runtime is unable to create the temporary file because of an unexpected condition, such as when the directory specified does not exist, there is no space left on the device, etc.
SecurityException - if a security manager exists, its checkWrite method is called with the result argument to see if the application is allowed read access to the file.
See Also:
createTempFile(java.lang.String, java.io.File)

deleteOnExit

public void deleteOnExit()
Requests that this File be deleted when the virtual machine terminates. Deletion will be attempted only for normal termination of the virtual machine, as defined by the Java Language Specification (12.9).

Once deletion has been requested, it is not possible to cancel the request. This method should therefore be used carefully.

Throws:
SecurityException - if a security manager exists, its checkDelete method is called with the pathname of this File to see if the application is allowed to delete the file.
See Also:
delete

exists

public boolean exists()
Tests if this File exists.
Returns:
true if the file specified by this object exists; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), checkRead(java.lang.String)

canWrite

public boolean canWrite()
Tests if the application can write to this file.
Returns:
true if and only if the file system actually contains a file specified by the path of this file and the application is allowed to write to the file; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkWrite method is called with the pathname of this File to see if the application is allowed write access to the file.
See Also:
getPath(), checkWrite(java.lang.String)

canRead

public boolean canRead()
Tests if the application can read from the specified file.
Returns:
true if the file specified by this object exists and the application can read the file; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), checkRead(java.lang.String)

isFile

public boolean isFile()
Tests if the file represented by this File object is a "normal" file.

A file is "normal" if it is not a directory and, in addition, satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file.

Returns:
true if the file specified by this object exists and is a "normal" file; false otherwise.
Throws:
SecurityException - If a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), checkRead(java.lang.String)

isDirectory

public boolean isDirectory()
Tests if the file represented by this File object is a directory.
Returns:
true if this File exists and is a directory; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), checkRead(java.lang.String)

isAbsolute

public boolean isAbsolute()
Tests if the file represented by this File object is an absolute pathname. The definition of an absolute pathname is system dependent. For example, on UNIX, a pathname is absolute if its first character is the separator character. On Windows platforms, a pathname is absolute if its first character is an ASCII '\' or '/', or if it begins with a letter followed by a colon.
Returns:
true if the pathname indicated by the File object is an absolute pathname; false otherwise.
See Also:
getPath(), separator

lastModified

public long lastModified()
Returns the time that the file represented by this File object was last modified.

The return value is system dependent and should only be used to compare with other values returned by last modified. It should not be interpreted as an absolute time.

Returns:
the time the file specified by this object was last modified, or 0L if the specified file does not exist.
Throws:
SecurityException - if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), checkRead(java.lang.String)

length

public long length()
Returns the length of the file represented by this File object.
Returns:
the length, in bytes, of the file specified by this object, or 0L if the specified file does not exist.
Throws:
SecurityException - if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), checkRead(java.lang.String)

mkdir

public boolean mkdir()
Creates a directory whose pathname is specified by this File object.
Returns:
true if the directory could be created; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkWrite method is called with the pathname of this File to see if the application is allowed write access to the file.
See Also:
getPath(), checkWrite(java.lang.String)

renameTo

public boolean renameTo(File dest)
Renames the file specified by this File object to have the pathname given by the File argument.
Parameters:
dest - the new filename.
Returns:
true if the renaming succeeds; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkWrite method is called both with the pathname of this file object and with the pathname of the destination target object to see if the application is allowed to write to both files.
See Also:
getPath(), checkWrite(java.lang.String)

mkdirs

public boolean mkdirs()
Creates a directory whose pathname is specified by this File object, including any necessary parent directories.
Returns:
true if the directory (or directories) could be created; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkWrite method is called with the pathname of each of the directories that is to be created, before any of the directories are created.
See Also:
getPath(), checkWrite(java.lang.String)

list

public String[] list()
Returns a list of the files in the directory specified by this File object.
Returns:
an array of file names in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).
Throws:
SecurityException - If a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), checkRead(java.lang.String)

list

public String[] list(FilenameFilter filter)
Returns a list of the files in the directory specified by this File that satisfy the specified filter.
Parameters:
filter - a filename filter.
Returns:
an array of file names in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).
Throws:
SecurityException - If a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also:
getPath(), FilenameFilter, checkRead(java.lang.String)

delete

public boolean delete()
Deletes the file specified by this object. If the target file to be deleted is a directory, it must be empty for deletion to succeed.
Returns:
true if the file is successfully deleted; false otherwise.
Throws:
SecurityException - if a security manager exists, its checkDelete method is called with the pathname of this File to see if the application is allowed to delete the file.
See Also:
getPath(), checkDelete(java.lang.String)

hashCode

public int hashCode()
Computes a hashcode for the file.
Returns:
a hash code value for this File object.
Overrides:
hashCode in class Object

equals

public boolean equals(Object obj)
Compares this object against the specified object. Returns true if and only if the argument is not null and is a File object whose pathname is equal to the pathname of this object.
Parameters:
obj - the object to compare with.
Returns:
true if the objects are the same; false otherwise.
Overrides:
equals in class Object

compareTo

public int compareTo(File file)
Compares two Files lexicographically according to their canonical paths.
Implements:
compareTo in interface Comparable
Parameters:
file - the File to be compared.
Returns:
the value 0 if the argument File's pathname is equal to this File's; a value less than 0 if this File's pathname is lexicographically less than the File argument's; and a value greater than 0 if this File's pathname is lexicographically greater than the File argument's.

compareTo

public int compareTo(Object o)
Compares this File to another Object according to their canonical paths. If the Object is a File, this function behaves like compareTo(File). Otherwise, it throws a ClassCastException (as Files are comparable only to other Files).
Implements:
compareTo in interface Comparable
Parameters:
o - the Object to be compared.
Returns:
the value 0 if the argument is a File whose pathname is equal to this File's; a value less than 0 if the argument is a File whose pathname is lexicographically greater than this File's; and a value greater than 0 if the argument is a File whosse pathname is lexicographically less than this File's.
Throws:
ClassCastException - if the argument is not a File.
See Also:
Comparable

toString

public String toString()
Returns a string representation of this object.
Returns:
a string giving the pathname of this object.
Overrides:
toString in class Object
See Also:
getPath()

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.