java.io
Class File

java.lang.Object
  java.io.File

All Implemented Interfaces:

Serializable, Comparable<File>

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

File is a class which represents a file name or directory. The file may be absolute relative to the root directory of the file system or relative to the current directory in which the program is running.

This class provides methods for querying/changing information about the file and also directory listing capabilities if the File represents a directory.

When manipulating file paths, the static fields of this class may be used to determine the platform specific separators.

See Also:

Serializable, Comparable, Serialized Form

Field Summary

static String	pathSeparator System dependent path separator String.
static char	pathSeparatorChar System dependent path separator character.
(package private) byte[]	properPath
static String	separator System dependent file separator String.
static char	separatorChar System dependent file separator character.

Constructor Summary

File(File dir, String name)
Constructs a new File using the specified directory and name.

File(String path)
Constructs a new File using the specified path.

File(String dirPath, String name)
Constructs a new File using the specified directory and name placing a path separator between the two.

File(URI uri)
Constructs a new File using the path of the specified URI uri needs to be an absolute and hierarchical URI with file scheme, and non-empty path component, but with undefined authority, query or fragment components.

Method Summary

boolean	canRead() Returns a boolean indicating whether or not the current context is allowed to read this File.
boolean	canWrite() Returns a boolean indicating whether or not the current context is allowed to write to this File.
int	compareTo(File another) Returns the relative sort ordering of paths for the receiver and given argument.
boolean	createNewFile() Creates the file specified by this File.
static File	createTempFile(String prefix, String suffix) Creates an empty temporary file using the given prefix and suffix as part of the file name.
static File	createTempFile(String prefix, String suffix, File directory) Creates an empty temporary file in the given directory using the given prefix and suffix as part of the file name.
boolean	delete() Deletes the file specified by this File.
void	deleteOnExit() When the virtual machine terminates, any abstract files which have been sent deleteOnExit() will be deleted.
boolean	equals(Object obj) Compares the argument obj to the receiver, and returns true if they represent the same object using a path specific comparison.
boolean	exists() Returns a boolean indicating whether or not this File can be found on the underlying file system.
File	getAbsoluteFile() Returns a new File constructed using the absolute file path of this File.
String	getAbsolutePath() Returns the absolute file path of this File.
File	getCanonicalFile() Returns a new File created using the canonical file path of this File.
String	getCanonicalPath() Returns the absolute file path of this File with all references resolved.
String	getName() Returns the filename (not directory) of this File.
String	getParent() Returns the pathname of the parent of this File.
File	getParentFile() Returns a new File made from the pathname of the parent of this File.
String	getPath() Returns the file path of this File.
int	hashCode() Returns an integer hash code for the receiver.
boolean	isAbsolute() Returns if this File is an absolute pathname.
boolean	isDirectory() Returns if this File represents a directory on the underlying file system.
boolean	isFile() Returns if this File represents a file on the underlying file system.
boolean	isHidden() Returns whether or not this file is a hidden file as defined by the operating system.
long	lastModified() Returns the time this File was last modified.
long	length() Returns the length of this File in bytes.
String[]	list() Returns an array of Strings representing the file names in the directory represented by this File.
String[]	list(FilenameFilter filter) Returns an array of Strings representing the file names in the directory represented by this File that match a specific filter.
File[]	listFiles() Returns an array of Files representing the file names in the directory represented by this File.
File[]	listFiles(FileFilter filter) Returns an array of Files representing the file names in the directory represented by this File that match a specific filter.
File[]	listFiles(FilenameFilter filter) Returns an array of Files representing the file names in the directory represented by this File that match a specific filter.
static File[]	listRoots() Lists the filesystem roots.
boolean	mkdir() Creates the directory named by the trailing filename of this File.
boolean	mkdirs() Create all the directories needed for this File.
(package private) byte[]	properPath(boolean internal) Answer a String representing the proper path for the receiver.
boolean	renameTo(File dest) Renames this File to the name represented by the File dest.
boolean	setLastModified(long time) Sets the time this File was last modified.
boolean	setReadOnly() Marks this file or directory to be read-only as defined by the operating system.
String	toString() Returns a string containing a concise, human-readable description of the receiver.
URI	toURI() Returns a file URI for this File.
URL	toURL() Returns a file URL for this File.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

