NIO2 API

org.classpath.icedtea.java.io
Class File

java.lang.Object
  extended by java.io.File
      extended by org.classpath.icedtea.java.io.File
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<java.io.File>

public class File
extends java.io.File

An abstract representation of file and directory pathnames.

User interfaces and operating systems use system-dependent pathname strings to name files and directories. This class presents an abstract, system-independent view of hierarchical pathnames. An abstract pathname has two components:

  1. An optional system-dependent prefix string, such as a disk-drive specifier, "/" for the UNIX root directory, or "\\\\" for a Microsoft Windows UNC pathname, and
  2. A sequence of zero or more string names.
The first name in an abstract pathname may be a directory name or, in the case of Microsoft Windows UNC pathnames, a hostname. Each subsequent name in an abstract pathname denotes a directory; the last name may denote either a directory or a file. The empty abstract pathname has no prefix and an empty name sequence.

The conversion of a pathname string to or from an abstract pathname is inherently system-dependent. When an abstract pathname is converted into a pathname string, each name is separated from the next by a single copy of the default separator character. The default name-separator character is defined by the system property file.separator, and is made available in the public static fields File.separator and File.separatorChar of this class. When a pathname string is converted into an abstract pathname, the names within it may be separated by the default name-separator character or by any other name-separator character that is supported by the underlying system.

A pathname, whether abstract or in string form, may be either absolute or relative. An absolute pathname is complete in that no other information is required in order to locate the file that it denotes. A relative pathname, in contrast, must be interpreted in terms of information taken from some other pathname. By default the classes in the java.io package always resolve relative pathnames against the current user directory. This directory is named by the system property user.dir, and is typically the directory in which the Java virtual machine was invoked.

The parent of an abstract pathname may be obtained by invoking the File.getParent() method of this class and consists of the pathname's prefix and each name in the pathname's name sequence except for the last. Each directory's absolute pathname is an ancestor of any File object with an absolute abstract pathname which begins with the directory's absolute pathname. For example, the directory denoted by the abstract pathname "/usr" is an ancestor of the directory denoted by the pathname "/usr/local/bin".

The prefix concept is used to handle root directories on UNIX platforms, and drive specifiers, root directories and UNC pathnames on Microsoft Windows platforms, as follows:

Instances of this class may or may not denote an actual file-system object such as a file or a directory. If it does denote such an object then that object resides in a partition. A partition is an operating system-specific portion of storage for a file system. A single storage device (e.g. a physical disk-drive, flash memory, CD-ROM) may contain multiple partitions. The object, if any, will reside on the partition named by some ancestor of the absolute form of this pathname.

A file system may implement restrictions to certain operations on the actual file-system object, such as reading, writing, and executing. These restrictions are collectively known as access permissions. The file system may have multiple sets of access permissions on a single object. For example, one set may apply to the object's owner, and another may apply to all other users. The access permissions on an object may cause some methods in this class to fail.

Instances of the File class are immutable; that is, once created, the abstract pathname represented by a File object will never change.

Interoperability with java.nio.file package

The java.nio.file package defines interfaces and classes for the Java virtual machine to access files, file attributes, and file systems. This API may be used to overcome many of the limitations of the java.io.File class. The toPath method may be used to obtain a Path that uses the abstract path represented by a File object to locate a file. The resulting Path provides more efficient and extensive access to file attributes, additional file operations, and I/O exceptions to help diagnose errors when an operation on a file fails.

Since:
JDK1.0
See Also:
Serialized Form

Field Summary
 
Fields inherited from class java.io.File
pathSeparator, pathSeparatorChar, separator, separatorChar
 
Constructor Summary
File(File parent, java.lang.String child)
          Creates a new File instance from a parent abstract pathname and a child pathname string.
File(java.lang.String pathname)
          Creates a new File instance by converting the given pathname string into an abstract pathname.
File(java.lang.String parent, java.lang.String child)
          Creates a new File instance from a parent pathname string and a child pathname string.
 
Method Summary
static File createTempFile(java.lang.String prefix, java.lang.String suffix, boolean deleteOnExit, FileAttribute<?>... attrs)
           Creates an empty file in the default temporary-file directory, using the given prefix and suffix to generate its name.
 Path toPath()
           Returns a java.nio.file.Path object constructed from the this abstract path.
 
