java.io

Class File

Implemented Interfaces:
Comparable<T>, Serializable

public class File
extends Object
implements Serializable, Comparable<T>

This class represents a file or directory on a local disk. It provides facilities for dealing with a variety of systems that use various types of path separators ("/" versus "\", for example). It also contains method useful for creating and deleting files and directories.
See Also:
Serialized Form

Field Summary

static String
pathSeparator
This is the string that is used to separate the host name from the path name in paths that include the host name.
static char
pathSeparatorChar
This is the first character of the string used to separate the host name from the path name in paths that include a host.
static String
separator
This is the path separator string for the current host.
static char
separatorChar
This is the first character of the file separator string.

Constructor Summary

File(File directory, String name)
This method initializes a new File object to represent a file in the specified directory.
File(String name)
This method initializes a new File object to represent a file with the specified path.
File(String dirPath, String name)
This method initializes a new File object to represent a file in the specified named directory.
File(URI uri)
This method initializes a new File object to represent a file corresponding to the specified file: protocol URI.

Method Summary

boolean
canExecute()
This method tests whether or not the current thread is allowed to to execute the file pointed to by this object.
boolean
canRead()
This method tests whether or not the current thread is allowed to to read the file pointed to by this object.
boolean
canWrite()
This method test whether or not the current thread is allowed to write to this object.
int
compareTo(File other)
This method compares the specified File to this one to test for equality.
boolean
createNewFile()
This method creates a new file of zero length with the same name as the path of this File object if an only if that file does not already exist.
static File
createTempFile(String prefix, String suffix)
This method creates a temporary file in the system temporary directory.
static File
createTempFile(String prefix, String suffix, File directory)
This method creates a temporary file in the specified directory.
boolean
delete()
This method deletes the file represented by this object.
void
deleteOnExit()
Calling this method requests that the file represented by this object be deleted when the virtual machine exits.
boolean
equals(Object obj)
This method tests two File objects for equality by comparing the path of the specified File against the path of this object.
boolean
exists()
This method tests whether or not the file represented by the object actually exists on the filesystem.
File
getAbsoluteFile()
This method returns a File object representing the absolute path of this object.
String
getAbsolutePath()
This method returns the path of this file as an absolute path name.
File
getCanonicalFile()
This method returns a File object representing the canonical path of this object.
String
getCanonicalPath()
This method returns a canonical representation of the pathname of this file.
long
getFreeSpace()
Get the free space in the partition pointed by this file path, in bytes.
String
getName()
This method returns the name of the file.
String
getParent()
This method returns a String the represents this file's parent.
File
getParentFile()
This method returns a File object representing the parent file of this one.
String
getPath()
Returns the path name that represents this file.
long
getTotalSpace()
Get the total space for the partition pointed by this file path, in bytes.
long
getUsableSpace()
Get the usable space in the partition pointed by this file path, in bytes.
int
hashCode()
This method returns a hash code representing this file.
boolean
isAbsolute()
This method returns true if this object represents an absolute file path and false if it does not.
boolean
isDirectory()
This method tests whether or not the file represented by this object is a directory.
boolean
isFile()
This method tests whether or not the file represented by this object is a "plain" file.
boolean
isHidden()
This method tests whether or not this file represents a "hidden" file.
long
lastModified()
This method returns the last modification time of this file.
long
length()
This method returns the length of the file represented by this object, or 0 if the specified file does not exist.
String[]
list()
This method returns a array of String's representing the list of files is then directory represented by this object.
String[]
list(FilenameFilter filter)
This method returns a array of String's representing the list of files is then directory represented by this object.
File[]
listFiles()
This method returns an array of File objects representing all the files in the directory represented by this object.
File[]
listFiles(FileFilter filter)
This method returns an array of File objects representing all the files in the directory represented by this object.
File[]
listFiles(FilenameFilter filter)
This method returns an array of File objects representing all the files in the directory represented by this object.
static File[]
listRoots()
This method returns an array of filesystem roots.
boolean
mkdir()
This method creates a directory for the path represented by this object.
boolean
mkdirs()
This method creates a directory for the path represented by this file.
boolean
renameTo(File dest)
This method renames the file represented by this object to the path of the file represented by the argument File.
boolean
setExecutable(boolean executable)
This method sets the owner's execute permission for the File represented by this object.
boolean
setExecutable(boolean executable, boolean ownerOnly)
This method sets the execute permissions for the File represented by this object.
boolean
setLastModified(long time)
This method sets the modification time on the file to the specified value.
boolean
setReadOnly()
This method sets the file represented by this object to be read only.
boolean
setReadable(boolean readable)
This method sets the owner's read permission for the File represented by this object.
boolean
setReadable(boolean readable, boolean ownerOnly)
This method sets the read permissions for the File represented by this object.
boolean
setWritable(boolean writable)
This method sets the owner's write permission for the File represented by this object.
boolean
setWritable(boolean writable, boolean ownerOnly)
This method sets the write permissions for the File represented by this object.
String
toString()
This method returns a String that is the path name of the file as returned by getPath.
URI
toURI()
URL
toURL()
This method returns a URL with the file: protocol that represents this file.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

pathSeparator

public static final String pathSeparator
This is the string that is used to separate the host name from the path name in paths that include the host name. It is the value of the path.separator system property.

pathSeparatorChar

public static final char pathSeparatorChar
This is the first character of the string used to separate the host name from the path name in paths that include a host. The separator string is taken from the path.separator system property.

separator

public static final String separator
This is the path separator string for the current host. This field contains the value of the file.separator system property. An example separator string would be "/" on the GNU system.

separatorChar

public static final char separatorChar
This is the first character of the file separator string. On many hosts (for example, on the GNU system), this represents the entire separator string. The complete separator string is obtained from the file.separatorsystem property.

Constructor Details

File

public File(File directory,
            String name)
This method initializes a new File object to represent a file in the specified directory. If the directory argument is null, the file is assumed to be in the current directory as specified by the user.dir system property
Parameters:
directory - The directory this file resides in
name - The name of the file

File

public File(String name)
This method initializes a new File object to represent a file with the specified path.
Parameters:
name - The path name of the file

File

public File(String dirPath,
            String name)
This method initializes a new File object to represent a file in the specified named directory. The path name to the file will be the directory name plus the separator string plus the file name. If the directory path name ends in the separator string, another separator string will still be appended.
Parameters:
dirPath - The path to the directory the file resides in
name - The name of the file

File

public File(URI uri)
This method initializes a new File object to represent a file corresponding to the specified file: protocol URI.
Parameters:
uri - The URI
Throws:
IllegalArgumentException - if the URI is not hierarchical

Method Details

canExecute

public boolean canExecute()
This method tests whether or not the current thread is allowed to to execute the file pointed to by this object. This will be true if and and only if 1) the file exists and 2) the SecurityManager (if any) allows access to the file via it's checkExec method 3) the file is executable.
Returns:
true if execution is allowed, false otherwise
Throws:
SecurityException - If the SecurityManager does not allow access to the file

