22.24 The Class java.io.File

A File object contains a path, which is a character string that can be used to identify a file within a file system. A path is assumed to consist of two parts, the directory and the file name, separated by the last occurrence within the path of a particular character known as the separator character. Some methods provide access to parts of the path string; other methods operate on the file that is identified by the path string. The details of such operations on files are to some extent dependent on the implementation of the host file system. The File class is designed to provide a set of abstract operations that are reasonably portable across otherwise incompatible file systems.

public class File {
	public static final String separator =
		System.getProperty("file.separator");
	public static final char separatorChar =
		separator.charAt(0);
	public static final String pathSeparator =
		System.getProperty("path.separator");
	public static final char pathSeparatorChar =
		pathSeparator.charAt(0);
	public File(String path) throws NullPointerException;
	public File(String dirname, String name)
		throws NullPointerException
	public File(File dir, String name)
		throws NullPointerException
	public String toString();
	public boolean equals(Object obj);
	public int hashCode();
	public String getName();
	public String getPath();
	public String getAbsolutePath();
	public String getParent();
	public native boolean isAbsolute();
	public boolean exists() throws SecurityException;
	public boolean canRead() throws SecurityException;
	public boolean canWrite() throws SecurityException;
	public boolean isFile() throws SecurityException;
	public boolean isDirectory() throws SecurityException;
	public long lastModified() throws SecurityException;
	public long length() throws SecurityException;
	public boolean mkdir() throws SecurityException;
	public boolean mkdirs() throws SecurityException;
	public String[] list() throws SecurityException;
	public String[] list(FilenameFilter filter)
		throws SecurityException;
	public boolean delete() throws SecurityException;
	public boolean renameTo(File dest) throws SecurityException;
}

22.24.1 public static final String separator = System.getProperty("file.separator");

This string should consist of a single character, whose value is also available in the field separatorChar; the string is provided merely for convenience.

22.24.2 public static final char separatorChar = separator.charAt(0);

The last occurrence of this character in a path string is assumed to separate the directory part of the path from the file name part of the path. On UNIX systems this character is typically '/'.

22.24.3 public static final String pathSeparator = System.getProperty("path.separator");

This string should consist of a single character, whose value is also available in the field pathSeparatorChar; the string is provided merely for convenience.

22.24.4 public static final char pathSeparatorChar = pathSeparator.charAt(0);

The first occurrence of this character in a string is sometimes assumed to separate a host name from a path name. On UNIX systems this character is typically ':'.

22.24.5 public File(String path) throws NullPointerException

This constructor initializes a newly created File so that it represents the path indicated by the argument path.

If the path is null, a NullPointerException is thrown.

22.24.6 public File(String dirname, String name)
throws NullPointerException

This constructor initializes a newly created File so that it represents the path whose directory part is specified by the argument dirname and whose file name part is specified by the argument name. If the dirname argument is null, the name is used as the path; otherwise the concatenation of dirname, the separatorChar (§22.24.2), and the name is used as the path.

If the name is null, a NullPointerException is thrown.

22.24.7 public File(File dir, String name)
throws NullPointerException

This constructor initializes a newly created File so that it represents the path whose directory part is specified by the File object dir and whose file name part is specified by the argument name.

If the name is null, a NullPointerException is thrown.

22.24.8 public String toString()

The result is a String equal to the path represented by this File object.

Overrides the toString method of Object (§20.1.2).

22.24.9 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a File object that represents the same path as this File object. In other words, two File objects are equal if and only if the strings returned by the getPath method (§22.24.12) are equal.

Overrides the equals method of Object (§20.1.3).

22.24.10 public int hashCode()

The hash code of this File object is equal to the exclusive OR of the hash code of its path string and the decimal value 1234321:

this.getPath().hashcode() ^ 1234321

Overrides the hashCode method of Object (§20.1.4).

22.24.11 public String getName()