Methods inherited from class java.io.File
canExecute, canRead, canWrite, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getFreeSpace, getName, getParent, getParentFile, getPath, getTotalSpace, getUsableSpace, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setExecutable, setExecutable, setLastModified, setReadable, setReadable, setReadOnly, setWritable, setWritable, toString, toURI, toURL
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

File

@ConstructorProperties(value="path")
public File(java.lang.String pathname)
Creates a new File instance by converting the given pathname string into an abstract pathname. If the given string is the empty string, then the result is the empty abstract pathname.

Parameters:
pathname - A pathname string
Throws:
java.lang.NullPointerException - If the pathname argument is null

File

public File(java.lang.String parent,
            java.lang.String child)
Creates a new File instance from a parent pathname string and a child pathname string.

If parent is null then the new File instance is created as if by invoking the single-argument File constructor on the given child pathname string.

Otherwise the parent pathname string is taken to denote a directory, and the child pathname string is taken to denote either a directory or a file. If the child pathname string is absolute then it is converted into a relative pathname in a system-dependent way. If parent is the empty string then the new File instance is created by converting child into an abstract pathname and resolving the result against a system-dependent default directory. Otherwise each pathname string is converted into an abstract pathname and the child abstract pathname is resolved against the parent.

Parameters:
parent - The parent pathname string
child - The child pathname string
Throws:
java.lang.NullPointerException - If child is null

File

public File(File parent,
            java.lang.String child)
Creates a new File instance from a parent abstract pathname and a child pathname string.

If parent is null then the new File instance is created as if by invoking the single-argument File constructor on the given child pathname string.

Otherwise the parent abstract pathname is taken to denote a directory, and the child pathname string is taken to denote either a directory or a file. If the child pathname string is absolute then it is converted into a relative pathname in a system-dependent way. If parent is the empty abstract pathname then the new File instance is created by converting child into an abstract pathname and resolving the result against a system-dependent default directory. Otherwise each pathname string is converted into an abstract pathname and the child abstract pathname is resolved against the parent.

Parameters:
parent - The parent abstract pathname
child - The child pathname string
Throws:
java.lang.NullPointerException - If child is null
Method Detail

createTempFile

public static File createTempFile(java.lang.String prefix,
                                  java.lang.String suffix,
                                  boolean deleteOnExit,
                                  FileAttribute<?>... attrs)
                           throws java.io.IOException
Creates an empty file in the default temporary-file directory, using the given prefix and suffix to generate its name. This method is equivalent to invoking the createTempFile(prefix, suffix) method with the addition that the resulting pathname may be requested to be deleted when the Java virtual machine terminates, and the initial file attributes to set atomically when creating the file may be specified.

When the value of the deleteOnExit method is true then the resulting file is requested to be deleted when the Java virtual machine terminates as if by invoking the deleteOnExit method.

The attrs parameter is an optional array of attributes to set atomically when creating the file. Each attribute is identified by its name. If more than one attribute of the same name is included in the array then all but the last occurrence is ignored.

Parameters:
prefix - The prefix string to be used in generating the file's name; must be at least three characters long
suffix - The suffix string to be used in generating the file's name; may be null, in which case the suffix ".tmp" will be used
deleteOnExit - true if the file denoted by resulting pathname be deleted when the Java virtual machine terminates
attrs - An optional list of file attributes to set atomically when creating the file
Returns:
An abstract pathname denoting a newly-created empty file
Throws:
java.lang.IllegalArgumentException - If the prefix argument contains fewer than three characters
java.lang.UnsupportedOperationException - If the array contains an attribute that cannot be set atomically when creating the file
java.io.IOException - If a file could not be created
java.lang.SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method does not allow a file to be created. When the deleteOnExit parameter has the value true then the security manager's SecurityManager.checkDelete(java.lang.String) is invoked to check delete access to the file.
Since:
1.7

toPath

public Path toPath()
Returns a java.nio.file.Path object constructed from the this abstract path. The first invocation of this method works as if invoking it were equivalent to evaluating the expression:
 FileSystems.getDefault().getPath(this.getPath());
 
Subsequent invocations of this method return the same Path.

If this abstract pathname is the empty abstract pathname then this method returns a Path that may be used to access to the current user directory.

Returns:
A Path constructed from this abstract path. The resulting Path is associated with the default-filesystem.
Throws:
InvalidPathException - If a Path object cannot be constructed from the abstract path (see FileSystem.getPath)
Since:
1.7

NIO2 API

Submit a bug or feature

Copyright 2010 Sun Microsystems, Inc. All rights reserved. Use is subject to the terms of the GNU General Public License.