canRead

public boolean canRead()
This method tests whether or not the current thread is allowed to to read the file pointed to by this object. This will be true if and and only if 1) the file exists and 2) the SecurityManager (if any) allows access to the file via it's checkRead method 3) the file is readable.
Returns:
true if reading is allowed, false otherwise
Throws:
SecurityException - If the SecurityManager does not allow access to the file

canWrite

public boolean canWrite()
This method test whether or not the current thread is allowed to write to this object. This will be true if and only if 1) The SecurityManager (if any) allows write access to the file and 2) The file exists and 3) The file is writable. To determine whether or not a non-existent file can be created, check the parent directory for write access.
Returns:
true if writing is allowed, false otherwise
Throws:
SecurityException - If the SecurityManager does not allow access to the file

compareTo

public int compareTo(File other)
This method compares the specified File to this one to test for equality. It does this by comparing the canonical path names of the files.

The canonical paths of the files are determined by calling the getCanonicalPath method on each object.

This method returns a 0 if the specified Object is equal to this one, a negative value if it is less than this one a positive value if it is greater than this one.

Returns:
An integer as described above
Since:
1.2

createNewFile

public boolean createNewFile()
            throws IOException
This method creates a new file of zero length with the same name as the path of this File object if an only if that file does not already exist.

A SecurityManager.checkWrite check is done prior to performing this action.

Returns:
true if the file was created, false if the file alread existed.
Throws:
IOException - If an I/O error occurs
SecurityException - If the SecurityManager will not allow this operation to be performed.
Since:
1.2

createTempFile

public static File createTempFile(String prefix,
                                  String suffix)
            throws IOException
This method creates a temporary file in the system temporary directory. The files created are guaranteed not to currently exist and the same file name will never be used twice in the same virtual machine instance. The system temporary directory is determined by examinging the java.io.tmpdir system property.

The prefix parameter is a sequence of at least three characters that are used as the start of the generated filename. The suffix parameter is a sequence of characters that is used to terminate the file name. This parameter may be null and if it is, the suffix defaults to ".tmp".

If a SecurityManager exists, then its checkWrite method is used to verify that this operation is permitted.

This method is identical to calling createTempFile(prefix, suffix, null).

Parameters:
prefix - The character prefix to use in generating the path name.
suffix - The character suffix to use in generating the path name.
Throws:
IllegalArgumentException - If the prefix or suffix are not valid.
SecurityException - If there is no permission to perform this operation
IOException - If an error occurs

createTempFile

public static File createTempFile(String prefix,
                                  String suffix,
                                  File directory)
            throws IOException
This method creates a temporary file in the specified directory. If the directory name is null, then this method uses the system temporary directory. The files created are guaranteed not to currently exist and the same file name will never be used twice in the same virtual machine instance. The system temporary directory is determined by examinging the java.io.tmpdir system property.

The prefix parameter is a sequence of at least three characters that are used as the start of the generated filename. The suffix parameter is a sequence of characters that is used to terminate the file name. This parameter may be null and if it is, the suffix defaults to ".tmp".

If a SecurityManager exists, then its checkWrite method is used to verify that this operation is permitted.

Parameters:
prefix - The character prefix to use in generating the path name.
suffix - The character suffix to use in generating the path name.
directory - The directory to create the file in, or null for the default temporary directory
Throws:
IllegalArgumentException - If the patterns is not valid
SecurityException - If there is no permission to perform this operation
IOException - If an error occurs
Since:
1.2

delete

public boolean delete()
This method deletes the file represented by this object. If this file is a directory, it must be empty in order for the delete to succeed.
Returns:
true if the file was deleted, false otherwise
Throws:
SecurityException - If deleting of the file is not allowed

deleteOnExit

public void deleteOnExit()
Calling this method requests that the file represented by this object be deleted when the virtual machine exits. Note that this request cannot be cancelled. Also, it will only be carried out if the virtual machine exits normally.
Throws:
SecurityException - If deleting of the file is not allowed
Since:
1.2

equals

public boolean equals(Object obj)
This method tests two File objects for equality by comparing the path of the specified File against the path of this object. The two objects are equal if an only if 1) The argument is not null 2) The argument is a File object and 3) The path of the Fileargument is equal to the path of this object.

The paths of the files are determined by calling the getPath() method on each object.

Overrides:
equals in interface Object
Returns:
true if the two objects are equal, false otherwise.

exists

public boolean exists()
This method tests whether or not the file represented by the object actually exists on the filesystem.
Returns:
true if the file exists, falseotherwise.
Throws:
SecurityException - If reading of the file is not permitted

getAbsoluteFile

public File getAbsoluteFile()
This method returns a File object representing the absolute path of this object.
Returns:
A File with the absolute path of the object.
Since:
1.2

getAbsolutePath

public String getAbsolutePath()
This method returns the path of this file as an absolute path name. If the path name is already absolute, then it is returned. Otherwise the value returned is the current directory plus the separatory string plus the path of the file. The current directory is determined from the user.dir system property.
Returns:
The absolute path of this file

getCanonicalFile

public File getCanonicalFile()
            throws IOException
This method returns a File object representing the canonical path of this object.
Returns:
A File instance representing the canonical path of this object.
Throws:
IOException - If an error occurs.
Since:
1.2

getCanonicalPath

public String getCanonicalPath()
            throws IOException
This method returns a canonical representation of the pathname of this file. The actual form of the canonical representation is system-dependent. On the GNU system, conversion to canonical form involves the removal of redundant separators, references to "." and "..", and symbolic links.

Note that this method, unlike the other methods which return path names, can throw an IOException. This is because native method might be required in order to resolve the canonical path

Throws:
IOException - If an error occurs

getFreeSpace

public long getFreeSpace()
Get the free space in the partition pointed by this file path, in bytes.
Returns:
the number of free bytes in this partition.
Since:
1.6

getName

public String getName()
This method returns the name of the file. This is everything in the complete path of the file after the last instance of the separator string.
Returns:
The file name

getParent

public String getParent()
This method returns a String the represents this file's parent. null is returned if the file has no parent. The parent is determined via a simple operation which removes the name after the last file separator character, as determined by the platform.
Returns:
The parent directory of this file

getParentFile

public File getParentFile()
This method returns a File object representing the parent file of this one.
Returns:
a File for the parent of this object. null will be returned if this object does not have a parent.
Since:
1.2

getPath

public String getPath()
Returns the path name that represents this file. May be a relative or an absolute path name
Returns:
The pathname of this file

getTotalSpace

public long getTotalSpace()
Get the total space for the partition pointed by this file path, in bytes.
Returns:
the total number of bytes in this partition.
Since:
1.6

getUsableSpace

public long getUsableSpace()
Get the usable space in the partition pointed by this file path, in bytes. This is not necessarily the same as the number returned by getFreeSpace(). Implementation note: Unlike the RI, on Linux and UNIX like systems this methods take into account the reserved space for the "root" user. This means that the returned results will be a little different if a normal user or root perform the query. Also, the bytes returned should be interpreted as an hint, and may be different at each call of this method or even right after the method returns.
Returns:
the number of usable bytes in this partition.
Since:
1.6

hashCode

public int hashCode()
This method returns a hash code representing this file. It is the hash code of the path of this file (as returned by getPath()) exclusived or-ed with the value 1234321.
Overrides:
hashCode in interface Object
Returns:
The hash code for this object

isAbsolute

public boolean isAbsolute()
This method returns true if this object represents an absolute file path and false if it does not. The definition of an absolute path varies by system. As an example, on GNU systems, a path is absolute if it starts with a "/".
Returns:
true if this object represents an absolute file name, false otherwise.

isDirectory

public boolean isDirectory()
This method tests whether or not the file represented by this object is a directory. In order for this method to return true, the file represented by this object must exist and be a directory.
Returns:
true if this file is a directory, false otherwise
Throws:
SecurityException - If reading of the file is not permitted

isFile

public boolean isFile()
This method tests whether or not the file represented by this object is a "plain" file. A file is a plain file if and only if it 1) Exists, 2) Is not a directory or other type of special file.
Returns:
true if this is a plain file, false otherwise
Throws:
SecurityException - If reading of the file is not permitted

isHidden

public boolean isHidden()
This method tests whether or not this file represents a "hidden" file. On GNU systems, a file is hidden if its name begins with a "." character. Files with these names are traditionally not shown with directory listing tools.
Returns:
true if the file is hidden, false otherwise.
Throws:
SecurityException - if a security manager exists and denies read access to this file.
Since:
1.2

lastModified

public long lastModified()
This method returns the last modification time of this file. The time value returned is an abstract value that should not be interpreted as a specified time value. It is only useful for comparing to other such time values returned on the same system. In that case, the larger value indicates a more recent modification time.

If the file does not exist, then a value of 0 is returned.

Returns:
The last modification time of the file
Throws:
SecurityException - If reading of the file is not permitted

