|
NIO2 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.classpath.icedtea.java.nio.file.Path
public abstract class Path
A file reference that locates a file using a system dependent path. The file is not required to exist.
On many platforms a path is the means to locate and access files in a file system. A path is hierarchical and composed of a sequence of directory names separated by a special separator or delimiter.
A system dependent path represented by this class is conceptually a
sequence of name elements and optionally a root component. The name
that is farthest from the root of the directory hierarchy is the
name of a file or directory. The other elements are directory names. The root
component typically identifies a file system hierarchy. A Path
can
represent a root, a root and a sequence of names, or simply one or more name
elements. It defines the getName
, getParent
, getRoot
, and subpath
methods
to access the components or a subsequence of its name elements.
In addition to accessing the components of a path, a Path
also
defines resolve
and relativize
operations. Paths can also be compared
, and tested
against each using using the startsWith
and endWith
methods.
A Path
is either absolute or relative. An
absolute path is complete in that does not need to be combined with another
path in order to locate a file. All operations on relative paths are first
resolved against a file system's default directory as if by invoking the
toAbsolutePath
method.
In addition to the operations defined by the FileRef
interface,
this class defines the following operations:
Directories can be opened
so as to
iterate over the entries in the directory.
Symbolic-links may be created
, or the
target of a link may be read
.
InputStream
or OutputStream
streams can be created to allow for interoperation with the
java.io
package
where required.
The real
path of an existing file may be
obtained.
This class implements Watchable
interface so that a directory
located by a path can be registered
with a WatchService
.
and entries in the directory watched.
java.nio.file.attribute
package provides access to file attributes or meta-data associated
with files. The Attributes
class defines methods that
operate on or return file attributes. For example, the file type, size,
timestamps, and other basic meta-data is obtained, in bulk, by
invoking the Attributes.readBasicFileAttributes
method:
Path file = ... BasicFileAttributes attrs = Attributes.readBasicFileAttributes(file);
Paths created by file systems associated with the default provider
are generally interoperable
with the java.io.File
class. Paths created by other
providers are unlikely to be interoperable with the abstract path names
represented by java.io.File
. The File.toPath
method may be used to obtain a Path
from the abstract
path name represented by a java.io.File java.io.File
object. The
resulting Path
can be used to operate on the same file as the java.io.File
object.
Path objects created by file system's associated with the default provider are interoperable with objects created by other file systems created by the same provider. Path objects created by file systems associated with other providers may not be interoperable with other file systems created by the same provider. The reasons for this are provider specific.
Instances of this class are immutable and safe for use by multiple concurrent threads.
Constructor Summary | |
---|---|
protected |
Path()
Initializes a new instance of this class. |
Method Summary | |
---|---|
abstract int |
compareTo(Path other)
Compares two abstract paths lexicographically. |
abstract Path |
copyTo(Path target,
CopyOption... options)
Copy the file located by this path to a target location. |
abstract Path |
createDirectory(FileAttribute<?>... attrs)
Creates a new directory. |
abstract Path |
createFile(FileAttribute<?>... attrs)
Creates a new and empty file, failing if the file already exists. |
abstract Path |
createLink(Path existing)
Creates a new link (directory entry) for an existing file (optional operation). |
abstract Path |
createSymbolicLink(Path target,
FileAttribute<?>... attrs)
Creates a symbolic link to a target (optional operation). |
abstract void |
delete(boolean failIfNotExists)
Deletes the file located by this path. |
abstract boolean |
endsWith(Path other)
Tests if this path ends with the given path. |
abstract boolean |
equals(Object ob)
Tests this path for equality with the given object. |
abstract boolean |
exists()
Tests whether the file located by this path exists. |
abstract FileSystem |
getFileSystem()
Returns the file system that created this object. |
abstract Path |
getName()
Returns the name of the file or directory denoted by this path. |
abstract Path |
getName(int index)
Returns a name element of this path. |
abstract int |
getNameCount()
Returns the number of name elements in the path. |
abstract Path |
getParent()
Returns the parent path, or null if this path does not
have a parent. |
abstract Path |
getRoot()
Returns the root component of this path as a Path object,
or null if this path does not have a root component. |
abstract int |
hashCode()
Computes a hash code for this path. |
abstract boolean |
isAbsolute()
Tells whether or not this path is absolute. |
abstract boolean |
isHidden()
Tells whether or not the file located by this object is considered hidden. |
abstract Iterator<Path> |
iterator()
Returns an iterator over the name elements of this path. |
abstract Path |
moveTo(Path target,
CopyOption... options)
Move or rename the file located by this path to a target location. |
abstract SeekableByteChannel |
newByteChannel(OpenOption... options)
Opens or creates a file, returning a seekable byte channel to access the file. |
abstract SeekableByteChannel |
newByteChannel(Set<? extends OpenOption> options,
FileAttribute<?>... attrs)
Opens or creates a file, returning a seekable byte channel to access the file. |
abstract DirectoryStream<Path> |
newDirectoryStream()
Opens the directory referenced by this object, returning a DirectoryStream to iterate over all entries in the directory. |
abstract DirectoryStream<Path> |
newDirectoryStream(DirectoryStream.Filter<? super Path> filter)
Opens the directory referenced by this object, returning a DirectoryStream to iterate over the entries in the directory. |
abstract DirectoryStream<Path> |
newDirectoryStream(String glob)
Opens the directory referenced by this object, returning a DirectoryStream to iterate over the entries in the directory. |
abstract InputStream |
newInputStream()
Opens the file located by this path for reading, returning an input stream to read bytes from the file. |
abstract OutputStream |
newOutputStream(OpenOption... options)
Opens or creates the file located by this path for writing, returning an output stream to write bytes to the file. |
abstract OutputStream |
newOutputStream(Set<? extends OpenOption> options,
FileAttribute<?>... attrs)
Opens or creates the file located by this path for writing, returning an output stream to write bytes to the file. |
abstract Path |
normalize()
Returns a path that is this path with redundant name elements eliminated. |
abstract boolean |
notExists()
Tests whether the file located by this path does not exist. |
abstract Path |
readSymbolicLink()
Reads the target of a symbolic link (optional operation). |
abstract WatchKey |
register(WatchService watcher,
WatchEvent.Kind<?>[] events,
WatchEvent.Modifier... modifiers)
Registers the file located by this path with a watch service. |
abstract Path |
relativize(Path other)
Constructs a relative path between this path and a given path. |
abstract Path |
resolve(Path other)
Resolve the given path against this path. |
abstract Path |
resolve(String other)
Converts a given path string to a Path and resolves it against
this Path in exactly the manner specified by the resolve method. |
abstract boolean |
startsWith(Path other)
Tests if this path starts with the given path. |
abstract Path |
subpath(int beginIndex,
int endIndex)
Returns a relative Path that is a subsequence of the name
elements of this path. |
abstract Path |
toAbsolutePath()
Returns a Path object representing the absolute path of this
path. |
abstract Path |
toRealPath(boolean resolveLinks)
Returns the real path of an existing file. |
abstract String |
toString()
Returns the string representation of this path. |
abstract URI |
toUri()
Returns a URI to represent this path. |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Methods inherited from interface org.classpath.icedtea.java.nio.file.FileRef |
---|
checkAccess, delete, getFileAttributeView, getFileAttributeView, getFileStore, isSameFile |
Methods inherited from interface org.classpath.icedtea.java.nio.file.Watchable |
---|
register |
Constructor Detail |
---|
protected Path()
Method Detail |
---|
public abstract FileSystem getFileSystem()
public abstract boolean isAbsolute()
An absolute path is complete in that it doesn't need to be combined with other path information in order to locate a file.
true
if, and only if, this path is absolutepublic abstract Path getRoot()
Path
object,
or null
if this path does not have a root component.
null
public abstract Path getName()
null
if this path has zero elementspublic abstract Path getParent()
null
if this path does not
have a parent.
The parent of this path object consists of this path's root
component, if any, and each element in the path except for the
farthest from the root in the directory hierarchy. This method
does not access the file system; the path or its parent may not exist.
Furthermore, this method does not eliminate special names such as "."
and ".." that may be used in some implementations. On UNIX for example,
the parent of "/a/b/c
" is "/a/b
", and the parent of
"x/y/.
" is "x/y
". This method may be used with the normalize
method, to eliminate redundant names, for cases where
shell-like navigation is required.
If this path has one or more elements, and no root component, then this method is equivalent to evaluating the expression:
subpath(0, getNameCount()-1);
public abstract int getNameCount()
0
if this path
only represents a root componentpublic abstract Path getName(int index)
The index
parameter is the index of the name element to return.
The element that is closest to the root in the directory hierarchy
has index 0
. The element that is farthest from the root
has index count
-1
.
index
- The index of the element
IllegalArgumentException
- If index
is negative, index
is greater than or
equal to the number of elements, or this path has zero name
elements.public abstract Path subpath(int beginIndex, int endIndex)
Path
that is a subsequence of the name
elements of this path.
The beginIndex
and endIndex
parameters specify the
subsequence of name elements. The name that is closest to the root
in the directory hierarchy has index 0
. The name that is
farthest from the root has index count
-1
. The returned Path
object has the name elements
that begin at beginIndex
and extend to the element at index endIndex-1
.
beginIndex
- The index of the first element, inclusiveendIndex
- The index of the last element, exclusive
Path
object that is a subsequence of the name
elements in this Path
IllegalArgumentException
- If beginIndex
is negative, or greater than or equal to
the number of elements. If endIndex
is less than or
equal to beginIndex
, or larger than the number of elements.public abstract boolean startsWith(Path other)
This path starts with the given path if this path's root
component starts with the root component of the given path,
and this path starts with the same name elements as the given path.
If the given path has more name elements than this path then false
is returned.
Whether or not the root component of this path starts with the root component of the given path is file system specific. If this path does not have a root component and the given path has a root component then this path does not start with the given path.
other
- The given path
true
if this path starts with the given path; otherwise
false
public abstract boolean endsWith(Path other)
If the given path has N elements, and no root component, and this path has N or more elements, then this path ends with the given path if the last N elements of each path, starting at the element farthest from the root, are equal.
If the given path has a root component then this path ends with the given path if the root component of this path ends with the root component of the given path, and the corresponding elements of both paths are equal. Whether or not the root component of this path ends with the root component of the given path is file system specific. If this path does not have a root component and the given path has a root component then this path does not end with the given path.
other
- The given path
true
if this path ends with the given path; otherwise
false
public abstract Path normalize()
The precise definition of this method is implementation dependent but
in general it derives from this path, a path that does not contain
redundant name elements. In many file systems, the ".
"
and "..
" are special names used to indicate the current directory
and parent directory. In such file systems all occurrences of ".
"
are considered redundant. If a "..
" is preceded by a
non-"..
" name then both names are considered redundant (the
process to identify such names is repeated until is it no longer
applicable).
This method does not access the file system; the path may not locate
a file that exists. Eliminating "..
" and a preceding name from a
path may result in the path that locates a different file than the original
path. This can arise when the preceding name is a symbolic link.
null
if this path does not
have a root component and all name elements are redundant.getParent()
,
toRealPath(boolean)
public abstract Path resolve(Path other)
If the other
parameter is an absolute
path then this method trivially returns other
. If other
is null
then this path is returned. Otherwise this method
considers this path to be a directory and resolves the given path
against this path. In the simplest case, the given path does not have
a root
component, in which case this method joins
the given path to this path and returns a resulting path that ends
with the given path. Where the given path has a root
component then resolution is highly implementation dependent and therefore
unspecified.
other
- The path to resolve against this path; can be null
relativize(org.classpath.icedtea.java.nio.file.Path)
public abstract Path resolve(String other)
Path
and resolves it against
this Path
in exactly the manner specified by the resolve
method.
other
- The path string to resolve against this path
InvalidPathException
- If the path string cannot be converted to a Path.FileSystem.getPath(java.lang.String)
public abstract Path relativize(Path other)
Relativization is the inverse of resolution
.
This method attempts to construct a relative
path
that when resolved
against this path, yields a
path that locates the same file as the given path. For example, on UNIX,
if this path is "/a/b"
and the given path is "/a/b/c/d"
then the resulting relative path would be "c/d"
. Where this
path and the given path do not have a root
component,
then a relative path can be constructed. A relative path cannot be
constructed if only one of the paths have a root component. Where both
paths have a root component then it is implementation dependent if a
relative path can be constructed. If this path and the given path are
equal
then null
is returned.
For any two paths p and q, where q does not have a root component,
p.relativize(p.resolve(q)).equals(q)
When symbolic-links are supported, then whether the resulting path,
when resolved against this path, yields a path that can be used to locate
the same
file as other
is implementation
dependent. For example, if this path is "/a/b"
and the given
path is "/a/x"
then the resulting relative path may be "../x"
. If "b"
is a symbolic-link then is implementation
dependent if "a/b/../x"
would locate the same file as "/a/x"
.
other
- The resulting path
null
if both paths are
equal
IllegalArgumentException
- If other
is not a Path
that can be relativized
against this pathpublic abstract void delete(boolean failIfNotExists) throws IOException
The failIfNotExists
parameter determines how the method
behaves when the file does not exist. When true
, and the file
does not exist, then the method fails. When false
then the method
does not fail.
As with the delete()
method, an implementation
may require to examine the file to determine if the file is a directory.
Consequently this method may not be atomic with respect to other file
system operations. If the file is a symbolic-link then the link is
deleted and not the final target of the link.
If the file is a directory then the directory must be empty. In some implementations a directory has entries for special files or links that are created when the directory is created. In such implementations a directory is considered empty when only the special entries exist.
On some operating systems it may not be possible to remove a file when it is open and in use by this Java virtual machine or other programs.
failIfNotExists
- true
if the method should fail when the file does not
exist
NoSuchFileException
- If the value of the failIfNotExists
is true
and
the file does not exist (optional specific exception)
DirectoryNotEmptyException
- If the file is a directory and could not otherwise be deleted
because the directory is not empty (optional specific
exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the SecurityManager.checkDelete(String)
method
is invoked to check delete access to the filepublic abstract Path createSymbolicLink(Path target, FileAttribute<?>... attrs) throws IOException
The target
parameter is the target of the link. It may be an
absolute
or relative path and may not exist. When
the target is a relative path then file system operations on the resulting
link are relative to the path of the link.
The attrs
parameter is an optional array of attributes
to set atomically when creating the link. 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.
Where symbolic links are supported, but the underlying FileStore
does not support symbolic links, then this may fail with an IOException
. Additionally, some operating systems may require that the
Java virtual machine be started with implementation specific privileges to
create symbolic links, in which case this method may throw IOException
.
target
- The target of the linkattrs
- The array of attributes to set atomically when creating the
symbolic link
UnsupportedOperationException
- If the implementation does not support symbolic links or the
array contains an attribute that cannot be set atomically when
creating the symbolic link
FileAlreadyExistsException
- If a file with the name already exists (optional specific
exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the the default provider, and a security manager
is installed, it denies LinkPermission
("symbolic")
or its checkWrite
method denies write access to the path of the symbolic link.public abstract Path createLink(Path existing) throws IOException
This path locates the directory entry to create. The existing
parameter is the path to an existing file. This method creates a new
directory entry for the file so that it can be accessed using this path.
On some file systems this is known as creating a "hard link". Whether the
file attributes are maintained for the file or for each directory entry
is file system specific and therefore not specified. Typically, a file
system requires that all links (directory entries) for a file be on the
same file system. Furthermore, on some platforms, the Java virtual machine
may require to be started with implementation specific privileges to
create hard links or to create links to directories.
existing
- A reference to an existing file
UnsupportedOperationException
- If the implementation does not support adding an existing file
to a directory
FileAlreadyExistsException
- If the entry could not otherwise be created because a file of
that name already exists (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the the default provider, and a security manager
is installed, it denies LinkPermission
("hard")
or its checkWrite
method denies write access to both this path and the path of the
existing fileBasicFileAttributes#linkCount
public abstract Path readSymbolicLink() throws IOException
If the file system supports symbolic
links then this method is used read the target of the link, failing
if the file is not a link. The target of the link need not exist. The
returned Path
object will be associated with the same file
system as this Path
.
Path
object representing the target of the link
UnsupportedOperationException
- If the implementation does not support symbolic links
NotLinkException
- If the target could otherwise not be read because the file
is not a link (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the the default provider, and a security manager
is installed, it checks that FilePermission
has been
granted with the "readlink
" action to read the link.public abstract URI toUri()
This method constructs a hierarchical URI
that is absolute
with a non-empty path component. Its scheme
is
equal to the URI scheme that identifies the provider. The exact form of
the other URI components is highly provider dependent. In particular, it
is implementation dependent if its query, fragment, and authority
components are defined or undefined.
For the default provider the path
component
will represent the absolute
path; the query,
fragment components are undefined. Whether the authority component is
defined or not is implementation dependent. There is no guarantee that
the URI
may be used to construct a java.io.File
.
In particular, if this path represents a Universal Naming Convention (UNC)
path, then the UNC server name may be encoded in the authority component
of the resulting URI. In the case of the default provider, and the file
exists, and it can be determined that the file is a directory, then the
resulting URI
will end with a slash.
The default provider provides a similar round-trip guarantee
to the File
class. For a given Path
p it
is guaranteed that
so long as the originalPaths.get
(p.toUri()).equals(p .toAbsolutePath
())
Path
, the URI
, and the new Path
are all created in (possibly different invocations of) the same
Java virtual machine. Whether other providers make any guarantees is
provider specific and therefore unspecified.
When a file system is constructed to access the contents of a file as a file system then it is highly implementation specific if the returned URI represents the given path in the file system or it represents a compound URI that encodes the URI of the enclosing file system. A format for compound URIs is not defined in this release; such a scheme may be added in a future release.
IOError
- If an I/O error occurs obtaining the absolute path, or where a
file system is constructed to access the contents of a file as
a file system, the URI of the enclosing file system cannot be
obtained.
SecurityException
- In the case of the the default provider, and a security manager
is installed, the toAbsolutePath
method
throws a security exception.public abstract Path toAbsolutePath()
Path
object representing the absolute path of this
path.
If this path is already absolute
then this
method simply returns this path. Otherwise, this method resolves the path
in an implementation dependent manner, typically by resolving the path
against a file system default directory. Depending on the implementation,
this method may throw an I/O error if the file system is not accessible.
Path
object representing the absolute path
IOError
- If an I/O error occurs
SecurityException
- In the case of the the default provider, and a security manager
is installed, its checkPropertyAccess
method is invoked to check access to the
system property user.dir
public abstract Path toRealPath(boolean resolveLinks) throws IOException
The precise definition of this method is implementation dependent but
in general it derives from this path, an absolute
path that locates the same
file as this path, but
with name elements that represent the actual name of the directories
and the file. For example, where filename comparisons on a file system
are case insensitive then the name elements represent the names in their
actual case. Additionally, the resulting path has redundant name
elements removed.
If this path is relative then its absolute path is first obtained,
as if by invoking the toAbsolutePath
method.
The resolveLinks
parameter specifies if symbolic links
should be resolved. This parameter is ignored when symbolic links are
not supported. Where supported, and the parameter has the value true
then symbolic links are resolved to their final target. Where the
parameter has the value false
then this method does not resolve
symbolic links. Some implementations allow special names such as
"..
" to refer to the parent directory. When deriving the real
path, and a "..
" (or equivalent) is preceded by a
non-"..
" name then an implementation will typically causes both
names to be removed. When not resolving symbolic links and the preceding
name is a symbolic link then the names are only removed if it guaranteed
that the resulting path will locate the same file as this path.
IOException
- If the file does not exist or an I/O error occurs
SecurityException
- In the case of the the default provider, and a security manager
is installed, its checkRead
method is invoked to check read access to the file, and where
this path is not absolute, its checkPropertyAccess
method is invoked to check access to the
system property user.dir
public abstract Path copyTo(Path target, CopyOption... options) throws IOException
This method copies the file located by this Path
to the
target location with the options
parameter specifying how the
copy is performed. By default, the copy fails if the target file already
exists, except if the source and target are the same
file, in which case this method has no effect. File attributes are not
required to be copied to the target file. If symbolic links are supported,
and the file is a link, then the final target of the link is copied. If
the file is a directory then it creates an empty directory in the target
location (entries in the directory are not copied). This method can be
used with the Files.walkFileTree
utility
method to copy a directory and all entries in the directory, or an entire
file-tree where required.
The options
parameter is an array of options and may contain
any of the following:
Option | Description |
---|---|
REPLACE_EXISTING |
If the target file exists, then the target file is replaced if it is not a non-empty directory. If the target file exists and is a symbolic-link then the symbolic-link is replaced (not the target of the link. |
COPY_ATTRIBUTES |
Attempts to copy the file attributes associated with this file to
the target file. The exact file attributes that are copied is platform
and file system dependent and therefore unspecified. Minimally, the
last-modified-time is
copied to the target file. |
NOFOLLOW_LINKS |
Symbolic-links are not followed. If the file, located by this path,
is a symbolic-link then the link is copied rather than the target of
the link. It is implementation specific if file attributes can be
copied to the new link. In other words, the COPY_ATTRIBUTES
option may be ignored when copying a link. |
An implementation of this interface may support additional implementation specific options.
Copying a file is not an atomic operation. If an IOException
is thrown then it possible that the target file is incomplete or some of
its file attributes have not been copied from the source file. When the
REPLACE_EXISTING
option is specified and the target file exists,
then the target file is replaced. The check for the existence of the file
and the creation of the new file may not be atomic with respect to other
file system activities.
target
- The target locationoptions
- Options specifying how the copy should be done
UnsupportedOperationException
- If the array contains a copy option that is not supported
FileAlreadyExistsException
- The target file exists and cannot be replaced because the
REPLACE_EXISTING
option is not specified, or the target
file is a non-empty directory (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the source file, the
checkWrite
is invoked
to check write access to the target file. If a symbolic link is
copied the security manager is invoked to check LinkPermission
("symbolic")
.public abstract Path moveTo(Path target, CopyOption... options) throws IOException
By default, this method attempts to move the file to the target
location, failing if the target file exists except if the source and
target are the same
file, in which case this method
has no effect. If the file is a symbolic link then the link is moved and
not the target of the link. This method may be invoked to move an empty
directory. In some implementations a directory has entries for special
files or links that are created when the directory is created. In such
implementations a directory is considered empty when only the special
entries exist. When invoked to move a directory that is not empty then the
directory is moved if it does not require moving the entries in the directory.
For example, renaming a directory on the same FileStore
will usually
not require moving the entries in the directory. When moving a directory
requires that its entries be moved then this method fails (by throwing
an IOException
). To move a file tree may involve copying
rather than moving directories and this can be done using the copyTo
method in conjunction with the Files.walkFileTree
utility method.
The options
parameter is an array of options and may contain
any of the following:
Option | Description |
---|---|
REPLACE_EXISTING |
If the target file exists, then the target file is replaced if it is not a non-empty directory. If the target file exists and is a symbolic-link then the symbolic-link is replaced and not the target of the link. |
ATOMIC_MOVE |
The move is performed as an atomic file system operation and all
other options are ignored. If the target file exists then it is
implementation specific if the existing file is replaced or this method
fails by throwing an IOException . If the move cannot be
performed as an atomic file system operation then AtomicMoveNotSupportedException is thrown. This can arise, for
example, when the target location is on a different FileStore
and would require that the file be copied, or target location is
associated with a different provider to this object. |
An implementation of this interface may support additional implementation specific options.
Where the move requires that the file be copied then the last-modified-time
is copied to the
new file. An implementation may also attempt to copy other file
attributes but is not required to fail if the file attributes cannot be
copied. When the move is performed as a non-atomic operation, and a IOException
is thrown, then the state of the files is not defined. The
original file and the target file may both exist, the target file may be
incomplete or some of its file attributes may not been copied from the
original file.
target
- The target locationoptions
- Options specifying how the move should be done
UnsupportedOperationException
- If the array contains a copy option that is not supported
FileAlreadyExistsException
- The target file exists and cannot be replaced because the
REPLACE_EXISTING
option is not specified, or the target
file is a non-empty directory
AtomicMoveNotSupportedException
- The options array contains the ATOMIC_MOVE
option but
the file cannot be moved as an atomic file system operation.
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkWrite
method is invoked to check write access to both the source and
target file.public abstract DirectoryStream<Path> newDirectoryStream() throws IOException
DirectoryStream
to iterate over all entries in the directory. The
elements returned by the directory stream's iterator
are of type Path
, each one representing an entry in the
directory. The Path
objects are obtained as if by resolving
the name of the directory entry against this
path.
The directory stream's close
method should be invoked after
iteration is completed so as to free any resources held for the open
directory. The Files.withDirectory
utility
method is useful for cases where a task is performed on each accepted
entry in a directory. This method closes the directory when iteration is
complete (or an error occurs).
When an implementation supports operations on entries in the
directory that execute in a race-free manner then the returned directory
stream is a SecureDirectoryStream
.
DirectoryStream
object
NotDirectoryException
- If the file could not otherwise be opened because it is not
a directory (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the directory.public abstract DirectoryStream<Path> newDirectoryStream(String glob) throws IOException
DirectoryStream
to iterate over the entries in the directory. The
elements returned by the directory stream's iterator
are of type Path
, each one representing an entry in the
directory. The Path
objects are obtained as if by resolving
the name of the directory entry against this
path. The entries returned by the iterator are filtered by matching the
String
representation of their file names against the given
globbing pattern.
For example, suppose we want to iterate over the files ending with ".java" in a directory:
Path dir = ... DirectoryStream<Path> stream = dir.newDirectoryStream("*.java");
The globbing pattern is specified by the getNameMatcher
method.
The directory stream's close
method should be invoked after
iteration is completed so as to free any resources held for the open
directory.
When an implementation supports operations on entries in the
directory that execute in a race-free manner then the returned directory
stream is a SecureDirectoryStream
.
glob
- The glob pattern
DirectoryStream
object
PatternSyntaxException
- If the pattern is invalid
UnsupportedOperationException
- If the pattern syntax is not known to the implementation
NotDirectoryException
- If the file could not otherwise be opened because it is not
a directory (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the directory.public abstract DirectoryStream<Path> newDirectoryStream(DirectoryStream.Filter<? super Path> filter) throws IOException
DirectoryStream
to iterate over the entries in the directory. The
elements returned by the directory stream's iterator
are of type Path
, each one representing an entry in the
directory. The Path
objects are obtained as if by resolving
the name of the directory entry against this
path. The entries returned by the iterator are filtered by the given
filter
. The DirectoryStreamFilters
class defines factory methods that create useful filters.
The directory stream's close
method should be invoked after
iteration is completed so as to free any resources held for the open
directory. The Files.withDirectory
utility
method is useful for cases where a task is performed on each accepted
entry in a directory. This method closes the directory when iteration is
complete (or an error occurs).
When an implementation supports operations on entries in the
directory that execute in a race-free manner then the returned directory
stream is a SecureDirectoryStream
.
Usage Example: Suppose we want to iterate over the files in a directory that are larger than 8K.
DirectoryStream.Filter<Path> filter = new DirectoryStream.Filter<Path>() { public boolean accept(Path file) { try { long size = Attributes.readBasicFileAttributes(file).size(); return (size > 8192L); } catch (IOException e) { // failed to get size return false; } } }; Path dir = ... DirectoryStream<Path> stream = dir.newDirectoryStream(filter);
filter
- The directory stream filter
DirectoryStream
object
NotDirectoryException
- If the file could not otherwise be opened because it is not
a directory (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the directory.public abstract Path createFile(FileAttribute<?>... attrs) throws IOException
This Path
locates the file to create. The check for the
existence of the file and the creation of the new file if it does not
exist are a single operation that is atomic with respect to all other
filesystem activities that might affect the directory.
The attrs
parameter is an optional array of file-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.
attrs
- An optional list of file attributes to set atomically when
creating the file
UnsupportedOperationException
- If the array contains an attribute that cannot be set atomically
when creating the file
FileAlreadyExistsException
- If a file of that name already exists
(optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkWrite
method is invoked to check write access to the new file.public abstract Path createDirectory(FileAttribute<?>... attrs) throws IOException
This Path
locates the directory to create. The check for the
existence of the file and the creation of the directory if it does not
exist are a single operation that is atomic with respect to all other
filesystem activities that might affect the directory.
The attrs
parameter is an optional array of file-attributes
to set atomically when creating the directory. Each
file 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.
attrs
- An optional list of file attributes to set atomically when
creating the directory
UnsupportedOperationException
- If the array contains an attribute that cannot be set atomically
when creating the directory
FileAlreadyExistsException
- If a directory could not otherwise be created because a file of
that name already exists (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkWrite
method is invoked to check write access to the new directory.public abstract SeekableByteChannel newByteChannel(Set<? extends OpenOption> options, FileAttribute<?>... attrs) throws IOException
The options
parameter determines how the file is opened.
The READ
and WRITE
options determine if the file should be opened for reading and/or writing.
If neither option (or the APPEND
option) is contained in the array then the file is opened for reading.
By default reading or writing commences at the beginning of the file.
In the addition to READ
and WRITE
, the following
options may be present:
Option | Description |
---|---|
APPEND |
If this option is present then the file is opened for writing and
each invocation of the channel's write method first advances
the position to the end of the file and then writes the requested
data. Whether the advancement of the position and the writing of the
data are done in a single atomic operation is system-dependent and
therefore unspecified. This option may not be used in conjunction
with the READ or TRUNCATE_EXISTING options. |
TRUNCATE_EXISTING |
If this option is present then the existing file is truncated to a size of 0 bytes. This option is ignored when the file is opened only for reading. |
CREATE_NEW |
If this option is present then a new file is created, failing if the file already exists or is a symbolic link. When creating a file the check for the existence of the file and the creation of the file if it does not exist is atomic with respect to other file system operations. This option is ignored when the file is opened only for reading. |
CREATE |
If this option is present then an existing file is opened if it
exists, otherwise a new file is created. This option is ignored if the
CREATE_NEW option is also present or the file is opened only
for reading. |
DELETE_ON_CLOSE |
When this option is present then the implementation makes a
best effort attempt to delete the file when closed by the
close method. If the close
method is not invoked then a best effort attempt is made to
delete the file when the Java virtual machine terminates. |
SPARSE |
When creating a new file this option is a hint that the new file will be sparse. This option is ignored when not creating a new file. |
SYNC |
Requires that every update to the file's content or metadata be written synchronously to the underlying storage device. (see Synchronized I/O file integrity). |
DSYNC |
Requires that every update to the file's content be written synchronously to the underlying storage device. (see Synchronized I/O file integrity). |
An implementation may also support additional implementation specific options.
The attrs
parameter is an optional array of file file-attributes
to set atomically when a new file is created.
In the case of the default provider, the returned seekable byte channel
is a FileChannel
.
Usage Examples:
Path file = ... // open file for reading ReadableByteChannel rbc = file.newByteChannel(EnumSet.of(READ))); // open file for writing to the end of an existing file, creating // the file if it doesn't already exist WritableByteChannel wbc = file.newByteChannel(EnumSet.of(CREATE,APPEND)); // create file with initial permissions, opening it for both reading and writing FileAttribute<Set<PosixFilePermission>> perms = ... SeekableByteChannel sbc = file.newByteChannel(EnumSet.of(CREATE_NEW,READ,WRITE), perms);
options
- Options specifying how the file is openedattrs
- An optional list of file attributes to set atomically when
creating the file
IllegalArgumentException
- If the set contains an invalid combination of options
UnsupportedOperationException
- If an unsupported open option is specified or the array contains
attributes that cannot be set atomically when creating the file
FileAlreadyExistsException
- If a file of that name already exists and the CREATE_NEW
option is specified
(optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the path if the file is
opened for reading. The checkWrite
method is invoked to check write access to the path
if the file is opened for writing.public abstract SeekableByteChannel newByteChannel(OpenOption... options) throws IOException
This method extends the options defined by the FileRef
interface and to the options specified by the newByteChannel
method
except that the options are specified by an array. In the case of the
default provider, the returned seekable byte channel is a FileChannel
.
newByteChannel
in interface FileRef
options
- Options specifying how the file is opened
IllegalArgumentException
- If the set contains an invalid combination of options
UnsupportedOperationException
- If an unsupported open option is specified
FileAlreadyExistsException
- If a file of that name already exists and the CREATE_NEW
option is specified
(optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the path if the file is
opened for reading. The checkWrite
method is invoked to check write access to the path
if the file is opened for writing.public abstract InputStream newInputStream() throws IOException
mark
or reset
methods. The stream will be safe for access by
multiple concurrent threads. Reading commences at the beginning of the file.
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the file.public abstract OutputStream newOutputStream(OpenOption... options) throws IOException
This method opens or creates a file in exactly the manner specified
by the newByteChannel
method except that the READ
option may not
be present in the array of open options. If no open options are present
then this method creates a new file for writing or truncates an existing
file.
The resulting stream will not be buffered. The stream will be safe for access by multiple concurrent threads.
Usage Example: Suppose we wish to open a log file for writing so that we append to the file if it already exists, or create it when it doesn't exist.
Path logfile = ... OutputStream out = new BufferedOutputStream(logfile.newOutputStream(CREATE, APPEND));
options
- Options specifying how the file is opened
IllegalArgumentException
- If options
contains an invalid combination of options
UnsupportedOperationException
- If an unsupported open option is specified
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkWrite
method is invoked to check write access to the file.public abstract OutputStream newOutputStream(Set<? extends OpenOption> options, FileAttribute<?>... attrs) throws IOException
This method opens or creates a file in exactly the manner specified
by the newByteChannel
method except that options
parameter may not contain the READ
option. If no open options are present
then this method creates a new file for writing or truncates an existing
file.
The resulting stream will not be buffered. The stream will be safe for access by multiple concurrent threads.
options
- Options specifying how the file is openedattrs
- An optional list of file attributes to set atomically when
creating the file
IllegalArgumentException
- If the set contains an invalid combination of options
UnsupportedOperationException
- If an unsupported open option is specified or the array contains
attributes that cannot be set atomically when creating the file
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkWrite
method is invoked to check write access to the file.public abstract boolean isHidden() throws IOException
hidden
attribute is set.
Depending on the implementation this method may require to access the file system to determine if the file is considered hidden.
true
if the file is considered hidden
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the file.public abstract boolean exists()
This convenience method is intended for cases where it is required to
take action when it can be confirmed that a file exists. This method simply
invokes the checkAccess
method to check if the file
exists. If the checkAccess
method succeeds then this method returns
true
, otherwise if an IOException
is thrown (because the
file doesn't exist or cannot be accessed by this Java virtual machine)
then false
is returned.
Note that the result of this method is immediately outdated. If this method indicates the file exists then there is no guarantee that a subsequence access will succeed. Care should be taken when using this method in security sensitive applications.
true
if the file exists; false
if the file does
not exist or its existence cannot be determined.
SecurityException
- In the case of the default provider, the SecurityManager.checkRead(String)
is invoked to check
read access to the file.notExists()
public abstract boolean notExists()
This convenience method is intended for cases where it is required to
take action when it can be confirmed that a file does not exist. This
method invokes the checkAccess
method to check if the
file exists. If the file does not exist then true
is returned,
otherwise the file exists or cannot be accessed by this Java virtual
machine and false
is returned.
Note that this method is not the complement of the exists
method. Where it is not possible to determine if a file exists
or not then both methods return false
. As with the exists
method, the result of this method is immediately outdated. If this
method indicates the file does exist then there is no guarantee that a
subsequence attempt to create the file will succeed. Care should be taken
when using this method in security sensitive applications.
true
if the file does not exist; false
if the
file exists or its existence cannot be determined.
SecurityException
- In the case of the default provider, the SecurityManager.checkRead(String)
is invoked to check
read access to the file.public abstract WatchKey register(WatchService watcher, WatchEvent.Kind<?>[] events, WatchEvent.Modifier... modifiers) throws IOException
In this release, this path locates a directory that exists. The
directory is registered with the watch service so that entries in the
directory can be watched. The events
parameter is an array of
events to register and may contain the following events:
ENTRY_CREATE
-
entry created or moved into the directoryENTRY_DELETE
-
entry deleted or moved out of the directoryENTRY_MODIFY
-
entry in directory was modified The context
for these events is the
relative path between the directory located by this path, and the path
that locates the directory entry that is created, deleted, or modified.
The set of events may include additional implementation specific
event that are not defined by the enum StandardWatchEventKind
The modifiers
parameter is an array of modifiers
that qualify how the directory is registered. This release does not
define any standard modifiers. The array may contain
implementation specific modifiers.
Where a file is registered with a watch service by means of a symbolic link then it is implementation specific if the watch continues to depend on the existence of the link after it is registered.
Usage Example: Suppose we wish register a directory for entry create, delete, and modify events:
Path dir = ... WatchService watcher = ... WatchKey key = dir.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY);
register
in interface Watchable
watcher
- The watch service to which this object is to be registeredevents
- The events for which this object should be registeredmodifiers
- The modifiers, if any, that modify how the object is registered
UnsupportedOperationException
- If unsupported events or modifiers are specified
IllegalArgumentException
- If an invalid combination of events or modifiers is specified
ClosedWatchServiceException
- If the watch service is closed
NotDirectoryException
- If the file is registered to watch the entries in a directory
and the file is not a directory (optional specific exception)
IOException
- If an I/O error occurs
SecurityException
- In the case of the default provider, and a security manager is
installed, the checkRead
method is invoked to check read access to the file.public abstract Iterator<Path> iterator()
The first element returned by the iterator represents the name
element that is closest to the root in the directory hierarchy, the
second element is the next closest, and so on. The last element returned
is the name of the file or directory denoted by this path. The root
component, if present, is not returned by the iterator.
iterator
in interface Iterable<Path>
public abstract int compareTo(Path other)
compareTo
in interface Comparable<Path>
other
- The path compared to this path.
equal
to this path, a
value less than zero if this path is lexicographically less than
the argument, or a value greater than zero if this path is
lexicographically greater than the argumentpublic abstract boolean equals(Object ob)
If the given object is not a Path, or is a Path associated with a
different provider, then this method immediately returns false
.
Whether or not two path are equal depends on the file system implementation. In some cases the paths are compared without regard to case, and others are case sensitive. This method does not access the file system and the file is not required to exist.
This method satisfies the general contract of the Object.equals
method.
equals
in interface FileRef
equals
in class Object
ob
- The object to which this object is to be compared
true
if, and only if, the given object is a Path
that is identical to this Path
Object.hashCode()
,
Hashtable
public abstract int hashCode()
The hash code is based upon the components of the path, and
satisfies the general contract of the Object.hashCode
method.
hashCode
in interface FileRef
hashCode
in class Object
Object.equals(java.lang.Object)
,
Hashtable
public abstract String toString()
If this path was created by converting a path string using the
getPath
method then the path string returned
by this method may differ from the original String used to create the path.
The returned path string uses the default name separator
to separate names in the path.
toString
in class Object
|
NIO2 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved.