User interfaces and operating systems use system-dependent pathname strings to name files and directories. This class presents an abstract, system-independent view of hierarchical pathnames. An abstract pathname has two components:
"/" for the UNIX root
directory, or "\\\\" for a Microsoft Windows UNC pathname, and
The conversion of a pathname string to or from an abstract pathname is
inherently system-dependent. When an abstract pathname is converted into a
pathname string, each name is separated from the next by a single copy of
the default separator character. The default name-separator
character is defined by the system property file.separator, and
is made available in the public static fields #separator
and #separatorChar
of this class.
When a pathname string is converted into an abstract pathname, the names
within it may be separated by the default name-separator character or by any
other name-separator character that is supported by the underlying system.
A pathname, whether abstract or in string form, may be either
absolute or relative. An absolute pathname is complete in
that no other information is required in order to locate the file that it
denotes. A relative pathname, in contrast, must be interpreted in terms of
information taken from some other pathname. By default the classes in the
java.io package always resolve relative pathnames against the
current user directory. This directory is named by the system property
user.dir, and is typically the directory in which the Java
virtual machine was invoked.
The prefix concept is used to handle root directories on UNIX platforms, and drive specifiers, root directories and UNC pathnames on Microsoft Windows platforms, as follows:
"/". Relative pathnames have no prefix. The abstract pathname
denoting the root directory has the prefix "/" and an empty
name sequence.
":" and
possibly followed by "\\" if the pathname is absolute. The
prefix of a UNC pathname is "\\\\"; the hostname and the share
name are the first two names in the name sequence. A relative pathname that
does not specify a drive has no prefix.
Instances of the File class are immutable; that is, once
created, the abstract pathname represented by a File object
will never change.
File instance by converting the given
pathname string into an abstract pathname. If the given string is
the empty string, then the result is the empty abstract pathname.File instance from a parent pathname string
and a child pathname string.
If parent is null then the new
File instance is created as if by invoking the
single-argument File constructor on the given
child pathname string.
Otherwise the parent pathname string is taken to denote
a directory, and the child pathname string is taken to
denote either a directory or a file. If the child pathname
string is absolute then it is converted into a relative pathname in a
system-dependent way. If parent is the empty string then
the new File instance is created by converting
child into an abstract pathname and resolving the result
against a system-dependent default directory. Otherwise each pathname
string is converted into an abstract pathname and the child abstract
pathname is resolved against the parent.
File instance from a parent abstract
pathname and a child pathname string.
If parent is null then the new
File instance is created as if by invoking the
single-argument File constructor on the given
child pathname string.
Otherwise the parent abstract pathname is taken to
denote a directory, and the child pathname string is taken
to denote either a directory or a file. If the child
pathname string is absolute then it is converted into a relative
pathname in a system-dependent way. If parent is the empty
abstract pathname then the new File instance is created by
converting child into an abstract pathname and resolving
the result against a system-dependent default directory. Otherwise each
pathname string is converted into an abstract pathname and the child
abstract pathname is resolved against the parent.
The exact form of a file: URI is system-dependent, hence the transformation performed by this constructor is also system-dependent.
For a given abstract pathname f it is guaranteed that
new File( f.toURI ()).equals( f.getAbsoluteFile ())so long as the original abstract pathname, the URI, and the new abstract pathname are all created in (possibly different invocations of) the same Java virtual machine. This relationship typically does not hold, however, when a file: URI that is created in a virtual machine on one operating system is converted into an abstract pathname in a virtual machine on a different operating system.
#pathSeparatorChar
.path.separator. This character is used to
separate filenames in a sequence of files given as a path list.
On UNIX systems, this character is ':'; on Microsoft Windows systems it
is ';'.#separatorChar
.file.separator. On UNIX systems the value of this
field is '/'; on Microsoft Windows systems it is '\\'.In the foregoing description, the notation sgn(expression) designates the mathematical signum function, which is defined to return one of -1, 0, or 1 according to whether the value of expression is negative, zero or positive. The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception iff y.compareTo(x) throws an exception.)
The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies x.compareTo(z)>0.
Finally, the implementer must ensure that x.compareTo(y)==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.
It is strongly recommended, but not strictly required that (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."
Note: this method should not be used for file-locking, as the resulting protocol cannot be made to work reliably. The FileLock facility should be used instead.
createTempFile(prefix, suffix, null)
.Creates a new empty file in the specified directory, using the given prefix and suffix strings to generate its name. If this method returns successfully then it is guaranteed that:
#deleteOnExit
method.
The prefix argument must be at least three characters
long. It is recommended that the prefix be a short, meaningful string
such as "hjb" or "mail". The
suffix argument may be null, in which case the
suffix ".tmp" will be used.
To create the new file, the prefix and the suffix may first be
adjusted to fit the limitations of the underlying platform. If the
prefix is too long then it will be truncated, but its first three
characters will always be preserved. If the suffix is too long then it
too will be truncated, but if it begins with a period character
('.') then the period and the first three characters
following it will always be preserved. Once these adjustments have been
made the name of the new file will be generated by concatenating the
prefix, five or more internally-generated characters, and the suffix.
If the directory argument is null then the
system-dependent default temporary-file directory will be used. The
default temporary-file directory is specified by the system property
java.io.tmpdir. On UNIX systems the default value of this
property is typically "/tmp" or "/var/tmp"; on
Microsoft Windows systems it is typically "C:\\WINNT\\TEMP". A different
value may be given to this system property when the Java virtual machine
is invoked, but programmatic changes to this property are not guaranteed
to have any effect upon the temporary directory used by this method.
Once deletion has been requested, it is not possible to cancel the request. This method should therefore be used with care.
Note: this method should not be used for file-locking, as the resulting protocol cannot be made to work reliably. The FileLock facility should be used instead.
true if and only if the argument is not
null and is an abstract pathname that denotes the same file
or directory as this abstract pathname. Whether or not two abstract
pathnames are equal depends upon the underlying system. On UNIX
systems, alphabetic case is significant in comparing pathnames; on Microsoft Windows
systems it is not.new File(this.#getAbsolutePath
()). If this abstract pathname is already absolute, then the pathname
string is simply returned as if by the #getPath
method. If this abstract pathname is the empty abstract pathname then
the pathname string of the current user directory, which is named by the
system property user.dir, is returned. Otherwise this
pathname is resolved in a system-dependent way. On UNIX systems, a
relative pathname is made absolute by resolving it against the current
user directory. On Microsoft Windows systems, a relative pathname is made absolute
by resolving it against the current directory of the drive named by the
pathname, if any; if not, it is resolved against the current user
directory.
new File(this.#getCanonicalPath
()).A canonical pathname is both absolute and unique. The precise definition of canonical form is system-dependent. This method first converts this pathname to absolute form if necessary, as if by invoking the #getAbsolutePath method, and then maps it to its unique form in a system-dependent way. This typically involves removing redundant names such as "." and ".." from the pathname, resolving symbolic links (on UNIX platforms), and converting drive letters to a standard case (on Microsoft Windows platforms).
Every pathname that denotes an existing file or directory has a unique canonical form. Every pathname that denotes a nonexistent file or directory also has a unique canonical form. The canonical form of the pathname of a nonexistent file or directory may be different from the canonical form of the same pathname after the file or directory is created. Similarly, the canonical form of the pathname of an existing file or directory may be different from the canonical form of the same pathname after the file or directory is deleted.
null if this pathname does not name a parent directory.
The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.
null if this pathname does not name a parent
directory.
The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.
1234321. On Microsoft Windows systems, the hash
code is equal to the exclusive or of the hash code of
its pathname string converted to lower case and the decimal
value 1234321."/". On Microsoft Windows systems, a
pathname is absolute if its prefix is a drive specifier followed by
"\\", or if its prefix is "\\\\".'.'). On Microsoft Windows systems, a file is
considered to be hidden if it has been marked as such in the filesystem. If this abstract pathname does not denote a directory, then this
method returns null. Otherwise an array of strings is
returned, one for each file or directory in the directory. Names
denoting the directory itself and the directory's parent directory are
not included in the result. Each string is a file name rather than a
complete path.
There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.
method, except that the strings in the
returned array must satisfy the filter. If the given
filter is null then all names are accepted.
Otherwise, a name satisfies the filter if and only if the value
true results when the FilenameFilter#accept
method of the filter is invoked on this
abstract pathname and the name of a file or directory in the directory
that it denotes. If this abstract pathname does not denote a directory, then this
method returns null. Otherwise an array of
File objects is returned, one for each file or directory in
the directory. Pathnames denoting the directory itself and the
directory's parent directory are not included in the result. Each
resulting abstract pathname is constructed from this abstract pathname
using the File(File, String)
constructor. Therefore if this pathname
is absolute then each resulting pathname is absolute; if this pathname
is relative then each resulting pathname will be relative to the same
directory.
There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.
method, except
that the pathnames in the returned array must satisfy the filter.
If the given filter is null then all
pathnames are accepted. Otherwise, a pathname satisfies the filter
if and only if the value true results when the
method of
the filter is invoked on the pathname.
method, except
that the pathnames in the returned array must satisfy the filter.
If the given filter is null then all
pathnames are accepted. Otherwise, a pathname satisfies the filter
if and only if the value true results when the
FilenameFilter#accept
method of the filter is
invoked on this abstract pathname and the name of a file or
directory in the directory that it denotes. A particular Java platform may support zero or more
hierarchically-organized file systems. Each file system has a
root directory from which all other files in that file
system can be reached. Windows platforms, for example, have a root
directory for each active drive; UNIX platforms have a single root
directory, namely "/". The set of available filesystem
roots is affected by various system-level operations such as the insertion
or ejection of removable media and the disconnecting or unmounting of
physical or virtual disk drives.
This method returns an array of File objects that
denote the root directories of the available filesystem roots. It is
guaranteed that the canonical pathname of any file physically present on
the local machine will begin with one of the roots returned by this
method.
The canonical pathname of a file that resides on some other machine
and is accessed via a remote-filesystem protocol such as SMB or NFS may
or may not begin with one of the roots returned by this method. If the
pathname of a remote file is syntactically indistinguishable from the
pathname of a local file then it will begin with one of the roots
returned by this method. Thus, for example, File objects
denoting the root directories of the mapped network drives of a Windows
platform will be returned by this method, while File
objects containing UNC pathnames will not be returned by this method.
Unlike most methods in this class, this method does not throw
security exceptions. If a security manager exists and its
method
denies read access to a particular root directory, then that directory
will not appear in the result.
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
Many aspects of the behavior of this method are inherently platform-dependent: The rename operation might not be able to move a file from one filesystem to another, it might not be atomic, and it might not succeed if a file with the destination abstract pathname already exists. The return value should always be checked to make sure that the rename operation was successful.
All platforms support file-modification times to the nearest second,
but some provide more precision. The argument will be truncated to fit
the supported precision. If the operation succeeds and no intervening
operations on the file take place, then the next invocation of the
#lastModified
method will return the (possibly
truncated) time argument that was passed to this method.
#getPath
method.The exact form of the URI is system-dependent. If it can be determined that the file denoted by this abstract pathname is a directory, then the resulting URI will end with a slash.
For a given abstract pathname f, it is guaranteed that
new File ( f.toURI()).equals( f.getAbsoluteFile ())so long as the original abstract pathname, the URI, and the new abstract pathname are all created in (possibly different invocations of) the same Java virtual machine. Due to the system-dependent nature of abstract pathnames, however, this relationship typically does not hold when a file: URI that is created in a virtual machine on one operating system is converted into an abstract pathname in a virtual machine on a different operating system.
file: URL. The
exact form of the URL is system-dependent. If it can be determined that
the file denoted by this abstract pathname is a directory, then the
resulting URL will end with a slash.
Usage note: This method does not automatically escape characters that are illegal in URLs. It is recommended that new code convert an abstract pathname into a URL by first converting it into a URI, via the toURI method, and then converting the URI into a URL via the URI.toURL method.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.