length

public long length()
This method returns the length of the file represented by this object, or 0 if the specified file does not exist.
Returns:
The length of the file
Throws:
SecurityException - If reading of the file is not permitted

list

public String[] list()
This method returns a array of String's representing the list of files is then directory represented by this object. If this object represents a non-directory file or a non-existent file, then null is returned. The list of files will not contain any names such as "." or ".." which indicate the current or parent directory. Also, the names are not guaranteed to be sorted.

A SecurityManager check is made prior to reading the directory. If read access to the directory is denied, an exception will be thrown.

Returns:
An array of files in the directory, or null if this object does not represent a valid directory.
Throws:
SecurityException - If read access is not allowed to the directory by the SecurityManager

list

public String[] list(FilenameFilter filter)
This method returns a array of String's representing the list of files is then directory represented by this object. If this object represents a non-directory file or a non-existent file, then null is returned. The list of files will not contain any names such as "." or ".." which indicate the current or parent directory. Also, the names are not guaranteed to be sorted.

In this form of the list() method, a filter is specified that allows the caller to control which files are returned in the list. The FilenameFilter specified is called for each file returned to determine whether or not that file should be included in the list.

A SecurityManager check is made prior to reading the directory. If read access to the directory is denied, an exception will be thrown.

Parameters:
filter - An object which will identify files to exclude from the directory listing.
Returns:
An array of files in the directory, or null if this object does not represent a valid directory.
Throws:
SecurityException - If read access is not allowed to the directory by the SecurityManager

listFiles

public File[] listFiles()
This method returns an array of File objects representing all the files in the directory represented by this object. If this object does not represent a directory, null is returned. Each of the returned File object is constructed with this object as its parent.

A SecurityManager check is made prior to reading the directory. If read access to the directory is denied, an exception will be thrown.

Returns:
An array of File objects for this directory.
Throws:
SecurityException - If the SecurityManager denies access to this directory.
Since:
1.2

listFiles

public File[] listFiles(FileFilter filter)
This method returns an array of File objects representing all the files in the directory represented by this object. If this object does not represent a directory, null is returned. Each of the returned File object is constructed with this object as its parent.

In this form of the listFiles() method, a filter is specified that allows the caller to control which files are returned in the list. The FileFilter specified is called for each file returned to determine whether or not that file should be included in the list.

A SecurityManager check is made prior to reading the directory. If read access to the directory is denied, an exception will be thrown.

Returns:
An array of File objects for this directory.
Throws:
SecurityException - If the SecurityManager denies access to this directory.
Since:
1.2

listFiles

public File[] listFiles(FilenameFilter filter)
This method returns an array of File objects representing all the files in the directory represented by this object. If this object does not represent a directory, null is returned. Each of the returned File object is constructed with this object as its parent.

In this form of the listFiles() method, a filter is specified that allows the caller to control which files are returned in the list. The FilenameFilter specified is called for each file returned to determine whether or not that file should be included in the list.

A SecurityManager check is made prior to reading the directory. If read access to the directory is denied, an exception will be thrown.

Returns:
An array of File objects for this directory.
Throws:
SecurityException - If the SecurityManager denies access to this directory.
Since:
1.2

listRoots

public static File[] listRoots()
This method returns an array of filesystem roots. Some operating systems have volume oriented filesystem. This method provides a mechanism for determining which volumes exist. GNU systems use a single hierarchical filesystem, so will have only one "/" filesystem root.
Returns:
An array of File objects for each filesystem root available.
Since:
1.2

mkdir

public boolean mkdir()
This method creates a directory for the path represented by this object.
Returns:
true if the directory was created, false otherwise
Throws:
SecurityException - If write access is not allowed to this file

mkdirs

public boolean mkdirs()
This method creates a directory for the path represented by this file. It will also create any intervening parent directories if necessary.
Returns:
true if the directory was created, false otherwise
Throws:
SecurityException - If write access is not allowed to this file

renameTo