properPath

transient byte[] properPath

separatorChar

public static final char separatorChar

System dependent file separator character.

separator

public static final String separator

System dependent file separator String. The initial value of this field is the System property "file.separator".

pathSeparatorChar

public static final char pathSeparatorChar

System dependent path separator character.

pathSeparator

public static final String pathSeparator

System dependent path separator String. The initial value of this field is the System property "path.separator".

Constructor Detail

File

public File(File dir,
            String name)

Constructs a new File using the specified directory and name.

Parameters:

dir - the directory for the file name

name - the file name to be contained in the dir

File

public File(String path)

Constructs a new File using the specified path.

Parameters:

path - the path to be used for the file

File

public File(String dirPath,
            String name)

Constructs a new File using the specified directory and name placing a path separator between the two.

Parameters:

dirPath - the directory for the file name

name - the file name to be contained in the dir

File

public File(URI uri)

Constructs a new File using the path of the specified URI uri needs to be an absolute and hierarchical URI with file scheme, and non-empty path component, but with undefined authority, query or fragment components.

Parameters:

uri - the URI instance which will be used to construct this file

Throws:

IllegalArgumentException - if uri does not comply with the conditions above.

See Also:

toURI(), URI

Method Detail

listRoots

public static File[] listRoots()

Lists the filesystem roots. The Java platform may support zero or more filesystems, each with its own platform-dependent root. Further, the canonical pathname of any file on the system will always begin with one of the returned filesystem roots.

Returns:

the array of filesystem roots

canRead

public boolean canRead()

Returns a boolean indicating whether or not the current context is allowed to read this File.

Returns:

true if this File can be read, false otherwise.

See Also:

SecurityManager.checkRead(FileDescriptor)

canWrite

public boolean canWrite()

Returns a boolean indicating whether or not the current context is allowed to write to this File.

Returns:

true if this File can be written, false otherwise.

See Also:

SecurityManager.checkWrite(FileDescriptor)

compareTo

public int compareTo(File another)

Returns the relative sort ordering of paths for the receiver and given argument. The ordering is platform dependent.

Specified by:

compareTo in interface Comparable<File>

Parameters:

another - a File to compare the receiver to

Returns:

an int determined by comparing the two paths. The meaning is described in the Comparable interface.

See Also:

Comparable

delete

public boolean delete()

Deletes the file specified by this File. Directories must be empty before they will be deleted.

Returns:

true if this File was deleted, false otherwise.

Throws:

SecurityException - in case a SecurityManager is installed, and it denies the request.

See Also:

SecurityManager.checkDelete(java.lang.String)

deleteOnExit

public void deleteOnExit()

When the virtual machine terminates, any abstract files which have been sent deleteOnExit() will be deleted. This will only happen when the virtual machine terminates normally as described by the Java Language Specification section 12.9.

Throws:

SecurityException - in case a SecurityManager is installed, and it denies the request.

equals

public boolean equals(Object obj)

Compares the argument obj to the receiver, and returns true if they represent the same object using a path specific comparison.

Overrides:

equals in class Object

Parameters:

obj - the Object to compare with this Object

Returns:

true if the object is the same as this object, false otherwise.

See Also:

Object.hashCode()

exists

public boolean exists()

Returns a boolean indicating whether or not this File can be found on the underlying file system.

Returns:

true if this File exists, false otherwise.

See Also:

getPath(), SecurityManager.checkRead(FileDescriptor)

getAbsolutePath

public String getAbsolutePath()

Returns the absolute file path of this File.

Returns:

the absolute file path

See Also:

SecurityManager.checkPropertyAccess(java.lang.String)

getAbsoluteFile

public File getAbsoluteFile()

Returns a new File constructed using the absolute file path of this File.

Returns:

a new File from this absolute file path

See Also:

SecurityManager.checkPropertyAccess(java.lang.String)

getCanonicalPath

