    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class java.io.File

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

public class File
extends Object
implements Serializable

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.

##

pathSeparator
  The system-dependent path separator string.
pathSeparatorChar
  The system-dependent path separator character.
separator
  The system-dependent path separator string.
separatorChar
  The system-dependent path separator character.

##

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

##

canRead()
  Tests if the application can read from the specified file.
canWrite()
  Tests if the application can write to this file.
delete()
  Deletes the file specified by this object.
equals(Object)
  Compares this object against the specified object.
exists()
  Tests if this `File` exists.
getAbsolutePath()
  Returns the absolute pathname of the file represented by this object.
getCanonicalPath()
  Returns the canonical form of this `File` object's pathname.
getName()
  Returns the name of the file represented by this object.
getParent()
  Returns the parent part of the pathname of this `File` object, or `null` if the name has no parent part.
getPath()
  Returns the pathname of the file represented by this object.
hashCode()
  Computes a hashcode for the file.
isAbsolute()
  Tests if the file represented by this `File` object is an absolute pathname.
isDirectory()
  Tests if the file represented by this `File` object is a directory.
isFile()
  Tests if the file represented by this `File` object is a "normal" file.
lastModified()
  Returns the time that the file represented by this `File` object was last modified.
length()
  Returns the length of the file represented by this `File` object.
list()
  Returns a list of the files in the directory specified by this `File` object.
list(FilenameFilter)
  Returns a list of the files in the directory specified by this `File` that satisfy the specified filter.
mkdir()
  Creates a directory whose pathname is specified by this `File` object.
mkdirs()
  Creates a directory whose pathname is specified by this `File` object, including any necessary parent directories.
renameTo(File)
  Renames the file specified by this `File` object to have the pathname given by the `File` argument.
toString()
  Returns a string representation of this object.

##

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

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

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

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

##

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

##

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

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

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

canWrite

     public boolean canWrite()

  Tests if the application can write to this file.

  Returns:
    `true` if the application is allowed to write to a file whose name is specified by this object; `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

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

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

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

isAbsolute

     public native 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

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

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

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

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

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

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

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

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

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

    All Packages  Class Hierarchy  This Package  Previous  Next  Index

Submit a bug or feature - Version 1.1.8 of Java Platform API Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1995-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.