public boolean renameTo(File dest)
This method renames the file represented by this object to the path of the file represented by the argument File.
Parameters:
dest - The File object representing the target name
Returns:
true if the rename succeeds, false otherwise.
Throws:
SecurityException - If write access is not allowed to the file by the SecurityMananger.

setExecutable

public boolean setExecutable(boolean executable)
This method sets the owner's execute permission for the File represented by this object. It is the same as calling setExecutable(readable, true).
Parameters:
Returns:
true if the file permissions are changed, false otherwise.
Throws:
SecurityException - If write access of the file is not permitted.
Since:
1.6

setExecutable

public boolean setExecutable(boolean executable,
                             boolean ownerOnly)
This method sets the execute permissions for the File represented by this object. If ownerOnly is set to true then only the execute permission bit for the owner of the file is changed. If ownerOnly is set to false, the file permissions are changed so that the file can be executed by everyone. On unix like systems this set the user, group and other write bits and is equal to call chmod a+x on the file.
Parameters:
Returns:
true if the file permissions are changed, false otherwise.
Throws:
SecurityException - If write access of the file is not permitted.
Since:
1.6

setLastModified

public boolean setLastModified(long time)
This method sets the modification time on the file to the specified value. This is specified as the number of seconds since midnight on January 1, 1970 GMT.
Parameters:
time - The desired modification time.
Returns:
true if the operation succeeded, false otherwise.
Throws:
IllegalArgumentException - If the specified time is negative.
SecurityException - If the SecurityManager will not allow this operation.
Since:
1.2

setReadOnly

public boolean setReadOnly()
This method sets the file represented by this object to be read only. A read only file or directory cannot be modified. Please note that GNU systems allow read only files to be deleted if the directory it is contained in is writable.
Returns:
true if the operation succeeded, false otherwise.
Throws:
SecurityException - If the SecurityManager does not allow this operation.
Since:
1.2

setReadable

public boolean setReadable(boolean readable)
This method sets the owner's read permission for the File represented by this object. It is the same as calling setReadable(readable, true).
Parameters:
Returns:
true if the file permissions are changed, false otherwise.
Throws:
SecurityException - If write access of the file is not permitted.
Since:
1.6

setReadable

public boolean setReadable(boolean readable,
                           boolean ownerOnly)
This method sets the read permissions for the File represented by this object. If ownerOnly is set to true then only the read permission bit for the owner of the file is changed. If ownerOnly is set to false, the file permissions are changed so that the file can be read by everyone. On unix like systems this sets the user, group and other read bits and is equal to call chmod a+r on the file.
Parameters:
Returns:
true if the file permissions are changed, false otherwise.
Throws:
SecurityException - If write access of the file is not permitted.
Since:
1.6

setWritable

public boolean setWritable(boolean writable)
This method sets the owner's write permission for the File represented by this object. It is the same as calling setWritable(readable, true).
Parameters:
Returns:
true if the file permissions are changed, false otherwise.
Throws:
SecurityException - If write access of the file is not permitted.
Since:
1.6

setWritable

public boolean setWritable(boolean writable,
                           boolean ownerOnly)
This method sets the write permissions for the File represented by this object. If ownerOnly is set to true then only the write permission bit for the owner of the file is changed. If ownerOnly is set to false, the file permissions are changed so that the file can be written by everyone. On unix like systems this set the user, group and other write bits and is equal to call chmod a+w on the file.
Parameters:
Returns:
true if the file permissions are changed, false otherwise.
Throws:
SecurityException - If write access of the file is not permitted.
Since:
1.6

toString

public String toString()
This method returns a String that is the path name of the file as returned by getPath.
Overrides:
toString in interface Object
Returns:
A String representation of this file

toURI

public URI toURI()
Returns:
A URI for this object.

toURL

public URL toURL()
            throws MalformedURLException
This method returns a URL with the file: protocol that represents this file. The exact form of this URL is system dependent.
Returns:
A URL for this object.
Throws:
MalformedURLException - If the URL cannot be created successfully.

File.java -- Class representing a file on disk Copyright (C) 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.