public class

File

extends Object
implements Serializable Comparable<T>
java.lang.Object
   ↳ java.io.File

Class Overview

An "abstract" representation of a file system entity identified by a pathname. The pathname may be absolute (relative to the root directory of the file system) or relative to the current directory in which the program is running.

The actual file referenced by a File may or may not exist. It may also, despite the name File, be a directory or other non-regular file.

This class provides limited functionality for getting/setting file permissions, file type, and last modified time.

Although Java doesn't specify a character encoding for filenames, on Android Java strings are converted to UTF-8 byte sequences when sending filenames to the operating system, and byte sequences returned by the operating system (from the various list methods) are converted to Java strings by decoding them as UTF-8 byte sequences.

See Also

Summary

Constants
String pathSeparator The system dependent path separator string.
char pathSeparatorChar The system dependent path separator character.
String separator The system dependent file separator string.
char separatorChar The system dependent file separator character.
Public Constructors
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 path and file name, placing a path separator between the two.
File(URI uri)
Constructs a new File using the path of the specified URI.
Public Methods
boolean canRead()
Indicates whether the current context is allowed to read from this file.
boolean canWrite()
Indicates whether the current context is allowed to write to this file.
int compareTo(File another)
Returns the relative sort ordering of the paths for this file and the file another.
boolean createNewFile()
Creates a new, empty file on the file system according to the path information stored in this file.
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.
static File createTempFile(String prefix, String suffix)
Creates an empty temporary file using the given prefix and suffix as part of the file name.
boolean delete()
Deletes this file.
void deleteOnExit()
Schedules this file to be automatically deleted once the virtual machine terminates.
boolean equals(Object obj)
Compares obj to this file and returns true if they represent the same object using a path specific comparison.
boolean exists()
Returns a boolean indicating whether this file can be found on the underlying file system.
File getAbsoluteFile()
Returns a new file constructed using the absolute path of this file.
String getAbsolutePath()
Returns the absolute path of this file.
File getCanonicalFile()
Returns a new file created using the canonical path of this file.
String getCanonicalPath()
Returns the absolute path of this file with all references resolved.
String getName()
Returns the name of the file or directory represented by 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 path of this file.
int hashCode()
Returns an integer hash code for the receiver.
boolean isAbsolute()
Indicates if this file's pathname is absolute.
boolean isDirectory()
Indicates if this file represents a directory on the underlying file system.
boolean isFile()
Indicates 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 when this file was last modified, measured in milliseconds since January 1st, 1970, midnight.
long length()
Returns the length of this file in bytes.
String[] list()
Returns an array of strings with the file names in the directory represented by this file.
String[] list(FilenameFilter filter)
Gets a list of the files in the directory represented by this file.
File[] listFiles(FileFilter filter)
Gets a list of the files in the directory represented by this file.
File[] listFiles(FilenameFilter filter)
Gets a list of the files in the directory represented by this file.
File[] listFiles()
Returns an array of files contained in the directory represented by this file.
static File[] listRoots()
Lists the file system roots.
boolean mkdir()
Creates the directory named by the trailing filename of this file.
boolean mkdirs()
Creates the directory named by the trailing filename of this file, including the complete directory path required to create this directory.
boolean renameTo(File dest)
Renames this file to the name represented by the dest file.
boolean setLastModified(long time)
Sets the time this file was last modified, measured in milliseconds since January 1st, 1970, midnight.
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 this file.
URI toURI()
Returns a Uniform Resource Identifier for this file.
URL toURL()
Returns a Uniform Resource Locator for this file.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Comparable

Constants

public static final String pathSeparator

Since: API Level 1

The system dependent path separator string. This field is a single-character string equal to String.valueOf(pathSeparatorChar).

public static final char pathSeparatorChar

Since: API Level 1

The system dependent path separator character. This field is initialized from the system property "path.separator". Later changes to that property will have no effect on this field or this class.

public static final String separator

Since: API Level 1

The system dependent file separator string. This field is a single-character string equal to String.valueOf(separatorChar).

public static final char separatorChar

Since: API Level 1

The system dependent file separator character. This field is initialized from the system property "file.separator". Later changes to that property will have no effect on this field or this class.

Public Constructors

public File (File dir, String name)

Since: API Level 1

Constructs a new file using the specified directory and name.

Parameters
dir the directory where the file is stored.
name the file's name.
Throws
NullPointerException if name is null.

public File (String path)

Since: API Level 1

Constructs a new file using the specified path.