public String getCanonicalPath()
                        throws IOException

Returns the absolute file path of this File with all references resolved. An absolute file path is one which begins at the root of the file system. The canonical path is one in which all references have been resolved. For the cases of '..' and '.' where the file system supports parent and working directory respectively, these should be removed and replaced with a direct directory reference. If the File does not exist, getCanonicalPath() may not resolve any references and simply return an absolute path name or throw an IOException.

Returns:

the canonical file path

Throws:

IOException - if an IO error occurs

See Also:

SecurityManager.checkPropertyAccess(java.lang.String)

getCanonicalFile

public File getCanonicalFile()
                      throws IOException

Returns a new File created using the canonical file path of this File. Equivalent to new File(this.getCanonicalPath()).

Returns:

the canonical file path

Throws:

IOException - If an IO error occurs

See Also:

SecurityManager.checkPropertyAccess(java.lang.String)

getName

public String getName()

Returns the filename (not directory) of this File.

Returns:

the filename or empty string

getParent

public String getParent()

Returns the pathname of the parent of this File. This is the path up to but not including the last name. null is returned when there is no parent.

Returns:

the parent name or null

getParentFile

public File getParentFile()

Returns a new File made from the pathname of the parent of this File. This is the path up to but not including the last name. null is returned when there is no parent.

Returns:

a new File representing parent or null

getPath

public String getPath()

Returns the file path of this File.

Returns:

the file path

hashCode

public int hashCode()

Returns an integer hash code for the receiver. Any two objects which answer true when passed to equals must answer the same value for this method.

Overrides:

hashCode in class Object

Returns:

the receiver's hash

See Also:

equals(java.lang.Object)

isAbsolute

public boolean isAbsolute()

Returns if this File is an absolute pathname. Whether a pathname is absolute is platform specific. On UNIX it is if the path starts with the character '/', on Windows it is absolute if either it starts with '\', '/', '\\' (to represent a file server), or a letter followed by a colon.

Returns:

true if this File is absolute, false otherwise.

See Also:

getPath()

isDirectory

public boolean isDirectory()

Returns if this File represents a directory on the underlying file system.

Returns:

true if this File is a directory, false otherwise.

See Also:

getPath(), SecurityManager.checkRead(FileDescriptor)

isFile

public boolean isFile()

Returns if this File represents a file on the underlying file system.

Returns:

true if this File is a file, false otherwise.

See Also:

getPath(), SecurityManager.checkRead(FileDescriptor)

isHidden

public boolean isHidden()

Returns whether or not this file is a hidden file as defined by the operating system.

Returns:

true if the file is hidden, false otherwise.

lastModified

public long lastModified()

Returns the time this File was last modified.

Returns:

the time this File was last modified.

See Also:

getPath(), SecurityManager.checkRead(FileDescriptor)

setLastModified

public boolean setLastModified(long time)

Sets the time this File was last modified.

Parameters:

time - The time to set the file as last modified.

Returns:

the time this File was last modified.

See Also:

SecurityManager.checkWrite(FileDescriptor)

setReadOnly

public boolean setReadOnly()

Marks this file or directory to be read-only as defined by the operating system.

Returns:

true if the operation was a success, false otherwise

length

public long length()

Returns the length of this File in bytes.

Returns:

the number of bytes in the file.

See Also:

getPath(), SecurityManager.checkRead(FileDescriptor)

list

public String[] list()

Returns an array of Strings representing the file names in the directory represented by this File. If this File is not a directory the result is null.

The entries . and .. representing current directory and parent directory are not returned as part of the list.

Returns:

an array of Strings or null.

See Also:

getPath(), isDirectory(), SecurityManager.checkRead(FileDescriptor)

listFiles

public File[] listFiles()

Returns an array of Files representing the file names in the directory represented by this File. If this File is not a directory the result is null. The Files returned will be absolute if this File is absolute, relative otherwise.

Returns:

an array of Files or null.

See Also:

getPath(), list(), isDirectory()

listFiles

public File[] listFiles(FilenameFilter filter)

Returns an array of Files representing the file names in the directory represented by this File that match a specific filter. If this File is not a directory the result is null. If the filter is null then all filenames match.