If the path string contains the separatorChar character (§22.24.2), this method returns the substring of the path that follows the last occurrence of the separator character; otherwise, the entire path string is returned.

22.24.12 public String getPath()

The result is a String equal to the path represented by this File object.

22.24.13 public String getAbsolutePath()

The result is a String equal to the result of converting to "absolute form" the path represented by this File object.

22.24.14 public String getParent()

If the path has a parent directory, a String representing the path of that parent directory is returned; otherwise, null is returned.

22.24.15 public boolean isAbsolute()

The result is true if and only if the path represented by the File object is in absolute form, indicating a complete name that starts from the root of the directory hierarchy, rather than a name relative to some implied directory.

22.24.16 public boolean exists() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if the file system actually contains a file that is specified by the path of the File object.

22.24.17 public boolean canRead() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

• The file system actually contains a file specified by the path of the File object.
• The file so specified can be read.

22.24.18 public boolean canWrite() throws SecurityException

First, if there is a security manager, its checkWrite method (§20.17.21) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

• The file system actually contains a file specified by the path of the File object.
• The file so specified can be written.

22.24.19 public boolean isFile() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

• The file system actually contains a file specified by the path of the File object.
• The file so specified is a data file rather than a directory.

22.24.20 public boolean isDirectory() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

• The file system actually contains a file specified by the path of the File object.
• The file so specified is a directory rather than a data file.

22.24.21 public long lastModified() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

An abstract modification time is returned. If two values returned by this method are compared, whether for the same file or for two different files, the smaller value represents an earlier modification time. Abstract modification times do not necessarily bear any relationship, even monotonicity, to times returned by the method System.currentTimeMillis (§20.18.6).

22.24.22 public long length() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The length of the file, measured in bytes, is returned.

22.24.23 public boolean mkdir() throws SecurityException

First, if there is a security manager, its checkWrite method (§20.17.21) is called with the path represented by this File object as its argument.

An attempt is made to create the directory specified by the path represented by this File object; the result is true if and only if the creation operation succeeds.

22.24.24 public boolean mkdirs() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

If the directory name represented by this File object has a parent directory name (§22.24.14), an attempt is first made to create the parent directory; if this attempt fails, the result is false. Otherwise, once the parent directory has been determined to exist, or if the path has no parent, an attempt is made to create the directory specified by this File object. The result is true if and only if the creation operation succeeds.

22.24.25 public String[] list() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

If the path represented by this File object does not correspond to a directory in the file system, then null is returned. Otherwise, an array of strings is returned, one for each file in the directory (on UNIX systems, the names "." and ".." are not included). Each string is a file name, not a complete path. There is no guarantee that the strings will appear in any particular order within the array; for example, they are not guaranteed to appear in alphabetical order.

22.24.26 public String[] list(FilenameFilter filter)
throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

If the path represented by this File object does not correspond to a directory in the file system, then null is returned. Otherwise, an array of strings is returned, one for each file in the directory (on UNIX systems, the names "." and ".." are not included) whose name satisfies the given filter. Each string is a file name, not a complete path. There is no guarantee that the strings will appear in any particular order within the array; for example, they are not guaranteed to appear in alphabetical order. A file name satisfies the filter if and only if the value true results when the accept method (§22.25.1) of the filter is called with this File object and the name as arguments.

22.24.27 public boolean renameTo(File dest)
throws SecurityException

First, if there is a security manager, its checkWrite method (§20.17.21) is called twice, first with the path represented by this File object as its argument and again with the path of dest as its argument.

An attempt is made to rename the file specified by the path represented by this File object to the name specified by dest; the result is true if and only if the renaming operation succeeds.

22.24.28 public boolean delete() throws SecurityException

First, if there is a security manager, its checkDelete method (§20.17.22) is called with the path represented by this File object as its argument.

An attempt is made to delete the file specified by the path represented by this File object; the result is true if and only if the deletion operation succeeds.