User interfaces and operating systems use system-dependent pathname jaroslav@1258: * strings to name files and directories. This class presents an jaroslav@1258: * abstract, system-independent view of hierarchical pathnames. An jaroslav@1258: * abstract pathname has two components: jaroslav@1258: * jaroslav@1258: *
"/" for the UNIX root
jaroslav@1258: * directory, or "\\\\" for a Microsoft Windows UNC pathname, and
jaroslav@1258: * The conversion of a pathname string to or from an abstract pathname is
jaroslav@1258: * inherently system-dependent. When an abstract pathname is converted into a
jaroslav@1258: * pathname string, each name is separated from the next by a single copy of
jaroslav@1258: * the default separator character. The default name-separator
jaroslav@1258: * character is defined by the system property file.separator, and
jaroslav@1258: * is made available in the public static fields {@link
jaroslav@1258: * #separator} and {@link #separatorChar} of this class.
jaroslav@1258: * When a pathname string is converted into an abstract pathname, the names
jaroslav@1258: * within it may be separated by the default name-separator character or by any
jaroslav@1258: * other name-separator character that is supported by the underlying system.
jaroslav@1258: *
jaroslav@1258: *
A pathname, whether abstract or in string form, may be either
jaroslav@1258: * absolute or relative. An absolute pathname is complete in
jaroslav@1258: * that no other information is required in order to locate the file that it
jaroslav@1258: * denotes. A relative pathname, in contrast, must be interpreted in terms of
jaroslav@1258: * information taken from some other pathname. By default the classes in the
jaroslav@1258: * java.io package always resolve relative pathnames against the
jaroslav@1258: * current user directory. This directory is named by the system property
jaroslav@1258: * user.dir, and is typically the directory in which the Java
jaroslav@1258: * virtual machine was invoked.
jaroslav@1258: *
jaroslav@1258: *
The parent of an abstract pathname may be obtained by invoking jaroslav@1258: * the {@link #getParent} method of this class and consists of the pathname's jaroslav@1258: * prefix and each name in the pathname's name sequence except for the last. jaroslav@1258: * Each directory's absolute pathname is an ancestor of any File jaroslav@1258: * object with an absolute abstract pathname which begins with the directory's jaroslav@1258: * absolute pathname. For example, the directory denoted by the abstract jaroslav@1258: * pathname "/usr" is an ancestor of the directory denoted by the jaroslav@1258: * pathname "/usr/local/bin". jaroslav@1258: * jaroslav@1258: *
The prefix concept is used to handle root directories on UNIX platforms, jaroslav@1258: * and drive specifiers, root directories and UNC pathnames on Microsoft Windows platforms, jaroslav@1258: * as follows: jaroslav@1258: * jaroslav@1258: *
"/". Relative pathnames have no prefix. The abstract pathname
jaroslav@1258: * denoting the root directory has the prefix "/" and an empty
jaroslav@1258: * name sequence.
jaroslav@1258: *
jaroslav@1258: * ":" and
jaroslav@1258: * possibly followed by "\\" if the pathname is absolute. The
jaroslav@1258: * prefix of a UNC pathname is "\\\\"; the hostname and the share
jaroslav@1258: * name are the first two names in the name sequence. A relative pathname that
jaroslav@1258: * does not specify a drive has no prefix.
jaroslav@1258: *
jaroslav@1258: * Instances of this class may or may not denote an actual file-system jaroslav@1258: * object such as a file or a directory. If it does denote such an object jaroslav@1258: * then that object resides in a partition. A partition is an jaroslav@1258: * operating system-specific portion of storage for a file system. A single jaroslav@1258: * storage device (e.g. a physical disk-drive, flash memory, CD-ROM) may jaroslav@1258: * contain multiple partitions. The object, if any, will reside on the jaroslav@1258: * partition named by some ancestor of the absolute jaroslav@1258: * form of this pathname. jaroslav@1258: * jaroslav@1258: *
A file system may implement restrictions to certain operations on the jaroslav@1258: * actual file-system object, such as reading, writing, and executing. These jaroslav@1258: * restrictions are collectively known as access permissions. The file jaroslav@1258: * system may have multiple sets of access permissions on a single object. jaroslav@1258: * For example, one set may apply to the object's owner, and another jaroslav@1258: * may apply to all other users. The access permissions on an object may jaroslav@1258: * cause some methods in this class to fail. jaroslav@1258: * jaroslav@1258: *
Instances of the File class are immutable; that is, once
jaroslav@1258: * created, the abstract pathname represented by a File object
jaroslav@1258: * will never change.
jaroslav@1258: *
jaroslav@1258: *
The {@code java.nio.file}
jaroslav@1258: * package defines interfaces and classes for the Java virtual machine to access
jaroslav@1258: * files, file attributes, and file systems. This API may be used to overcome
jaroslav@1258: * many of the limitations of the {@code java.io.File} class.
jaroslav@1258: * The {@link #toPath toPath} method may be used to obtain a {@link
jaroslav@1258: * Path} that uses the abstract path represented by a {@code File} object to
jaroslav@1258: * locate a file. The resulting {@code Path} may be used with the {@link
jaroslav@1258: * java.nio.file.Files} class to provide more efficient and extensive access to
jaroslav@1258: * additional file operations, file attributes, and I/O exceptions to help
jaroslav@1258: * diagnose errors when an operation on a file fails.
jaroslav@1258: *
jaroslav@1258: * @author unascribed
jaroslav@1258: * @since JDK1.0
jaroslav@1258: */
jaroslav@1258:
jaroslav@1258: public class File
jaroslav@1258: implements Serializable, Comparable If Otherwise the If Otherwise the The exact form of a file: URI is system-dependent, hence
jaroslav@1258: * the transformation performed by this constructor is also
jaroslav@1258: * system-dependent.
jaroslav@1258: *
jaroslav@1258: * For a given abstract pathname f it is guaranteed that
jaroslav@1258: *
jaroslav@1258: * The parent of an abstract pathname consists of the
jaroslav@1258: * pathname's prefix, if any, and each name in the pathname's name
jaroslav@1258: * sequence except for the last. If the name sequence is empty then
jaroslav@1258: * the pathname does not name a parent directory.
jaroslav@1258: *
jaroslav@1258: * @return The pathname string of the parent directory named by this
jaroslav@1258: * abstract pathname, or The parent of an abstract pathname consists of the
jaroslav@1258: * pathname's prefix, if any, and each name in the pathname's name
jaroslav@1258: * sequence except for the last. If the name sequence is empty then
jaroslav@1258: * the pathname does not name a parent directory.
jaroslav@1258: *
jaroslav@1258: * @return The abstract pathname of the parent directory named by this
jaroslav@1258: * abstract pathname, or If this abstract pathname is already absolute, then the pathname
jaroslav@1258: * string is simply returned as if by the A canonical pathname is both absolute and unique. The precise
jaroslav@1258: * definition of canonical form is system-dependent. This method first
jaroslav@1258: * converts this pathname to absolute form if necessary, as if by invoking the
jaroslav@1258: * {@link #getAbsolutePath} method, and then maps it to its unique form in a
jaroslav@1258: * system-dependent way. This typically involves removing redundant names
jaroslav@1258: * such as "." and ".." from the pathname, resolving
jaroslav@1258: * symbolic links (on UNIX platforms), and converting drive letters to a
jaroslav@1258: * standard case (on Microsoft Windows platforms).
jaroslav@1258: *
jaroslav@1258: * Every pathname that denotes an existing file or directory has a
jaroslav@1258: * unique canonical form. Every pathname that denotes a nonexistent file
jaroslav@1258: * or directory also has a unique canonical form. The canonical form of
jaroslav@1258: * the pathname of a nonexistent file or directory may be different from
jaroslav@1258: * the canonical form of the same pathname after the file or directory is
jaroslav@1258: * created. Similarly, the canonical form of the pathname of an existing
jaroslav@1258: * file or directory may be different from the canonical form of the same
jaroslav@1258: * pathname after the file or directory is deleted.
jaroslav@1258: *
jaroslav@1258: * @return The canonical pathname string denoting the same file or
jaroslav@1258: * directory as this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @throws IOException
jaroslav@1258: * If an I/O error occurs, which is possible because the
jaroslav@1258: * construction of the canonical pathname may require
jaroslav@1258: * filesystem queries
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a required system property value cannot be accessed, or
jaroslav@1258: * if a security manager exists and its The exact form of the URI is system-dependent. If it can be
jaroslav@1258: * determined that the file denoted by this abstract pathname is a
jaroslav@1258: * directory, then the resulting URI will end with a slash.
jaroslav@1258: *
jaroslav@1258: * For a given abstract pathname f, it is guaranteed that
jaroslav@1258: *
jaroslav@1258: * Note that when this abstract pathname represents a UNC pathname then
jaroslav@1258: * all components of the UNC (including the server name component) are encoded
jaroslav@1258: * in the {@code URI} path. The authority component is undefined, meaning
jaroslav@1258: * that it is represented as {@code null}. The {@link Path} class defines the
jaroslav@1258: * {@link Path#toUri toUri} method to encode the server name in the authority
jaroslav@1258: * component of the resulting {@code URI}. The {@link #toPath toPath} method
jaroslav@1258: * may be used to obtain a {@code Path} representing this abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @return An absolute, hierarchical URI with a scheme equal to
jaroslav@1258: * "file", a path representing this abstract pathname,
jaroslav@1258: * and undefined authority, query, and fragment components
jaroslav@1258: * @throws SecurityException If a required system property value cannot
jaroslav@1258: * be accessed.
jaroslav@1258: *
jaroslav@1258: * @see #File(java.net.URI)
jaroslav@1258: * @see java.net.URI
jaroslav@1258: * @see java.net.URI#toURL()
jaroslav@1258: * @since 1.4
jaroslav@1258: */
jaroslav@1258: public URI toURI() {
jaroslav@1258: try {
jaroslav@1258: File f = getAbsoluteFile();
jaroslav@1258: String sp = slashify(f.getPath(), f.isDirectory());
jaroslav@1258: if (sp.startsWith("//"))
jaroslav@1258: sp = "//" + sp;
jaroslav@1258: return new URI("file", null, sp, null);
jaroslav@1258: } catch (URISyntaxException x) {
jaroslav@1258: throw new Error(x); // Can't happen
jaroslav@1258: }
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258:
jaroslav@1258: /* -- Attribute accessors -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether the application can read the file denoted by this
jaroslav@1258: * abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @return Where it is required to distinguish an I/O exception from the case
jaroslav@1258: * that the file is not a directory, or where several attributes of the
jaroslav@1258: * same file are required at the same time, then the {@link
jaroslav@1258: * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
jaroslav@1258: * Files.readAttributes} method may be used.
jaroslav@1258: *
jaroslav@1258: * @return Where it is required to distinguish an I/O exception from the case
jaroslav@1258: * that the file is not a normal file, or where several attributes of the
jaroslav@1258: * same file are required at the same time, then the {@link
jaroslav@1258: * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
jaroslav@1258: * Files.readAttributes} method may be used.
jaroslav@1258: *
jaroslav@1258: * @return Where it is required to distinguish an I/O exception from the case
jaroslav@1258: * where {@code 0L} is returned, or where several attributes of the
jaroslav@1258: * same file are required at the same time, or where the time of last
jaroslav@1258: * access or the creation time are required, then the {@link
jaroslav@1258: * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
jaroslav@1258: * Files.readAttributes} method may be used.
jaroslav@1258: *
jaroslav@1258: * @return A Where it is required to distinguish an I/O exception from the case
jaroslav@1258: * that {@code 0L} is returned, or where several attributes of the same file
jaroslav@1258: * are required at the same time, then the {@link
jaroslav@1258: * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
jaroslav@1258: * Files.readAttributes} method may be used.
jaroslav@1258: *
jaroslav@1258: * @return The length, in bytes, of the file denoted by this abstract
jaroslav@1258: * pathname, or
jaroslav@1258: * Note: this method should not be used for file-locking, as
jaroslav@1258: * the resulting protocol cannot be made to work reliably. The
jaroslav@1258: * {@link java.nio.channels.FileLock FileLock}
jaroslav@1258: * facility should be used instead.
jaroslav@1258: *
jaroslav@1258: * @return Note that the {@link java.nio.file.Files} class defines the {@link
jaroslav@1258: * java.nio.file.Files#delete(Path) delete} method to throw an {@link IOException}
jaroslav@1258: * when a file cannot be deleted. This is useful for error reporting and to
jaroslav@1258: * diagnose why a file cannot be deleted.
jaroslav@1258: *
jaroslav@1258: * @return Once deletion has been requested, it is not possible to cancel the
jaroslav@1258: * request. This method should therefore be used with care.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * Note: this method should not be used for file-locking, as
jaroslav@1258: * the resulting protocol cannot be made to work reliably. The
jaroslav@1258: * {@link java.nio.channels.FileLock FileLock}
jaroslav@1258: * facility should be used instead.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its If this abstract pathname does not denote a directory, then this
jaroslav@1258: * method returns {@code null}. Otherwise an array of strings is
jaroslav@1258: * returned, one for each file or directory in the directory. Names
jaroslav@1258: * denoting the directory itself and the directory's parent directory are
jaroslav@1258: * not included in the result. Each string is a file name rather than a
jaroslav@1258: * complete path.
jaroslav@1258: *
jaroslav@1258: * There is no guarantee that the name strings in the resulting array
jaroslav@1258: * will appear in any specific order; they are not, in particular,
jaroslav@1258: * guaranteed to appear in alphabetical order.
jaroslav@1258: *
jaroslav@1258: * Note that the {@link java.nio.file.Files} class defines the {@link
jaroslav@1258: * java.nio.file.Files#newDirectoryStream(Path) newDirectoryStream} method to
jaroslav@1258: * open a directory and iterate over the names of the files in the directory.
jaroslav@1258: * This may use less resources when working with very large directories, and
jaroslav@1258: * may be more responsive when working with remote directories.
jaroslav@1258: *
jaroslav@1258: * @return An array of strings naming the files and directories in the
jaroslav@1258: * directory denoted by this abstract pathname. The array will be
jaroslav@1258: * empty if the directory is empty. Returns {@code null} if
jaroslav@1258: * this abstract pathname does not denote a directory, or if an
jaroslav@1258: * I/O error occurs.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * SecurityManager#checkRead(String)} method denies read access to
jaroslav@1258: * the directory
jaroslav@1258: */
jaroslav@1258: public String[] list() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return fs.list(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns an array of strings naming the files and directories in the
jaroslav@1258: * directory denoted by this abstract pathname that satisfy the specified
jaroslav@1258: * filter. The behavior of this method is the same as that of the
jaroslav@1258: * {@link #list()} method, except that the strings in the returned array
jaroslav@1258: * must satisfy the filter. If the given {@code filter} is {@code null}
jaroslav@1258: * then all names are accepted. Otherwise, a name satisfies the filter if
jaroslav@1258: * and only if the value {@code true} results when the {@link
jaroslav@1258: * FilenameFilter#accept FilenameFilter.accept(File, String)} method
jaroslav@1258: * of the filter is invoked on this abstract pathname and the name of a
jaroslav@1258: * file or directory in the directory that it denotes.
jaroslav@1258: *
jaroslav@1258: * @param filter
jaroslav@1258: * A filename filter
jaroslav@1258: *
jaroslav@1258: * @return An array of strings naming the files and directories in the
jaroslav@1258: * directory denoted by this abstract pathname that were accepted
jaroslav@1258: * by the given {@code filter}. The array will be empty if the
jaroslav@1258: * directory is empty or if no names were accepted by the filter.
jaroslav@1258: * Returns {@code null} if this abstract pathname does not denote
jaroslav@1258: * a directory, or if an I/O error occurs.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * SecurityManager#checkRead(String)} method denies read access to
jaroslav@1258: * the directory
jaroslav@1258: *
jaroslav@1258: * @see java.nio.file.Files#newDirectoryStream(Path,String)
jaroslav@1258: */
jaroslav@1258: public String[] list(FilenameFilter filter) {
jaroslav@1258: String names[] = list();
jaroslav@1258: if ((names == null) || (filter == null)) {
jaroslav@1258: return names;
jaroslav@1258: }
jaroslav@1258: List If this abstract pathname does not denote a directory, then this
jaroslav@1258: * method returns {@code null}. Otherwise an array of {@code File} objects
jaroslav@1258: * is returned, one for each file or directory in the directory. Pathnames
jaroslav@1258: * denoting the directory itself and the directory's parent directory are
jaroslav@1258: * not included in the result. Each resulting abstract pathname is
jaroslav@1258: * constructed from this abstract pathname using the {@link #File(File,
jaroslav@1258: * String) File(File, String)} constructor. Therefore if this
jaroslav@1258: * pathname is absolute then each resulting pathname is absolute; if this
jaroslav@1258: * pathname is relative then each resulting pathname will be relative to
jaroslav@1258: * the same directory.
jaroslav@1258: *
jaroslav@1258: * There is no guarantee that the name strings in the resulting array
jaroslav@1258: * will appear in any specific order; they are not, in particular,
jaroslav@1258: * guaranteed to appear in alphabetical order.
jaroslav@1258: *
jaroslav@1258: * Note that the {@link java.nio.file.Files} class defines the {@link
jaroslav@1258: * java.nio.file.Files#newDirectoryStream(Path) newDirectoryStream} method
jaroslav@1258: * to open a directory and iterate over the names of the files in the
jaroslav@1258: * directory. This may use less resources when working with very large
jaroslav@1258: * directories.
jaroslav@1258: *
jaroslav@1258: * @return An array of abstract pathnames denoting the files and
jaroslav@1258: * directories in the directory denoted by this abstract pathname.
jaroslav@1258: * The array will be empty if the directory is empty. Returns
jaroslav@1258: * {@code null} if this abstract pathname does not denote a
jaroslav@1258: * directory, or if an I/O error occurs.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * SecurityManager#checkRead(String)} method denies read access to
jaroslav@1258: * the directory
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public File[] listFiles() {
jaroslav@1258: String[] ss = list();
jaroslav@1258: if (ss == null) return null;
jaroslav@1258: int n = ss.length;
jaroslav@1258: File[] fs = new File[n];
jaroslav@1258: for (int i = 0; i < n; i++) {
jaroslav@1258: fs[i] = new File(ss[i], this);
jaroslav@1258: }
jaroslav@1258: return fs;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns an array of abstract pathnames denoting the files and
jaroslav@1258: * directories in the directory denoted by this abstract pathname that
jaroslav@1258: * satisfy the specified filter. The behavior of this method is the same
jaroslav@1258: * as that of the {@link #listFiles()} method, except that the pathnames in
jaroslav@1258: * the returned array must satisfy the filter. If the given {@code filter}
jaroslav@1258: * is {@code null} then all pathnames are accepted. Otherwise, a pathname
jaroslav@1258: * satisfies the filter if and only if the value {@code true} results when
jaroslav@1258: * the {@link FilenameFilter#accept
jaroslav@1258: * FilenameFilter.accept(File, String)} method of the filter is
jaroslav@1258: * invoked on this abstract pathname and the name of a file or directory in
jaroslav@1258: * the directory that it denotes.
jaroslav@1258: *
jaroslav@1258: * @param filter
jaroslav@1258: * A filename filter
jaroslav@1258: *
jaroslav@1258: * @return An array of abstract pathnames denoting the files and
jaroslav@1258: * directories in the directory denoted by this abstract pathname.
jaroslav@1258: * The array will be empty if the directory is empty. Returns
jaroslav@1258: * {@code null} if this abstract pathname does not denote a
jaroslav@1258: * directory, or if an I/O error occurs.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * SecurityManager#checkRead(String)} method denies read access to
jaroslav@1258: * the directory
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: * @see java.nio.file.Files#newDirectoryStream(Path,String)
jaroslav@1258: */
jaroslav@1258: public File[] listFiles(FilenameFilter filter) {
jaroslav@1258: String ss[] = list();
jaroslav@1258: if (ss == null) return null;
jaroslav@1258: ArrayList Many aspects of the behavior of this method are inherently
jaroslav@1258: * platform-dependent: The rename operation might not be able to move a
jaroslav@1258: * file from one filesystem to another, it might not be atomic, and it
jaroslav@1258: * might not succeed if a file with the destination abstract pathname
jaroslav@1258: * already exists. The return value should always be checked to make sure
jaroslav@1258: * that the rename operation was successful.
jaroslav@1258: *
jaroslav@1258: * Note that the {@link java.nio.file.Files} class defines the {@link
jaroslav@1258: * java.nio.file.Files#move move} method to move or rename a file in a
jaroslav@1258: * platform independent manner.
jaroslav@1258: *
jaroslav@1258: * @param dest The new abstract pathname for the named file
jaroslav@1258: *
jaroslav@1258: * @return All platforms support file-modification times to the nearest second,
jaroslav@1258: * but some provide more precision. The argument will be truncated to fit
jaroslav@1258: * the supported precision. If the operation succeeds and no intervening
jaroslav@1258: * operations on the file take place, then the next invocation of the
jaroslav@1258: * The {@link java.nio.file.Files} class defines methods that operate on
jaroslav@1258: * file attributes including file permissions. This may be used when finer
jaroslav@1258: * manipulation of file permissions is required.
jaroslav@1258: *
jaroslav@1258: * @param writable
jaroslav@1258: * If An invocation of this method of the form file.setWritable(arg)
jaroslav@1258: * behaves in exactly the same way as the invocation
jaroslav@1258: *
jaroslav@1258: * The {@link java.nio.file.Files} class defines methods that operate on
jaroslav@1258: * file attributes including file permissions. This may be used when finer
jaroslav@1258: * manipulation of file permissions is required.
jaroslav@1258: *
jaroslav@1258: * @param readable
jaroslav@1258: * If An invocation of this method of the form file.setReadable(arg)
jaroslav@1258: * behaves in exactly the same way as the invocation
jaroslav@1258: *
jaroslav@1258: * The {@link java.nio.file.Files} class defines methods that operate on
jaroslav@1258: * file attributes including file permissions. This may be used when finer
jaroslav@1258: * manipulation of file permissions is required.
jaroslav@1258: *
jaroslav@1258: * @param executable
jaroslav@1258: * If An invocation of this method of the form file.setExcutable(arg)
jaroslav@1258: * behaves in exactly the same way as the invocation
jaroslav@1258: *
jaroslav@1258: * A particular Java platform may support zero or more
jaroslav@1258: * hierarchically-organized file systems. Each file system has a
jaroslav@1258: * {@code root} directory from which all other files in that file system
jaroslav@1258: * can be reached. Windows platforms, for example, have a root directory
jaroslav@1258: * for each active drive; UNIX platforms have a single root directory,
jaroslav@1258: * namely {@code "/"}. The set of available filesystem roots is affected
jaroslav@1258: * by various system-level operations such as the insertion or ejection of
jaroslav@1258: * removable media and the disconnecting or unmounting of physical or
jaroslav@1258: * virtual disk drives.
jaroslav@1258: *
jaroslav@1258: * This method returns an array of {@code File} objects that denote the
jaroslav@1258: * root directories of the available filesystem roots. It is guaranteed
jaroslav@1258: * that the canonical pathname of any file physically present on the local
jaroslav@1258: * machine will begin with one of the roots returned by this method.
jaroslav@1258: *
jaroslav@1258: * The canonical pathname of a file that resides on some other machine
jaroslav@1258: * and is accessed via a remote-filesystem protocol such as SMB or NFS may
jaroslav@1258: * or may not begin with one of the roots returned by this method. If the
jaroslav@1258: * pathname of a remote file is syntactically indistinguishable from the
jaroslav@1258: * pathname of a local file then it will begin with one of the roots
jaroslav@1258: * returned by this method. Thus, for example, {@code File} objects
jaroslav@1258: * denoting the root directories of the mapped network drives of a Windows
jaroslav@1258: * platform will be returned by this method, while {@code File} objects
jaroslav@1258: * containing UNC pathnames will not be returned by this method.
jaroslav@1258: *
jaroslav@1258: * Unlike most methods in this class, this method does not throw
jaroslav@1258: * security exceptions. If a security manager exists and its {@link
jaroslav@1258: * SecurityManager#checkRead(String)} method denies read access to a
jaroslav@1258: * particular root directory, then that directory will not appear in the
jaroslav@1258: * result.
jaroslav@1258: *
jaroslav@1258: * @return An array of {@code File} objects denoting the available
jaroslav@1258: * filesystem roots, or {@code null} if the set of roots could not
jaroslav@1258: * be determined. The array will be empty if there are no
jaroslav@1258: * filesystem roots.
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: * @see java.nio.file.FileStore
jaroslav@1258: */
jaroslav@1258: public static File[] listRoots() {
jaroslav@1258: return fs.listRoots();
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258:
jaroslav@1258: /* -- Disk usage -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the size of the partition named by this
jaroslav@1258: * abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @return The size, in bytes, of the partition or 0L if this
jaroslav@1258: * abstract pathname does not name a partition
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager has been installed and it denies
jaroslav@1258: * {@link RuntimePermission}("getFileSystemAttributes")
jaroslav@1258: * or its {@link SecurityManager#checkRead(String)} method denies
jaroslav@1258: * read access to the file named by this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public long getTotalSpace() {
jaroslav@1258: SecurityManager sm = System.getSecurityManager();
jaroslav@1258: if (sm != null) {
jaroslav@1258: sm.checkPermission(new RuntimePermission("getFileSystemAttributes"));
jaroslav@1258: sm.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return fs.getSpace(this, FileSystem.SPACE_TOTAL);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the number of unallocated bytes in the partition named by this abstract path name.
jaroslav@1258: *
jaroslav@1258: * The returned number of unallocated bytes is a hint, but not
jaroslav@1258: * a guarantee, that it is possible to use most or any of these
jaroslav@1258: * bytes. The number of unallocated bytes is most likely to be
jaroslav@1258: * accurate immediately after this call. It is likely to be made
jaroslav@1258: * inaccurate by any external I/O operations including those made
jaroslav@1258: * on the system outside of this virtual machine. This method
jaroslav@1258: * makes no guarantee that write operations to this file system
jaroslav@1258: * will succeed.
jaroslav@1258: *
jaroslav@1258: * @return The number of unallocated bytes on the partition 0L
jaroslav@1258: * if the abstract pathname does not name a partition. This
jaroslav@1258: * value will be less than or equal to the total file system size
jaroslav@1258: * returned by {@link #getTotalSpace}.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager has been installed and it denies
jaroslav@1258: * {@link RuntimePermission}("getFileSystemAttributes")
jaroslav@1258: * or its {@link SecurityManager#checkRead(String)} method denies
jaroslav@1258: * read access to the file named by this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public long getFreeSpace() {
jaroslav@1258: SecurityManager sm = System.getSecurityManager();
jaroslav@1258: if (sm != null) {
jaroslav@1258: sm.checkPermission(new RuntimePermission("getFileSystemAttributes"));
jaroslav@1258: sm.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return fs.getSpace(this, FileSystem.SPACE_FREE);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the number of bytes available to this virtual machine on the
jaroslav@1258: * partition named by this abstract pathname. When
jaroslav@1258: * possible, this method checks for write permissions and other operating
jaroslav@1258: * system restrictions and will therefore usually provide a more accurate
jaroslav@1258: * estimate of how much new data can actually be written than {@link
jaroslav@1258: * #getFreeSpace}.
jaroslav@1258: *
jaroslav@1258: * The returned number of available bytes is a hint, but not a
jaroslav@1258: * guarantee, that it is possible to use most or any of these bytes. The
jaroslav@1258: * number of unallocated bytes is most likely to be accurate immediately
jaroslav@1258: * after this call. It is likely to be made inaccurate by any external
jaroslav@1258: * I/O operations including those made on the system outside of this
jaroslav@1258: * virtual machine. This method makes no guarantee that write operations
jaroslav@1258: * to this file system will succeed.
jaroslav@1258: *
jaroslav@1258: * @return The number of available bytes on the partition or 0L
jaroslav@1258: * if the abstract pathname does not name a partition. On
jaroslav@1258: * systems where this information is not available, this method
jaroslav@1258: * will be equivalent to a call to {@link #getFreeSpace}.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager has been installed and it denies
jaroslav@1258: * {@link RuntimePermission}("getFileSystemAttributes")
jaroslav@1258: * or its {@link SecurityManager#checkRead(String)} method denies
jaroslav@1258: * read access to the file named by this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public long getUsableSpace() {
jaroslav@1258: SecurityManager sm = System.getSecurityManager();
jaroslav@1258: if (sm != null) {
jaroslav@1258: sm.checkPermission(new RuntimePermission("getFileSystemAttributes"));
jaroslav@1258: sm.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return fs.getSpace(this, FileSystem.SPACE_USABLE);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /* -- Temporary files -- */
jaroslav@1258:
jaroslav@1258: private static class TempDirectory {
jaroslav@1258: private TempDirectory() { }
jaroslav@1258:
jaroslav@1258: // temporary directory location
jaroslav@1258: private static final File tmpdir = new File(fs.normalize(AccessController
jaroslav@1258: .doPrivileged(new GetPropertyAction("java.io.tmpdir"))));
jaroslav@1258: static File location() {
jaroslav@1258: return tmpdir;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: // file name generation
jaroslav@1258: private static final SecureRandom random = new SecureRandom();
jaroslav@1258: static File generateFile(String prefix, String suffix, File dir) {
jaroslav@1258: long n = random.nextLong();
jaroslav@1258: if (n == Long.MIN_VALUE) {
jaroslav@1258: n = 0; // corner case
jaroslav@1258: } else {
jaroslav@1258: n = Math.abs(n);
jaroslav@1258: }
jaroslav@1258: return new File(dir, prefix + Long.toString(n) + suffix);
jaroslav@1258: }
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Creates a new empty file in the specified directory, using the
jaroslav@1258: * given prefix and suffix strings to generate its name. If this method
jaroslav@1258: * returns successfully then it is guaranteed that:
jaroslav@1258: *
jaroslav@1258: * The To create the new file, the prefix and the suffix may first be
jaroslav@1258: * adjusted to fit the limitations of the underlying platform. If the
jaroslav@1258: * prefix is too long then it will be truncated, but its first three
jaroslav@1258: * characters will always be preserved. If the suffix is too long then it
jaroslav@1258: * too will be truncated, but if it begins with a period character
jaroslav@1258: * ( If the The {@link
jaroslav@1258: * java.nio.file.Files#createTempFile(String,String,java.nio.file.attribute.FileAttribute[])
jaroslav@1258: * Files.createTempFile} method provides an alternative method to create an
jaroslav@1258: * empty file in the temporary-file directory. Files created by that method
jaroslav@1258: * may have more restrictive access permissions to files created by this
jaroslav@1258: * method and so may be more suited to security-sensitive applications.
jaroslav@1258: *
jaroslav@1258: * @param prefix The prefix string to be used in generating the file's
jaroslav@1258: * name; must be at least three characters long
jaroslav@1258: *
jaroslav@1258: * @param suffix The suffix string to be used in generating the file's
jaroslav@1258: * name; may be
jaroslav@1258: * @serialData Default fields followed by separator character.
jaroslav@1258: */
jaroslav@1258: private synchronized void writeObject(java.io.ObjectOutputStream s)
jaroslav@1258: throws IOException
jaroslav@1258: {
jaroslav@1258: s.defaultWriteObject();
jaroslav@1258: s.writeChar(this.separatorChar); // Add the separator character
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * readObject is called to restore this filename.
jaroslav@1258: * The original separator character is read. If it is different
jaroslav@1258: * than the separator character on this system, then the old separator
jaroslav@1258: * is replaced by the local separator.
jaroslav@1258: */
jaroslav@1258: private synchronized void readObject(java.io.ObjectInputStream s)
jaroslav@1258: throws IOException, ClassNotFoundException
jaroslav@1258: {
jaroslav@1258: ObjectInputStream.GetField fields = s.readFields();
jaroslav@1258: String pathField = (String)fields.get("path", null);
jaroslav@1258: char sep = s.readChar(); // read the previous separator char
jaroslav@1258: if (sep != separatorChar)
jaroslav@1258: pathField = pathField.replace(sep, separatorChar);
jaroslav@1258: this.path = fs.normalize(pathField);
jaroslav@1258: this.prefixLength = fs.prefixLength(this.path);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /** use serialVersionUID from JDK 1.0.2 for interoperability */
jaroslav@1258: private static final long serialVersionUID = 301077366599181567L;
jaroslav@1258:
jaroslav@1258: // -- Integration with java.nio.file --
jaroslav@1258:
jaroslav@1258: private volatile transient Path filePath;
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns a {@link Path java.nio.file.Path} object constructed from the
jaroslav@1258: * this abstract path. The resulting {@code Path} is associated with the
jaroslav@1258: * {@link java.nio.file.FileSystems#getDefault default-filesystem}.
jaroslav@1258: *
jaroslav@1258: * The first invocation of this method works as if invoking it were
jaroslav@1258: * equivalent to evaluating the expression:
jaroslav@1258: * If this abstract pathname is the empty abstract pathname then this
jaroslav@1258: * method returns a {@code Path} that may be used to access the current
jaroslav@1258: * user directory.
jaroslav@1258: *
jaroslav@1258: * @return a {@code Path} constructed from this abstract path
jaroslav@1258: *
jaroslav@1258: * @throws java.nio.file.InvalidPathException
jaroslav@1258: * if a {@code Path} object cannot be constructed from the abstract
jaroslav@1258: * path (see {@link java.nio.file.FileSystem#getPath FileSystem.getPath})
jaroslav@1258: *
jaroslav@1258: * @since 1.7
jaroslav@1258: * @see Path#toFile
jaroslav@1258: */
jaroslav@1258: public Path toPath() {
jaroslav@1258: Path result = filePath;
jaroslav@1258: if (result == null) {
jaroslav@1258: synchronized (this) {
jaroslav@1258: result = filePath;
jaroslav@1258: if (result == null) {
jaroslav@1258: result = FileSystems.getDefault().getPath(path);
jaroslav@1258: filePath = result;
jaroslav@1258: }
jaroslav@1258: }
jaroslav@1258: }
jaroslav@1258: return result;
jaroslav@1258: }
jaroslav@1258: }
file.separator. On UNIX systems the value of this
jaroslav@1258: * field is '/'; on Microsoft Windows systems it is '\\'.
jaroslav@1258: *
jaroslav@1258: * @see java.lang.System#getProperty(java.lang.String)
jaroslav@1258: */
jaroslav@1258: public static final char separatorChar = fs.getSeparator();
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * The system-dependent default name-separator character, represented as a
jaroslav@1258: * string for convenience. This string contains a single character, namely
jaroslav@1258: * {@link #separatorChar}.
jaroslav@1258: */
jaroslav@1258: public static final String separator = "" + separatorChar;
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * The system-dependent path-separator character. This field is
jaroslav@1258: * initialized to contain the first character of the value of the system
jaroslav@1258: * property path.separator. This character is used to
jaroslav@1258: * separate filenames in a sequence of files given as a path list.
jaroslav@1258: * On UNIX systems, this character is ':'; on Microsoft Windows systems it
jaroslav@1258: * is ';'.
jaroslav@1258: *
jaroslav@1258: * @see java.lang.System#getProperty(java.lang.String)
jaroslav@1258: */
jaroslav@1258: public static final char pathSeparatorChar = fs.getPathSeparator();
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * The system-dependent path-separator character, represented as a string
jaroslav@1258: * for convenience. This string contains a single character, namely
jaroslav@1258: * {@link #pathSeparatorChar}.
jaroslav@1258: */
jaroslav@1258: public static final String pathSeparator = "" + pathSeparatorChar;
jaroslav@1258:
jaroslav@1258:
jaroslav@1258: /* -- Constructors -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Internal constructor for already-normalized pathname strings.
jaroslav@1258: */
jaroslav@1258: private File(String pathname, int prefixLength) {
jaroslav@1258: this.path = pathname;
jaroslav@1258: this.prefixLength = prefixLength;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Internal constructor for already-normalized pathname strings.
jaroslav@1258: * The parameter order is used to disambiguate this method from the
jaroslav@1258: * public(File, String) constructor.
jaroslav@1258: */
jaroslav@1258: private File(String child, File parent) {
jaroslav@1258: assert parent.path != null;
jaroslav@1258: assert (!parent.path.equals(""));
jaroslav@1258: this.path = fs.resolve(parent.path, child);
jaroslav@1258: this.prefixLength = parent.prefixLength;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Creates a new File instance by converting the given
jaroslav@1258: * pathname string into an abstract pathname. If the given string is
jaroslav@1258: * the empty string, then the result is the empty abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @param pathname A pathname string
jaroslav@1258: * @throws NullPointerException
jaroslav@1258: * If the pathname argument is null
jaroslav@1258: */
jaroslav@1258: public File(String pathname) {
jaroslav@1258: if (pathname == null) {
jaroslav@1258: throw new NullPointerException();
jaroslav@1258: }
jaroslav@1258: this.path = fs.normalize(pathname);
jaroslav@1258: this.prefixLength = fs.prefixLength(this.path);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /* Note: The two-argument File constructors do not interpret an empty
jaroslav@1258: parent abstract pathname as the current user directory. An empty parent
jaroslav@1258: instead causes the child to be resolved against the system-dependent
jaroslav@1258: directory defined by the FileSystem.getDefaultParent method. On Unix
jaroslav@1258: this default is "/", while on Microsoft Windows it is "\\". This is required for
jaroslav@1258: compatibility with the original behavior of this class. */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Creates a new File instance from a parent pathname string
jaroslav@1258: * and a child pathname string.
jaroslav@1258: *
jaroslav@1258: * parent is null then the new
jaroslav@1258: * File instance is created as if by invoking the
jaroslav@1258: * single-argument File constructor on the given
jaroslav@1258: * child pathname string.
jaroslav@1258: *
jaroslav@1258: * parent pathname string is taken to denote
jaroslav@1258: * a directory, and the child pathname string is taken to
jaroslav@1258: * denote either a directory or a file. If the child pathname
jaroslav@1258: * string is absolute then it is converted into a relative pathname in a
jaroslav@1258: * system-dependent way. If parent is the empty string then
jaroslav@1258: * the new File instance is created by converting
jaroslav@1258: * child into an abstract pathname and resolving the result
jaroslav@1258: * against a system-dependent default directory. Otherwise each pathname
jaroslav@1258: * string is converted into an abstract pathname and the child abstract
jaroslav@1258: * pathname is resolved against the parent.
jaroslav@1258: *
jaroslav@1258: * @param parent The parent pathname string
jaroslav@1258: * @param child The child pathname string
jaroslav@1258: * @throws NullPointerException
jaroslav@1258: * If child is null
jaroslav@1258: */
jaroslav@1258: public File(String parent, String child) {
jaroslav@1258: if (child == null) {
jaroslav@1258: throw new NullPointerException();
jaroslav@1258: }
jaroslav@1258: if (parent != null) {
jaroslav@1258: if (parent.equals("")) {
jaroslav@1258: this.path = fs.resolve(fs.getDefaultParent(),
jaroslav@1258: fs.normalize(child));
jaroslav@1258: } else {
jaroslav@1258: this.path = fs.resolve(fs.normalize(parent),
jaroslav@1258: fs.normalize(child));
jaroslav@1258: }
jaroslav@1258: } else {
jaroslav@1258: this.path = fs.normalize(child);
jaroslav@1258: }
jaroslav@1258: this.prefixLength = fs.prefixLength(this.path);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Creates a new File instance from a parent abstract
jaroslav@1258: * pathname and a child pathname string.
jaroslav@1258: *
jaroslav@1258: * parent is null then the new
jaroslav@1258: * File instance is created as if by invoking the
jaroslav@1258: * single-argument File constructor on the given
jaroslav@1258: * child pathname string.
jaroslav@1258: *
jaroslav@1258: * parent abstract pathname is taken to
jaroslav@1258: * denote a directory, and the child pathname string is taken
jaroslav@1258: * to denote either a directory or a file. If the child
jaroslav@1258: * pathname string is absolute then it is converted into a relative
jaroslav@1258: * pathname in a system-dependent way. If parent is the empty
jaroslav@1258: * abstract pathname then the new File instance is created by
jaroslav@1258: * converting child into an abstract pathname and resolving
jaroslav@1258: * the result against a system-dependent default directory. Otherwise each
jaroslav@1258: * pathname string is converted into an abstract pathname and the child
jaroslav@1258: * abstract pathname is resolved against the parent.
jaroslav@1258: *
jaroslav@1258: * @param parent The parent abstract pathname
jaroslav@1258: * @param child The child pathname string
jaroslav@1258: * @throws NullPointerException
jaroslav@1258: * If child is null
jaroslav@1258: */
jaroslav@1258: public File(File parent, String child) {
jaroslav@1258: if (child == null) {
jaroslav@1258: throw new NullPointerException();
jaroslav@1258: }
jaroslav@1258: if (parent != null) {
jaroslav@1258: if (parent.path.equals("")) {
jaroslav@1258: this.path = fs.resolve(fs.getDefaultParent(),
jaroslav@1258: fs.normalize(child));
jaroslav@1258: } else {
jaroslav@1258: this.path = fs.resolve(parent.path,
jaroslav@1258: fs.normalize(child));
jaroslav@1258: }
jaroslav@1258: } else {
jaroslav@1258: this.path = fs.normalize(child);
jaroslav@1258: }
jaroslav@1258: this.prefixLength = fs.prefixLength(this.path);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Creates a new File instance by converting the given
jaroslav@1258: * file: URI into an abstract pathname.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * new File( f.{@link #toURI() toURI}()).equals( f.{@link #getAbsoluteFile() getAbsoluteFile}())
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * so long as the original abstract pathname, the URI, and the new abstract
jaroslav@1258: * pathname are all created in (possibly different invocations of) the same
jaroslav@1258: * Java virtual machine. This relationship typically does not hold,
jaroslav@1258: * however, when a file: URI that is created in a virtual machine
jaroslav@1258: * on one operating system is converted into an abstract pathname in a
jaroslav@1258: * virtual machine on a different operating system.
jaroslav@1258: *
jaroslav@1258: * @param uri
jaroslav@1258: * An absolute, hierarchical URI with a scheme equal to
jaroslav@1258: * "file", a non-empty path component, and undefined
jaroslav@1258: * authority, query, and fragment components
jaroslav@1258: *
jaroslav@1258: * @throws NullPointerException
jaroslav@1258: * If uri is null
jaroslav@1258: *
jaroslav@1258: * @throws IllegalArgumentException
jaroslav@1258: * If the preconditions on the parameter do not hold
jaroslav@1258: *
jaroslav@1258: * @see #toURI()
jaroslav@1258: * @see java.net.URI
jaroslav@1258: * @since 1.4
jaroslav@1258: */
jaroslav@1258: public File(URI uri) {
jaroslav@1258:
jaroslav@1258: // Check our many preconditions
jaroslav@1258: if (!uri.isAbsolute())
jaroslav@1258: throw new IllegalArgumentException("URI is not absolute");
jaroslav@1258: if (uri.isOpaque())
jaroslav@1258: throw new IllegalArgumentException("URI is not hierarchical");
jaroslav@1258: String scheme = uri.getScheme();
jaroslav@1258: if ((scheme == null) || !scheme.equalsIgnoreCase("file"))
jaroslav@1258: throw new IllegalArgumentException("URI scheme is not \"file\"");
jaroslav@1258: if (uri.getAuthority() != null)
jaroslav@1258: throw new IllegalArgumentException("URI has an authority component");
jaroslav@1258: if (uri.getFragment() != null)
jaroslav@1258: throw new IllegalArgumentException("URI has a fragment component");
jaroslav@1258: if (uri.getQuery() != null)
jaroslav@1258: throw new IllegalArgumentException("URI has a query component");
jaroslav@1258: String p = uri.getPath();
jaroslav@1258: if (p.equals(""))
jaroslav@1258: throw new IllegalArgumentException("URI path component is empty");
jaroslav@1258:
jaroslav@1258: // Okay, now initialize
jaroslav@1258: p = fs.fromURIPath(p);
jaroslav@1258: if (File.separatorChar != '/')
jaroslav@1258: p = p.replace('/', File.separatorChar);
jaroslav@1258: this.path = fs.normalize(p);
jaroslav@1258: this.prefixLength = fs.prefixLength(this.path);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258:
jaroslav@1258: /* -- Path-component accessors -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the name of the file or directory denoted by this abstract
jaroslav@1258: * pathname. This is just the last name in the pathname's name
jaroslav@1258: * sequence. If the pathname's name sequence is empty, then the empty
jaroslav@1258: * string is returned.
jaroslav@1258: *
jaroslav@1258: * @return The name of the file or directory denoted by this abstract
jaroslav@1258: * pathname, or the empty string if this pathname's name sequence
jaroslav@1258: * is empty
jaroslav@1258: */
jaroslav@1258: public String getName() {
jaroslav@1258: int index = path.lastIndexOf(separatorChar);
jaroslav@1258: if (index < prefixLength) return path.substring(prefixLength);
jaroslav@1258: return path.substring(index + 1);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the pathname string of this abstract pathname's parent, or
jaroslav@1258: * null if this pathname does not name a parent directory.
jaroslav@1258: *
jaroslav@1258: * null if this pathname
jaroslav@1258: * does not name a parent
jaroslav@1258: */
jaroslav@1258: public String getParent() {
jaroslav@1258: int index = path.lastIndexOf(separatorChar);
jaroslav@1258: if (index < prefixLength) {
jaroslav@1258: if ((prefixLength > 0) && (path.length() > prefixLength))
jaroslav@1258: return path.substring(0, prefixLength);
jaroslav@1258: return null;
jaroslav@1258: }
jaroslav@1258: return path.substring(0, index);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the abstract pathname of this abstract pathname's parent,
jaroslav@1258: * or null if this pathname does not name a parent
jaroslav@1258: * directory.
jaroslav@1258: *
jaroslav@1258: * null if this pathname
jaroslav@1258: * does not name a parent
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public File getParentFile() {
jaroslav@1258: String p = this.getParent();
jaroslav@1258: if (p == null) return null;
jaroslav@1258: return new File(p, this.prefixLength);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Converts this abstract pathname into a pathname string. The resulting
jaroslav@1258: * string uses the {@link #separator default name-separator character} to
jaroslav@1258: * separate the names in the name sequence.
jaroslav@1258: *
jaroslav@1258: * @return The string form of this abstract pathname
jaroslav@1258: */
jaroslav@1258: public String getPath() {
jaroslav@1258: return path;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258:
jaroslav@1258: /* -- Path operations -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether this abstract pathname is absolute. The definition of
jaroslav@1258: * absolute pathname is system dependent. On UNIX systems, a pathname is
jaroslav@1258: * absolute if its prefix is "/". On Microsoft Windows systems, a
jaroslav@1258: * pathname is absolute if its prefix is a drive specifier followed by
jaroslav@1258: * "\\", or if its prefix is "\\\\".
jaroslav@1258: *
jaroslav@1258: * @return true if this abstract pathname is absolute,
jaroslav@1258: * false otherwise
jaroslav@1258: */
jaroslav@1258: public boolean isAbsolute() {
jaroslav@1258: return fs.isAbsolute(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the absolute pathname string of this abstract pathname.
jaroslav@1258: *
jaroslav@1258: * {@link #getPath}
jaroslav@1258: * method. If this abstract pathname is the empty abstract pathname then
jaroslav@1258: * the pathname string of the current user directory, which is named by the
jaroslav@1258: * system property user.dir, is returned. Otherwise this
jaroslav@1258: * pathname is resolved in a system-dependent way. On UNIX systems, a
jaroslav@1258: * relative pathname is made absolute by resolving it against the current
jaroslav@1258: * user directory. On Microsoft Windows systems, a relative pathname is made absolute
jaroslav@1258: * by resolving it against the current directory of the drive named by the
jaroslav@1258: * pathname, if any; if not, it is resolved against the current user
jaroslav@1258: * directory.
jaroslav@1258: *
jaroslav@1258: * @return The absolute pathname string denoting the same file or
jaroslav@1258: * directory as this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a required system property value cannot be accessed.
jaroslav@1258: *
jaroslav@1258: * @see java.io.File#isAbsolute()
jaroslav@1258: */
jaroslav@1258: public String getAbsolutePath() {
jaroslav@1258: return fs.resolve(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the absolute form of this abstract pathname. Equivalent to
jaroslav@1258: * new File(this.{@link #getAbsolutePath}).
jaroslav@1258: *
jaroslav@1258: * @return The absolute abstract pathname denoting the same file or
jaroslav@1258: * directory as this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a required system property value cannot be accessed.
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public File getAbsoluteFile() {
jaroslav@1258: String absPath = getAbsolutePath();
jaroslav@1258: return new File(absPath, fs.prefixLength(absPath));
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the canonical pathname string of this abstract pathname.
jaroslav@1258: *
jaroslav@1258: * {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead} method denies
jaroslav@1258: * read access to the file
jaroslav@1258: *
jaroslav@1258: * @since JDK1.1
jaroslav@1258: * @see Path#toRealPath
jaroslav@1258: */
jaroslav@1258: public String getCanonicalPath() throws IOException {
jaroslav@1258: return fs.canonicalize(fs.resolve(this));
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the canonical form of this abstract pathname. Equivalent to
jaroslav@1258: * new File(this.{@link #getCanonicalPath}).
jaroslav@1258: *
jaroslav@1258: * @return The canonical pathname string denoting the same file or
jaroslav@1258: * directory as this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @throws IOException
jaroslav@1258: * If an I/O error occurs, which is possible because the
jaroslav@1258: * construction of the canonical pathname may require
jaroslav@1258: * filesystem queries
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a required system property value cannot be accessed, or
jaroslav@1258: * if a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead} method denies
jaroslav@1258: * read access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: * @see Path#toRealPath
jaroslav@1258: */
jaroslav@1258: public File getCanonicalFile() throws IOException {
jaroslav@1258: String canonPath = getCanonicalPath();
jaroslav@1258: return new File(canonPath, fs.prefixLength(canonPath));
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: private static String slashify(String path, boolean isDirectory) {
jaroslav@1258: String p = path;
jaroslav@1258: if (File.separatorChar != '/')
jaroslav@1258: p = p.replace(File.separatorChar, '/');
jaroslav@1258: if (!p.startsWith("/"))
jaroslav@1258: p = "/" + p;
jaroslav@1258: if (!p.endsWith("/") && isDirectory)
jaroslav@1258: p = p + "/";
jaroslav@1258: return p;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Converts this abstract pathname into a file: URL. The
jaroslav@1258: * exact form of the URL is system-dependent. If it can be determined that
jaroslav@1258: * the file denoted by this abstract pathname is a directory, then the
jaroslav@1258: * resulting URL will end with a slash.
jaroslav@1258: *
jaroslav@1258: * @return A URL object representing the equivalent file URL
jaroslav@1258: *
jaroslav@1258: * @throws MalformedURLException
jaroslav@1258: * If the path cannot be parsed as a URL
jaroslav@1258: *
jaroslav@1258: * @see #toURI()
jaroslav@1258: * @see java.net.URI
jaroslav@1258: * @see java.net.URI#toURL()
jaroslav@1258: * @see java.net.URL
jaroslav@1258: * @since 1.2
jaroslav@1258: *
jaroslav@1258: * @deprecated This method does not automatically escape characters that
jaroslav@1258: * are illegal in URLs. It is recommended that new code convert an
jaroslav@1258: * abstract pathname into a URL by first converting it into a URI, via the
jaroslav@1258: * {@link #toURI() toURI} method, and then converting the URI into a URL
jaroslav@1258: * via the {@link java.net.URI#toURL() URI.toURL} method.
jaroslav@1258: */
jaroslav@1258: @Deprecated
jaroslav@1258: public URL toURL() throws MalformedURLException {
jaroslav@1258: return new URL("file", "", slashify(getAbsolutePath(), isDirectory()));
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Constructs a file: URI that represents this abstract pathname.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * new {@link #File(java.net.URI) File}( f.toURI()).equals( f.{@link #getAbsoluteFile() getAbsoluteFile}())
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * so long as the original abstract pathname, the URI, and the new abstract
jaroslav@1258: * pathname are all created in (possibly different invocations of) the same
jaroslav@1258: * Java virtual machine. Due to the system-dependent nature of abstract
jaroslav@1258: * pathnames, however, this relationship typically does not hold when a
jaroslav@1258: * file: URI that is created in a virtual machine on one operating
jaroslav@1258: * system is converted into an abstract pathname in a virtual machine on a
jaroslav@1258: * different operating system.
jaroslav@1258: *
jaroslav@1258: * true if and only if the file specified by this
jaroslav@1258: * abstract pathname exists and can be read by the
jaroslav@1258: * application; false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method denies read access to the file
jaroslav@1258: */
jaroslav@1258: public boolean canRead() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return fs.checkAccess(this, FileSystem.ACCESS_READ);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether the application can modify the file denoted by this
jaroslav@1258: * abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the file system actually
jaroslav@1258: * contains a file denoted by this abstract pathname and
jaroslav@1258: * the application is allowed to write to the file;
jaroslav@1258: * false otherwise.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the file
jaroslav@1258: */
jaroslav@1258: public boolean canWrite() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: }
jaroslav@1258: return fs.checkAccess(this, FileSystem.ACCESS_WRITE);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether the file or directory denoted by this abstract pathname
jaroslav@1258: * exists.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the file or directory denoted
jaroslav@1258: * by this abstract pathname exists; false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method denies read access to the file or directory
jaroslav@1258: */
jaroslav@1258: public boolean exists() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return ((fs.getBooleanAttributes(this) & FileSystem.BA_EXISTS) != 0);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether the file denoted by this abstract pathname is a
jaroslav@1258: * directory.
jaroslav@1258: *
jaroslav@1258: * true if and only if the file denoted by this
jaroslav@1258: * abstract pathname exists and is a directory;
jaroslav@1258: * false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method denies read access to the file
jaroslav@1258: */
jaroslav@1258: public boolean isDirectory() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return ((fs.getBooleanAttributes(this) & FileSystem.BA_DIRECTORY)
jaroslav@1258: != 0);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether the file denoted by this abstract pathname is a normal
jaroslav@1258: * file. A file is normal if it is not a directory and, in
jaroslav@1258: * addition, satisfies other system-dependent criteria. Any non-directory
jaroslav@1258: * file created by a Java application is guaranteed to be a normal file.
jaroslav@1258: *
jaroslav@1258: * true if and only if the file denoted by this
jaroslav@1258: * abstract pathname exists and is a normal file;
jaroslav@1258: * false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method denies read access to the file
jaroslav@1258: */
jaroslav@1258: public boolean isFile() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return ((fs.getBooleanAttributes(this) & FileSystem.BA_REGULAR) != 0);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether the file named by this abstract pathname is a hidden
jaroslav@1258: * file. The exact definition of hidden is system-dependent. On
jaroslav@1258: * UNIX systems, a file is considered to be hidden if its name begins with
jaroslav@1258: * a period character ('.'). On Microsoft Windows systems, a file is
jaroslav@1258: * considered to be hidden if it has been marked as such in the filesystem.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the file denoted by this
jaroslav@1258: * abstract pathname is hidden according to the conventions of the
jaroslav@1258: * underlying platform
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method denies read access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public boolean isHidden() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return ((fs.getBooleanAttributes(this) & FileSystem.BA_HIDDEN) != 0);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the time that the file denoted by this abstract pathname was
jaroslav@1258: * last modified.
jaroslav@1258: *
jaroslav@1258: * long value representing the time the file was
jaroslav@1258: * last modified, measured in milliseconds since the epoch
jaroslav@1258: * (00:00:00 GMT, January 1, 1970), or 0L if the
jaroslav@1258: * file does not exist or if an I/O error occurs
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method denies read access to the file
jaroslav@1258: */
jaroslav@1258: public long lastModified() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return fs.getLastModifiedTime(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the length of the file denoted by this abstract pathname.
jaroslav@1258: * The return value is unspecified if this pathname denotes a directory.
jaroslav@1258: *
jaroslav@1258: * 0L if the file does not exist. Some
jaroslav@1258: * operating systems may return 0L for pathnames
jaroslav@1258: * denoting system-dependent entities such as devices or pipes.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method denies read access to the file
jaroslav@1258: */
jaroslav@1258: public long length() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkRead(path);
jaroslav@1258: }
jaroslav@1258: return fs.getLength(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258:
jaroslav@1258: /* -- File operations -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Atomically creates a new, empty file named by this abstract pathname if
jaroslav@1258: * and only if a file with this name does not yet exist. The check for the
jaroslav@1258: * existence of the file and the creation of the file if it does not exist
jaroslav@1258: * are a single operation that is atomic with respect to all other
jaroslav@1258: * filesystem activities that might affect the file.
jaroslav@1258: * true if the named file does not exist and was
jaroslav@1258: * successfully created; false if the named file
jaroslav@1258: * already exists
jaroslav@1258: *
jaroslav@1258: * @throws IOException
jaroslav@1258: * If an I/O error occurred
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public boolean createNewFile() throws IOException {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) security.checkWrite(path);
jaroslav@1258: return fs.createFileExclusively(path);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Deletes the file or directory denoted by this abstract pathname. If
jaroslav@1258: * this pathname denotes a directory, then the directory must be empty in
jaroslav@1258: * order to be deleted.
jaroslav@1258: *
jaroslav@1258: * true if and only if the file or directory is
jaroslav@1258: * successfully deleted; false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkDelete} method denies
jaroslav@1258: * delete access to the file
jaroslav@1258: */
jaroslav@1258: public boolean delete() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkDelete(path);
jaroslav@1258: }
jaroslav@1258: return fs.delete(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Requests that the file or directory denoted by this abstract
jaroslav@1258: * pathname be deleted when the virtual machine terminates.
jaroslav@1258: * Files (or directories) are deleted in the reverse order that
jaroslav@1258: * they are registered. Invoking this method to delete a file or
jaroslav@1258: * directory that is already registered for deletion has no effect.
jaroslav@1258: * Deletion will be attempted only for normal termination of the
jaroslav@1258: * virtual machine, as defined by the Java Language Specification.
jaroslav@1258: *
jaroslav@1258: * {@link
jaroslav@1258: * java.lang.SecurityManager#checkDelete} method denies
jaroslav@1258: * delete access to the file
jaroslav@1258: *
jaroslav@1258: * @see #delete
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public void deleteOnExit() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkDelete(path);
jaroslav@1258: }
jaroslav@1258: DeleteOnExitHook.add(path);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns an array of strings naming the files and directories in the
jaroslav@1258: * directory denoted by this abstract pathname.
jaroslav@1258: *
jaroslav@1258: * true if and only if the directory was
jaroslav@1258: * created; false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method does not permit the named directory to be created
jaroslav@1258: */
jaroslav@1258: public boolean mkdir() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: }
jaroslav@1258: return fs.createDirectory(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Creates the directory named by this abstract pathname, including any
jaroslav@1258: * necessary but nonexistent parent directories. Note that if this
jaroslav@1258: * operation fails it may have succeeded in creating some of the necessary
jaroslav@1258: * parent directories.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the directory was created,
jaroslav@1258: * along with all necessary parent directories; false
jaroslav@1258: * otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkRead(java.lang.String)}
jaroslav@1258: * method does not permit verification of the existence of the
jaroslav@1258: * named directory and all necessary parent directories; or if
jaroslav@1258: * the {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method does not permit the named directory and all necessary
jaroslav@1258: * parent directories to be created
jaroslav@1258: */
jaroslav@1258: public boolean mkdirs() {
jaroslav@1258: if (exists()) {
jaroslav@1258: return false;
jaroslav@1258: }
jaroslav@1258: if (mkdir()) {
jaroslav@1258: return true;
jaroslav@1258: }
jaroslav@1258: File canonFile = null;
jaroslav@1258: try {
jaroslav@1258: canonFile = getCanonicalFile();
jaroslav@1258: } catch (IOException e) {
jaroslav@1258: return false;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: File parent = canonFile.getParentFile();
jaroslav@1258: return (parent != null && (parent.mkdirs() || parent.exists()) &&
jaroslav@1258: canonFile.mkdir());
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Renames the file denoted by this abstract pathname.
jaroslav@1258: *
jaroslav@1258: * true if and only if the renaming succeeded;
jaroslav@1258: * false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to either the old or new pathnames
jaroslav@1258: *
jaroslav@1258: * @throws NullPointerException
jaroslav@1258: * If parameter dest is null
jaroslav@1258: */
jaroslav@1258: public boolean renameTo(File dest) {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: security.checkWrite(dest.path);
jaroslav@1258: }
jaroslav@1258: return fs.rename(this, dest);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Sets the last-modified time of the file or directory named by this
jaroslav@1258: * abstract pathname.
jaroslav@1258: *
jaroslav@1258: * {@link #lastModified} method will return the (possibly
jaroslav@1258: * truncated) time argument that was passed to this method.
jaroslav@1258: *
jaroslav@1258: * @param time The new last-modified time, measured in milliseconds since
jaroslav@1258: * the epoch (00:00:00 GMT, January 1, 1970)
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded;
jaroslav@1258: * false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws IllegalArgumentException If the argument is negative
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the named file
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public boolean setLastModified(long time) {
jaroslav@1258: if (time < 0) throw new IllegalArgumentException("Negative time");
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: }
jaroslav@1258: return fs.setLastModifiedTime(this, time);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Marks the file or directory named by this abstract pathname so that
jaroslav@1258: * only read operations are allowed. After invoking this method the file
jaroslav@1258: * or directory is guaranteed not to change until it is either deleted or
jaroslav@1258: * marked to allow write access. Whether or not a read-only file or
jaroslav@1258: * directory may be deleted depends upon the underlying system.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded;
jaroslav@1258: * false otherwise
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the named file
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public boolean setReadOnly() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: }
jaroslav@1258: return fs.setReadOnly(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Sets the owner's or everybody's write permission for this abstract
jaroslav@1258: * pathname.
jaroslav@1258: *
jaroslav@1258: * true, sets the access permission to allow write
jaroslav@1258: * operations; if false to disallow write operations
jaroslav@1258: *
jaroslav@1258: * @param ownerOnly
jaroslav@1258: * If true, the write permission applies only to the
jaroslav@1258: * owner's write permission; otherwise, it applies to everybody. If
jaroslav@1258: * the underlying file system can not distinguish the owner's write
jaroslav@1258: * permission from that of others, then the permission will apply to
jaroslav@1258: * everybody, regardless of this value.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded. The
jaroslav@1258: * operation will fail if the user does not have permission to change
jaroslav@1258: * the access permissions of this abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the named file
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public boolean setWritable(boolean writable, boolean ownerOnly) {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: }
jaroslav@1258: return fs.setPermission(this, FileSystem.ACCESS_WRITE, writable, ownerOnly);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * A convenience method to set the owner's write permission for this abstract
jaroslav@1258: * pathname.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * file.setWritable(arg, true)
jaroslav@1258: *
jaroslav@1258: * @param writable
jaroslav@1258: * If true, sets the access permission to allow write
jaroslav@1258: * operations; if false to disallow write operations
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded. The
jaroslav@1258: * operation will fail if the user does not have permission to
jaroslav@1258: * change the access permissions of this abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public boolean setWritable(boolean writable) {
jaroslav@1258: return setWritable(writable, true);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Sets the owner's or everybody's read permission for this abstract
jaroslav@1258: * pathname.
jaroslav@1258: *
jaroslav@1258: * true, sets the access permission to allow read
jaroslav@1258: * operations; if false to disallow read operations
jaroslav@1258: *
jaroslav@1258: * @param ownerOnly
jaroslav@1258: * If true, the read permission applies only to the
jaroslav@1258: * owner's read permission; otherwise, it applies to everybody. If
jaroslav@1258: * the underlying file system can not distinguish the owner's read
jaroslav@1258: * permission from that of others, then the permission will apply to
jaroslav@1258: * everybody, regardless of this value.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded. The
jaroslav@1258: * operation will fail if the user does not have permission to
jaroslav@1258: * change the access permissions of this abstract pathname. If
jaroslav@1258: * readable is false and the underlying
jaroslav@1258: * file system does not implement a read permission, then the
jaroslav@1258: * operation will fail.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public boolean setReadable(boolean readable, boolean ownerOnly) {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: }
jaroslav@1258: return fs.setPermission(this, FileSystem.ACCESS_READ, readable, ownerOnly);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * A convenience method to set the owner's read permission for this abstract
jaroslav@1258: * pathname.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * file.setReadable(arg, true)
jaroslav@1258: *
jaroslav@1258: * @param readable
jaroslav@1258: * If true, sets the access permission to allow read
jaroslav@1258: * operations; if false to disallow read operations
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded. The
jaroslav@1258: * operation will fail if the user does not have permission to
jaroslav@1258: * change the access permissions of this abstract pathname. If
jaroslav@1258: * readable is false and the underlying
jaroslav@1258: * file system does not implement a read permission, then the
jaroslav@1258: * operation will fail.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public boolean setReadable(boolean readable) {
jaroslav@1258: return setReadable(readable, true);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Sets the owner's or everybody's execute permission for this abstract
jaroslav@1258: * pathname.
jaroslav@1258: *
jaroslav@1258: * true, sets the access permission to allow execute
jaroslav@1258: * operations; if false to disallow execute operations
jaroslav@1258: *
jaroslav@1258: * @param ownerOnly
jaroslav@1258: * If true, the execute permission applies only to the
jaroslav@1258: * owner's execute permission; otherwise, it applies to everybody.
jaroslav@1258: * If the underlying file system can not distinguish the owner's
jaroslav@1258: * execute permission from that of others, then the permission will
jaroslav@1258: * apply to everybody, regardless of this value.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded. The
jaroslav@1258: * operation will fail if the user does not have permission to
jaroslav@1258: * change the access permissions of this abstract pathname. If
jaroslav@1258: * executable is false and the underlying
jaroslav@1258: * file system does not implement an execute permission, then the
jaroslav@1258: * operation will fail.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public boolean setExecutable(boolean executable, boolean ownerOnly) {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkWrite(path);
jaroslav@1258: }
jaroslav@1258: return fs.setPermission(this, FileSystem.ACCESS_EXECUTE, executable, ownerOnly);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * A convenience method to set the owner's execute permission for this abstract
jaroslav@1258: * pathname.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * file.setExecutable(arg, true)
jaroslav@1258: *
jaroslav@1258: * @param executable
jaroslav@1258: * If true, sets the access permission to allow execute
jaroslav@1258: * operations; if false to disallow execute operations
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the operation succeeded. The
jaroslav@1258: * operation will fail if the user does not have permission to
jaroslav@1258: * change the access permissions of this abstract pathname. If
jaroslav@1258: * executable is false and the underlying
jaroslav@1258: * file system does not implement an excute permission, then the
jaroslav@1258: * operation will fail.
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method denies write access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public boolean setExecutable(boolean executable) {
jaroslav@1258: return setExecutable(executable, true);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests whether the application can execute the file denoted by this
jaroslav@1258: * abstract pathname.
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the abstract pathname exists
jaroslav@1258: * and the application is allowed to execute the file
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkExec(java.lang.String)}
jaroslav@1258: * method denies execute access to the file
jaroslav@1258: *
jaroslav@1258: * @since 1.6
jaroslav@1258: */
jaroslav@1258: public boolean canExecute() {
jaroslav@1258: SecurityManager security = System.getSecurityManager();
jaroslav@1258: if (security != null) {
jaroslav@1258: security.checkExec(path);
jaroslav@1258: }
jaroslav@1258: return fs.checkAccess(this, FileSystem.ACCESS_EXECUTE);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258:
jaroslav@1258: /* -- Filesystem interface -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * List the available filesystem roots.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * This method provides only part of a temporary-file facility. To arrange
jaroslav@1258: * for a file created by this method to be deleted automatically, use the
jaroslav@1258: * {@link #deleteOnExit} method.
jaroslav@1258: *
jaroslav@1258: * prefix argument must be at least three characters
jaroslav@1258: * long. It is recommended that the prefix be a short, meaningful string
jaroslav@1258: * such as "hjb" or "mail". The
jaroslav@1258: * suffix argument may be null, in which case the
jaroslav@1258: * suffix ".tmp" will be used.
jaroslav@1258: *
jaroslav@1258: * '.') then the period and the first three characters
jaroslav@1258: * following it will always be preserved. Once these adjustments have been
jaroslav@1258: * made the name of the new file will be generated by concatenating the
jaroslav@1258: * prefix, five or more internally-generated characters, and the suffix.
jaroslav@1258: *
jaroslav@1258: * directory argument is null then the
jaroslav@1258: * system-dependent default temporary-file directory will be used. The
jaroslav@1258: * default temporary-file directory is specified by the system property
jaroslav@1258: * java.io.tmpdir. On UNIX systems the default value of this
jaroslav@1258: * property is typically "/tmp" or "/var/tmp"; on
jaroslav@1258: * Microsoft Windows systems it is typically "C:\\WINNT\\TEMP". A different
jaroslav@1258: * value may be given to this system property when the Java virtual machine
jaroslav@1258: * is invoked, but programmatic changes to this property are not guaranteed
jaroslav@1258: * to have any effect upon the temporary directory used by this method.
jaroslav@1258: *
jaroslav@1258: * @param prefix The prefix string to be used in generating the file's
jaroslav@1258: * name; must be at least three characters long
jaroslav@1258: *
jaroslav@1258: * @param suffix The suffix string to be used in generating the file's
jaroslav@1258: * name; may be null, in which case the
jaroslav@1258: * suffix ".tmp" will be used
jaroslav@1258: *
jaroslav@1258: * @param directory The directory in which the file is to be created, or
jaroslav@1258: * null if the default temporary-file
jaroslav@1258: * directory is to be used
jaroslav@1258: *
jaroslav@1258: * @return An abstract pathname denoting a newly-created empty file
jaroslav@1258: *
jaroslav@1258: * @throws IllegalArgumentException
jaroslav@1258: * If the prefix argument contains fewer than three
jaroslav@1258: * characters
jaroslav@1258: *
jaroslav@1258: * @throws IOException If a file could not be created
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method does not allow a file to be created
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public static File createTempFile(String prefix, String suffix,
jaroslav@1258: File directory)
jaroslav@1258: throws IOException
jaroslav@1258: {
jaroslav@1258: if (prefix.length() < 3)
jaroslav@1258: throw new IllegalArgumentException("Prefix string too short");
jaroslav@1258: if (suffix == null)
jaroslav@1258: suffix = ".tmp";
jaroslav@1258:
jaroslav@1258: File tmpdir = (directory != null) ? directory : TempDirectory.location();
jaroslav@1258: SecurityManager sm = System.getSecurityManager();
jaroslav@1258: File f;
jaroslav@1258: do {
jaroslav@1258: f = TempDirectory.generateFile(prefix, suffix, tmpdir);
jaroslav@1258: if (sm != null) {
jaroslav@1258: try {
jaroslav@1258: sm.checkWrite(f.getPath());
jaroslav@1258: } catch (SecurityException se) {
jaroslav@1258: // don't reveal temporary directory location
jaroslav@1258: if (directory == null)
jaroslav@1258: throw new SecurityException("Unable to create temporary file");
jaroslav@1258: throw se;
jaroslav@1258: }
jaroslav@1258: }
jaroslav@1258: } while (!fs.createFileExclusively(f.getPath()));
jaroslav@1258: return f;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Creates an empty file in the default temporary-file directory, using
jaroslav@1258: * the given prefix and suffix to generate its name. Invoking this method
jaroslav@1258: * is equivalent to invoking {@link #createTempFile(java.lang.String,
jaroslav@1258: * java.lang.String, java.io.File)
jaroslav@1258: * createTempFile(prefix, suffix, null)}.
jaroslav@1258: *
jaroslav@1258: * null, in which case the
jaroslav@1258: * suffix ".tmp" will be used
jaroslav@1258: *
jaroslav@1258: * @return An abstract pathname denoting a newly-created empty file
jaroslav@1258: *
jaroslav@1258: * @throws IllegalArgumentException
jaroslav@1258: * If the prefix argument contains fewer than three
jaroslav@1258: * characters
jaroslav@1258: *
jaroslav@1258: * @throws IOException If a file could not be created
jaroslav@1258: *
jaroslav@1258: * @throws SecurityException
jaroslav@1258: * If a security manager exists and its {@link
jaroslav@1258: * java.lang.SecurityManager#checkWrite(java.lang.String)}
jaroslav@1258: * method does not allow a file to be created
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: * @see java.nio.file.Files#createTempDirectory(String,FileAttribute[])
jaroslav@1258: */
jaroslav@1258: public static File createTempFile(String prefix, String suffix)
jaroslav@1258: throws IOException
jaroslav@1258: {
jaroslav@1258: return createTempFile(prefix, suffix, null);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /* -- Basic infrastructure -- */
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Compares two abstract pathnames lexicographically. The ordering
jaroslav@1258: * defined by this method depends upon the underlying system. On UNIX
jaroslav@1258: * systems, alphabetic case is significant in comparing pathnames; on Microsoft Windows
jaroslav@1258: * systems it is not.
jaroslav@1258: *
jaroslav@1258: * @param pathname The abstract pathname to be compared to this abstract
jaroslav@1258: * pathname
jaroslav@1258: *
jaroslav@1258: * @return Zero if the argument is equal to this abstract pathname, a
jaroslav@1258: * value less than zero if this abstract pathname is
jaroslav@1258: * lexicographically less than the argument, or a value greater
jaroslav@1258: * than zero if this abstract pathname is lexicographically
jaroslav@1258: * greater than the argument
jaroslav@1258: *
jaroslav@1258: * @since 1.2
jaroslav@1258: */
jaroslav@1258: public int compareTo(File pathname) {
jaroslav@1258: return fs.compare(this, pathname);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Tests this abstract pathname for equality with the given object.
jaroslav@1258: * Returns true if and only if the argument is not
jaroslav@1258: * null and is an abstract pathname that denotes the same file
jaroslav@1258: * or directory as this abstract pathname. Whether or not two abstract
jaroslav@1258: * pathnames are equal depends upon the underlying system. On UNIX
jaroslav@1258: * systems, alphabetic case is significant in comparing pathnames; on Microsoft Windows
jaroslav@1258: * systems it is not.
jaroslav@1258: *
jaroslav@1258: * @param obj The object to be compared with this abstract pathname
jaroslav@1258: *
jaroslav@1258: * @return true if and only if the objects are the same;
jaroslav@1258: * false otherwise
jaroslav@1258: */
jaroslav@1258: public boolean equals(Object obj) {
jaroslav@1258: if ((obj != null) && (obj instanceof File)) {
jaroslav@1258: return compareTo((File)obj) == 0;
jaroslav@1258: }
jaroslav@1258: return false;
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Computes a hash code for this abstract pathname. Because equality of
jaroslav@1258: * abstract pathnames is inherently system-dependent, so is the computation
jaroslav@1258: * of their hash codes. On UNIX systems, the hash code of an abstract
jaroslav@1258: * pathname is equal to the exclusive or of the hash code
jaroslav@1258: * of its pathname string and the decimal value
jaroslav@1258: * 1234321. On Microsoft Windows systems, the hash
jaroslav@1258: * code is equal to the exclusive or of the hash code of
jaroslav@1258: * its pathname string converted to lower case and the decimal
jaroslav@1258: * value 1234321. Locale is not taken into account on
jaroslav@1258: * lowercasing the pathname string.
jaroslav@1258: *
jaroslav@1258: * @return A hash code for this abstract pathname
jaroslav@1258: */
jaroslav@1258: public int hashCode() {
jaroslav@1258: return fs.hashCode(this);
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * Returns the pathname string of this abstract pathname. This is just the
jaroslav@1258: * string returned by the {@link #getPath} method.
jaroslav@1258: *
jaroslav@1258: * @return The string form of this abstract pathname
jaroslav@1258: */
jaroslav@1258: public String toString() {
jaroslav@1258: return getPath();
jaroslav@1258: }
jaroslav@1258:
jaroslav@1258: /**
jaroslav@1258: * WriteObject is called to save this filename.
jaroslav@1258: * The separator character is saved also so it can be replaced
jaroslav@1258: * in case the path is reconstituted on a different host type.
jaroslav@1258: *
jaroslav@1258: * Subsequent invocations of this method return the same {@code Path}.
jaroslav@1258: *
jaroslav@1258: *
jaroslav@1258: * {@link java.nio.file.FileSystems#getDefault FileSystems.getDefault}().{@link
jaroslav@1258: * java.nio.file.FileSystem#getPath getPath}(this.{@link #getPath getPath}());
jaroslav@1258: *