The entries . and .. representing current directory and parent directory are not returned as part of the list.

Parameters:

filter - the filter to match names to or null.

Returns:

an array of Files or null.

See Also:

list(FilenameFilter filter), getPath(), isDirectory(), SecurityManager.checkRead(FileDescriptor)

listFiles

public File[] listFiles(FileFilter filter)

Returns an array of Files representing the file names in the directory represented by this File that match a specific filter. If this File is not a directory the result is null. If the filter is null then all filenames match.

The entries . and .. representing current directory and parent directory are not returned as part of the list.

Parameters:

filter - the filter to match names to or null.

Returns:

an array of Files or null.

See Also:

getPath(), isDirectory(), SecurityManager.checkRead(FileDescriptor)

list

public String[] list(FilenameFilter filter)

Returns an array of Strings representing the file names in the directory represented by this File that match a specific filter. If this File is not a directory the result is null. If the filter is null then all filenames match.

The entries . and .. representing current directory and parent directory are not returned as part of the list.

Parameters:

filter - the filter to match names to or null.

Returns:

an array of Strings or null.

See Also:

getPath(), isDirectory(), SecurityManager.checkRead(FileDescriptor)

mkdir

public boolean mkdir()

Creates the directory named by the trailing filename of this File. Not all directories required to create this File are created.

Returns:

true if the directory was created, false otherwise.

See Also:

getPath(), SecurityManager.checkWrite(FileDescriptor)

mkdirs

public boolean mkdirs()

Create all the directories needed for this File. If the terminal directory already exists, answer false. If the directories were created successfully, answer true.

Returns:

true if the necessary directories were created, false otherwise.

createNewFile

public boolean createNewFile()
                      throws IOException

Creates the file specified by this File. If the file already exists this method returns false. Otherwise, if the file is created successfully, the result is true. An IOException will be thrown if the directory to contain this file does not exist.

Returns:

true if this File was created, false otherwise.

Throws:

IOException - if an I/O error occurs or the directory does not exist.

See Also:

SecurityManager.checkWrite(FileDescriptor)

createTempFile

public static File createTempFile(String prefix,
                                  String suffix)
                           throws IOException

Creates an empty temporary file using the given prefix and suffix as part of the file name. If suffix is null, .tmp is used.

Parameters:

prefix - the prefix to the temp file name

suffix - the suffix to the temp file name

Returns:

the temporary file

Throws:

IOException - If an error occurs when writing the file

createTempFile

public static File createTempFile(String prefix,
                                  String suffix,
                                  File directory)
                           throws IOException

Creates an empty temporary file in the given directory using the given prefix and suffix as part of the file name.

Parameters:

prefix - the prefix to the temp file name

suffix - the suffix to the temp file name

directory - the location to which the temp file is to be written, or null for the default temp location

Returns:

the temporary file

Throws:

IOException - If an error occurs when writing the file

properPath

byte[] properPath(boolean internal)

Answer a String representing the proper path for the receiver. If the receiver is absolute do not prepend the user.dir property, otherwise do.

Parameters:

internal - is user.dir internal

Returns:

the proper path

renameTo

public boolean renameTo(File dest)

Renames this File to the name represented by the File dest. This works for both normal files and directories.

Parameters:

dest - the File containing the new name.

Returns:

true if the File was renamed, false otherwise.

See Also:

getPath(), SecurityManager.checkRead(FileDescriptor), SecurityManager.checkWrite(FileDescriptor)

toString

public String toString()

Returns a string containing a concise, human-readable description of the receiver.

Overrides:

toString in class Object

Returns:

a printable representation for the receiver.

toURI

public URI toURI()

Returns a file URI for this File. The URI is System dependent and may not be transferable between different operating/file systems.

Returns:

a file URI for this File.

toURL

public URL toURL()
          throws MalformedURLException

Returns a file URL for this File. The URL is System dependent and may not be transferable between different operating/file systems.

Returns:

a file URL for this File.

Throws:

MalformedURLException - if the path cannot be transformed into an URL