Parameters
path the path to be used for the file.

public File (String dirPath, String name)

Since: API Level 1

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

Parameters
dirPath the path to the directory where the file is stored.
name the file's name.
Throws
NullPointerException if name is null.

public File (URI uri)

Since: API Level 1

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

Parameters
uri the Unified Resource Identifier that is used to construct this file.
Throws
IllegalArgumentException if uri does not comply with the conditions above.
See Also

Public Methods

public boolean canRead ()

Since: API Level 1

Indicates whether the current context is allowed to read from this file.

Returns
  • true if this file can be read, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies the read request.

public boolean canWrite ()

Since: API Level 1

Indicates whether the current context is allowed to write to this file.

Returns
  • true if this file can be written, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies the write request.

public int compareTo (File another)

Since: API Level 1

Returns the relative sort ordering of the paths for this file and the file another. The ordering is platform dependent.

Parameters
another a file to compare this file to
Returns
  • an int determined by comparing the two paths. Possible values are described in the Comparable interface.
See Also

public boolean createNewFile ()

Since: API Level 1

Creates a new, empty file on the file system according to the path information stored in this file.

Returns
  • true if the file has been created, false if it already exists.
Throws
IOException if it's not possible to create the file.
SecurityException if a SecurityManager is installed and it denies write access for this file.

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

Since: API Level 1

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 location for temporary files, which is taken from the "java.io.tmpdir" system property. It may be necessary to set this property to an existing, writable directory for this method to work properly.
Returns
  • the temporary file.
Throws
IllegalArgumentException if the length of prefix is less than 3.
IOException if an error occurs when writing the file.

public static File createTempFile (String prefix, String suffix)

Since: API Level 1

Creates an empty temporary file using the given prefix and suffix as part of the file name. If suffix is null, .tmp is used. This method is a convenience method that calls createTempFile(String, String, File) with the third argument being null.

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.

public boolean delete ()

Since: API Level 1

Deletes this file. Directories must be empty before they will be deleted.

Returns
  • true if this file was deleted, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies the request.
See Also

public void deleteOnExit ()

Since: API Level 1

Schedules this file to be automatically deleted once the virtual machine terminates. This will only happen when the virtual machine terminates normally as described by the Java Language Specification section 12.9.

Throws
SecurityException if a SecurityManager is installed and it denies the request.

public boolean equals (Object obj)

Since: API Level 1

Compares obj to this file and returns true if they represent the same object using a path specific comparison.

Parameters
obj the object to compare this file with.
Returns
  • true if obj is the same as this object, false otherwise.

public boolean exists ()

Since: API Level 1

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

Returns
  • true if this file exists, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.
See Also

public File getAbsoluteFile ()

Since: API Level 1

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

Returns
  • a new file from this file's absolute path.
See Also

public String getAbsolutePath ()

Since: API Level 1

Returns the absolute path of this file.

Returns
  • the absolute file path.

public File getCanonicalFile ()

Since: API Level 1

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

Returns
  • the new file constructed from this file's canonical path.
Throws
IOException if an I/O error occurs.
See Also

public String getCanonicalPath ()

Since: API Level 1

Returns the absolute path of this file with all references resolved. An absolute path is one that 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 are removed and replaced with a direct directory reference. If the file does not exist, getCanonicalPath() may not resolve any references and simply returns an absolute path name or throws an IOException.

Returns
  • the canonical path of this file.
Throws
IOException if an I/O error occurs.

public String getName ()

Since: API Level 1

Returns the name of the file or directory represented by this file.

Returns
  • this file's name or an empty string if there is no name part in the file's path.

public String getParent ()

Since: API Level 1

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

Returns
  • this file's parent pathname or null.

public File getParentFile ()

Since: API Level 1

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 this file's parent or null.

public String getPath ()

Since: API Level 1

Returns the path of this file.

Returns
  • this file's path.

public int hashCode ()

Since: API Level 1

Returns an integer hash code for the receiver. Any two objects for which equals returns true must return the same hash code.

Returns
  • this files's hash value.
See Also

public boolean isAbsolute ()

Since: API Level 1

Indicates if this file's pathname is absolute. Whether a pathname is absolute is platform specific. On Android, absolute paths start with the character '/'.

Returns
  • true if this file's pathname is absolute, false otherwise.
See Also

public boolean isDirectory ()

Since: API Level 1

Indicates if this file represents a directory on the underlying file system.

Returns
  • true if this file is a directory, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.

public boolean isFile ()

Since: API Level 1

Indicates if this file represents a file on the underlying file system.

Returns
  • true if this file is a file, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.

public boolean isHidden ()

Since: API Level 1

Returns whether or not this file is a hidden file as defined by the operating system. The notion of "hidden" is system-dependent. For Unix systems a file is considered hidden if its name starts with a ".". For Windows systems there is an explicit flag in the file system for this purpose.

Returns
  • true if the file is hidden, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.

public long lastModified ()

Since: API Level 1

Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight. Returns 0 if the file does not exist.

Returns
  • the time when this file was last modified.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.

public long length ()

Since: API Level 1

Returns the length of this file in bytes. Returns 0 if the file does not exist. The result for a directory is not defined.

Returns
  • the number of bytes in this file.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.

public String[] list ()

Since: API Level 1

Returns an array of strings with the file names in the directory represented by this file. The result is null if this file is not a directory.

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

Returns
  • an array of strings with file names or null.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.
See Also

public String[] list (FilenameFilter filter)

Since: API Level 1

Gets a list of the files in the directory represented by this file. This list is then filtered through a FilenameFilter and the names of files with matching names are returned as an array of strings. Returns null if this file is not a directory. If filter is null then all filenames match.

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

Parameters
filter the filter to match names against, may be null.
Returns
  • an array of files or null.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.
See Also

public File[] listFiles (FileFilter filter)

Since: API Level 1

Gets a list of the files in the directory represented by this file. This list is then filtered through a FileFilter and matching files are returned as an array of files. Returns null if this file is not a directory. If filter is null then all files match.

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

Parameters
filter the filter to match names against, may be null.
Returns
  • an array of files or null.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.
See Also

public File[] listFiles (FilenameFilter filter)

Since: API Level 1

Gets a list of the files in the directory represented by this file. This list is then filtered through a FilenameFilter and files with matching names are returned as an array of files. Returns null if this file is not a directory. If filter is null then all filenames match.

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

Parameters
filter the filter to match names against, may be null.
Returns
  • an array of files or null.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.
See Also

public File[] listFiles ()

Since: API Level 1

Returns an array of files contained in the directory represented by this file. The result is null if this file is not a directory. The paths of the files in the array are absolute if the path of this file is absolute, they are relative otherwise.

Returns
  • an array of files or null.
Throws
SecurityException if a SecurityManager is installed and it denies read access to this file.
See Also

public static File[] listRoots ()

Since: API Level 1

Lists the file system roots. The Java platform may support zero or more file systems, 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 file system roots.

Returns
  • the array of file system roots.

public boolean mkdir ()

Since: API Level 1

Creates the directory named by the trailing filename of this file. Does not create the complete path required to create this directory.

Returns
  • true if the directory has been created, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies write access for this file.
See Also

public boolean mkdirs ()

Since: API Level 1

Creates the directory named by the trailing filename of this file, including the complete directory path required to create this directory.

Returns
  • true if the necessary directories have been created, false if the target directory already exists or one of the directories can not be created.
Throws
SecurityException if a SecurityManager is installed and it denies write access for this file.
See Also

public boolean renameTo (File dest)

Since: API Level 1

Renames this file to the name represented by the dest file. 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.
Throws
SecurityException if a SecurityManager is installed and it denies write access for this file or the dest file.

public boolean setLastModified (long time)

Since: API Level 1

Sets the time this file was last modified, measured in milliseconds since January 1st, 1970, midnight.

Parameters
time the last modification time for this file.
Returns
  • true if the operation is successful, false otherwise.
Throws
IllegalArgumentException if time < 0.
SecurityException if a SecurityManager is installed and it denies write access to this file.

public boolean setReadOnly ()

Since: API Level 1

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

Returns
  • true if the operation is successful, false otherwise.
Throws
SecurityException if a SecurityManager is installed and it denies write access to this file.

public String toString ()

Since: API Level 1

Returns a string containing a concise, human-readable description of this file.

Returns
  • a printable representation of this file.

public URI toURI ()

Since: API Level 1

Returns a Uniform Resource Identifier for this file. The URI is system dependent and may not be transferable between different operating / file systems.

Returns
  • an URI for this file.

public URL toURL ()

Since: API Level 1

Returns a Uniform Resource Locator for this file. The URL is system dependent and may not be transferable between different operating / file systems.

Returns
  • a URL for this file.
Throws
MalformedURLException if the path cannot be transformed into a URL.