Checked exception thrown when a file system operation is denied, typically
due to a file permission or other access check.

 This exception is not related to the AccessControlException or SecurityException thrown by access controllers or security managers when
access to a file is denied.

Checked exception thrown when a file cannot be moved as an atomic file system
operation.

The type component determines if the entry

The principal component, sometimes called the

The permissions component is a set of

The flags component is a set of flags to indicate how entries are inherited and propagated

An entry in an access control list (ACL).

 The ACL entry represented by this class is based on the ACL model
specified in RFC 3530:
Network File System (NFS) version 4 Protocol. Each entry has four
components as follows:


    The type component determines if the entry
   grants or denies access.

    The principal component, sometimes called the
   "who" component, is a UserPrincipal corresponding to the identity
   that the entry grants or denies access


    The permissions component is a set of
   permissions


    The flags component is a set of flags to indicate how entries are inherited and propagated


 ACL entries are created using an associated AclEntry.Builder object by
invoking its build method.

 ACL entries are immutable and are safe for use by multiple concurrent
threads.

A builder of AclEntry objects.

 A Builder object is obtained by invoking one of the newBuilder methods defined by the AclEntry
class.

 Builder objects are mutable and are not safe for use by multiple
concurrent threads without appropriate synchronization.

// lookup "joe"
UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
    .lookupPrincipalByName("joe");

// get view
AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class);

// create ACE to give "joe" read access
AclEntry entry = AclEntry.newBuilder()
    .setType(AclEntryType.ALLOW)
    .setPrincipal(joe)
    .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES)
    .build();

// read ACL, insert ACE, re-write ACL
List<AclEntry> acl = view.getAcl();
acl.add(0, entry);   // insert before any DENY entries
view.setAcl(acl);

 Name
 Type


 "acl"
 List<AclEntry>


 "owner"
 UserPrincipal

A file attribute view that supports reading or updating a file's Access
Control Lists (ACL) or file owner attributes.

 ACLs are used to specify access rights to file system objects. An ACL is
an ordered list of access-control-entries, each specifying a
UserPrincipal and the level of access for that user principal. This
file attribute view defines the getAcl, and setAcl methods to read and write ACLs based on the ACL
model specified in RFC 3530:
Network File System (NFS) version 4 Protocol. This file attribute view
is intended for file system implementations that support the NFSv4 ACL model
or have a well-defined mapping between the NFSv4 ACL model and the ACL
model used by the file system. The details of such mapping are implementation
dependent and are therefore unspecified.

 This class also extends FileOwnerAttributeView so as to define
methods to get and set the file owner.

 When a file system provides access to a set of file-systems that are not homogeneous then only some of the file systems may
support ACLs. The supportsFileAttributeView method can be used to test if a file system
supports ACLs.

Interoperability

RFC 3530 allows for special user identities to be used on platforms that
support the POSIX defined access permissions. The special user identities
are "OWNER@", "GROUP@", and "EVERYONE@". When both
the AclFileAttributeView and the PosixFileAttributeView
are supported then these special user identities may be included in ACL entries that are read or written. The file system's UserPrincipalLookupService may be used to obtain a UserPrincipal
to represent these special identities by invoking the lookupPrincipalByName
method.

 Usage Example:
Suppose we wish to add an entry to an existing ACL to grant "joe" access:


    // lookup "joe"
    UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
        .lookupPrincipalByName("joe");

    // get view
    AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class);

    // create ACE to give "joe" read access
    AclEntry entry = AclEntry.newBuilder()
        .setType(AclEntryType.ALLOW)
        .setPrincipal(joe)
        .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES)
        .build();

    // read ACL, insert ACE, re-write ACL
    List<AclEntry> acl = view.getAcl();
    acl.add(0, entry);   // insert before any DENY entries
    view.setAcl(acl);

 Dynamic Access
 Where dynamic access to file attributes is required, the attributes
supported by this attribute view are as follows:



     Name
     Type


     "acl"
     List<AclEntry>


     "owner"
     UserPrincipal




 The getAttribute method may be used to read
the ACL or owner attributes as if by invoking the getAcl or
getOwner methods.

 The setAttribute method may be used to
update the ACL or owner attributes as if by invoking the setAcl
or setOwner methods.

 Setting the ACL when creating a file

 Implementations supporting this attribute view may also support setting
the initial ACL when creating a file or directory. The initial ACL
may be provided to methods such as createFile or createDirectory as an FileAttribute with name "acl:acl" and a value that is the list of AclEntry objects.

 Where an implementation supports an ACL model that differs from the NFSv4
defined ACL model then setting the initial ACL when creating the file must
translate the ACL to the model supported by the file system. Methods that
create a file should reject (by throwing IOException)
any attempt to create a file that would be less secure as a result of the
translation.

An object that provides a read-only or updatable view of non-opaque
values associated with an object in a filesystem. This interface is extended
or implemented by specific attribute views that define the attributes
supported by the view. A specific attribute view will typically define
type-safe methods to read or update the attributes that it supports.

Basic attributes associated with a file in a file system.

 Basic file attributes are attributes that are common to many file systems
and consist of mandatory and optional file attributes as defined by this
interface.

 Usage Example:


   Path file = ...
   BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);

 Name
 Type


 "lastModifiedTime"
 FileTime


 "lastAccessTime"
 FileTime


 "creationTime"
 FileTime


 "size"
 Long


 "isRegularFile"
 Boolean


 "isDirectory"
 Boolean


 "isSymbolicLink"
 Boolean


 "isOther"
 Boolean


 "fileKey"
 Object

A file attribute view that provides a view of a basic set of file
attributes common to many file systems. The basic set of file attributes
consist of mandatory and optional file attributes as
defined by the BasicFileAttributes interface.

 The file attributes are retrieved from the file system as a bulk
operation by invoking the readAttributes method.
This class also defines the setTimes method to update the
file's time attributes.

 Where dynamic access to file attributes is required, the attributes
supported by this attribute view have the following names and types:



     Name
     Type


     "lastModifiedTime"
     FileTime


     "lastAccessTime"
     FileTime


     "creationTime"
     FileTime


     "size"
     Long


     "isRegularFile"
     Boolean


     "isDirectory"
     Boolean


     "isSymbolicLink"
     Boolean


     "isOther"
     Boolean


     "fileKey"
     Object




 The getAttribute method may be
used to read any of these attributes as if by invoking the readAttributes() method.

 The setAttribute method may be
used to update the file's last modified time, last access time or create time
attributes as if by invoking the setTimes method.

File attributes associated with a file in a file system that supports
legacy "DOS" attributes.

 Usage Example:


   Path file = ...
   DosFileAttributes attrs = Files.readAttributes(file, DosFileAttributes.class);

 Name
 Type


 readonly
 Boolean


 hidden
 Boolean


 system
 Boolean


 archive
 Boolean

A file attribute view that provides a view of the legacy "DOS" file attributes.
These attributes are supported by file systems such as the File Allocation
Table (FAT) format commonly used in consumer devices.

 A DosFileAttributeView is a BasicFileAttributeView that
additionally supports access to the set of DOS attribute flags that are used
to indicate if the file is read-only, hidden, a system file, or archived.

 Where dynamic access to file attributes is required, the attributes
supported by this attribute view are as defined by BasicFileAttributeView, and in addition, the following attributes are
supported:



     Name
     Type


     readonly
     Boolean


     hidden
     Boolean


     system
     Boolean


     archive
     Boolean




 The getAttribute method may
be used to read any of these attributes, or any of the attributes defined by
BasicFileAttributeView as if by invoking the readAttributes() method.

 The setAttribute method may
be used to update the file's last modified time, last access time or create
time attributes as defined by BasicFileAttributeView. It may also be
used to update the DOS attributes as if by invoking the setReadOnly, setHidden, setSystem, and
setArchive methods respectively.

An object that encapsulates the value of a file attribute that can be set
atomically when creating a new file or directory by invoking the createFile or createDirectory methods.

An attribute view that is a read-only or updatable view of non-opaque
values associated with a file in a filesystem. This interface is extended or
implemented by specific file attribute views that define methods to read
and/or update the attributes of a file.

A file attribute view that supports reading or updating the owner of a file.
This file attribute view is intended for file system implementations that
support a file attribute that represents an identity that is the owner of
the file. Often the owner of a file is the identity of the entity that
created the file.

 The getOwner or setOwner methods may
be used to read or update the owner of the file.

 The getAttribute and
setAttribute methods may also be
used to read or update the owner. In that case, the owner attribute is
identified by the name "owner", and the value of the attribute is
a UserPrincipal.

An attribute view that is a read-only or updatable view of the attributes of
a FileStore.

Represents the value of a file's time stamp attribute. For example, it may
represent the time that the file was last
modified,
accessed,
or created.

 Instances of this class are immutable.

A UserPrincipal representing a group identity, used to
determine access rights to objects in a file system. The exact definition of
a group is implementation specific, but typically, it represents an identity
created for administrative purposes so as to determine the access rights for
the members of the group. Whether an entity can be a member of multiple
groups, and whether groups can be nested, are implementation specified and
therefore not specified.

File attributes associated with files on file systems used by operating systems
that implement the Portable Operating System Interface (POSIX) family of
standards.

 The POSIX attributes of a file are retrieved using a PosixFileAttributeView by invoking its readAttributes method.

Path file = ...
PosixFileAttributes attrs = Files.getFileAttributeView(file, PosixFileAttributeView.class)
    .readAttributes();
System.out.format("%s %s%n",
    attrs.owner().getName(),
    PosixFilePermissions.toString(attrs.permissions()));

 Name
 Type


 "permissions"
 Set<PosixFilePermission>


 "group"
 GroupPrincipal

Path path = ...
Set<PosixFilePermission> perms =
    EnumSet.of(OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ);
Files.createFile(path, PosixFilePermissions.asFileAttribute(perms));

A file attribute view that provides a view of the file attributes commonly
associated with files on file systems used by operating systems that implement
the Portable Operating System Interface (POSIX) family of standards.

 Operating systems that implement the
POSIX family of standards commonly use file systems that have a
file owner, group-owner, and related access
permissions. This file attribute view provides read and write access
to these attributes.

 The readAttributes method is used to read the
file's attributes. The file owner is
represented by a UserPrincipal that is the identity of the file owner
for the purposes of access control. The group-owner, represented by a GroupPrincipal, is the identity of the
group owner, where a group is an identity created for administrative purposes
so as to determine the access rights for the members of the group.

 The permissions attribute is a
set of access permissions. This file attribute view provides access to the nine
permission defined by the PosixFilePermission class.
These nine permission bits determine the read, write, and
execute access for the file owner, group, and others (others
meaning identities other than the owner and members of the group). Some
operating systems and file systems may provide additional permission bits
but access to these other bits is not defined by this class in this release.

 Usage Example:
Suppose we need to print out the owner and access permissions of a file:


    Path file = ...
    PosixFileAttributes attrs = Files.getFileAttributeView(file, PosixFileAttributeView.class)
        .readAttributes();
    System.out.format("%s %s%n",
        attrs.owner().getName(),
        PosixFilePermissions.toString(attrs.permissions()));

 Dynamic Access
 Where dynamic access to file attributes is required, the attributes
supported by this attribute view are as defined by BasicFileAttributeView and FileOwnerAttributeView, and in addition,
the following attributes are supported:



     Name
     Type


     "permissions"
     Set<PosixFilePermission>


     "group"
     GroupPrincipal




 The getAttribute method may be used to read
any of these attributes, or any of the attributes defined by BasicFileAttributeView as if by invoking the readAttributes() method.

 The setAttribute method may be used to update
the file's last modified time, last access time or create time attributes as
defined by BasicFileAttributeView. It may also be used to update
the permissions, owner, or group-owner as if by invoking the setPermissions, setOwner, and setGroup methods respectively.

 Setting Initial Permissions
 Implementations supporting this attribute view may also support setting
the initial permissions when creating a file or directory. The
initial permissions are provided to the createFile
or createDirectory methods as a FileAttribute with name "posix:permissions"
and a value that is the set of permissions. The
following example uses the asFileAttribute method to construct a FileAttribute when creating a
file:



    Path path = ...
    Set<PosixFilePermission> perms =
        EnumSet.of(OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ);
    Files.createFile(path, PosixFilePermissions.asFileAttribute(perms));

 When the access permissions are set at file creation time then the actual
value of the permissions may differ that the value of the attribute object.
The reasons for this are implementation specific. On UNIX systems, for
example, a process has a umask that impacts the permission bits
of newly created files. Where an implementation supports the setting of
the access permissions, and the underlying file system supports access
permissions, then it is required that the value of the actual access
permissions will be equal or less than the value of the attribute
provided to the createFile or createDirectory methods. In other words, the file may
be more secure than requested.

This class consists exclusively of static methods that operate on sets of
PosixFilePermission objects.

A file attribute view that provides a view of a file's user-defined
attributes, sometimes known as extended attributes. User-defined
file attributes are used to store metadata with a file that is not meaningful
to the file system. It is primarily intended for file system implementations
that support such a capability directly but may be emulated. The details of
such emulation are highly implementation specific and therefore not specified.

 This FileAttributeView provides a view of a file's user-defined
attributes as a set of name/value pairs, where the attribute name is
represented by a String. An implementation may require to encode and
decode from the platform or file system representation when accessing the
attribute. The value has opaque content. This attribute view defines the
read and write methods to read the value into
or write from a ByteBuffer. This FileAttributeView is not
intended for use where the size of an attribute value is larger than Integer.MAX_VALUE.

 User-defined attributes may be used in some implementations to store
security related attributes so consequently, in the case of the default
provider at least, all methods that access user-defined attributes require the
RuntimePermission("accessUserDefinedAttributes") permission when a
security manager is installed.

 The supportsFileAttributeView method may be used to test if a specific FileStore supports the storage of user-defined
attributes.

 Where dynamic access to file attributes is required, the getAttribute method may be used to read
the attribute value. The attribute value is returned as a byte array (byte[]).
The setAttribute method may be used
to write the value of a user-defined attribute from a buffer (as if by
invoking the write method), or byte array (byte[]).

A Principal representing an identity used to determine access rights
to objects in a file system.

 On many platforms and file systems an entity requires appropriate access
rights or permissions in order to access objects in a file system. The
access rights are generally performed by checking the identity of the entity.
For example, on implementations that use Access Control Lists (ACLs) to
enforce privilege separation then a file in the file system may have an
associated ACL that determines the access rights of identities specified in
the ACL.

 A UserPrincipal object is an abstract representation of an
identity. It has a name that is typically the username or
account name that it represents. User principal objects may be obtained using
a UserPrincipalLookupService, or returned by FileAttributeView implementations that provide access to identity related
attributes. For example, the AclFileAttributeView and PosixFileAttributeView provide access to a file's owner.

An object to lookup user and group principals by name. A UserPrincipal
represents an identity that may be used to determine access rights to objects
in a file system. A GroupPrincipal represents a group identity.
A UserPrincipalLookupService defines methods to lookup identities by
name or group name (which are typically user or account names). Whether names
and group names are case sensitive or not depends on the implementation.
The exact definition of a group is implementation specific but typically a
group represents an identity created for administrative purposes so as to
determine the access rights for the members of the group. In particular it is
implementation specific if the namespace for names and groups is the
same or is distinct. To ensure consistent and correct behavior across
platforms it is recommended that this API be used as if the namespaces are
distinct. In other words, the lookupPrincipalByName should be used to lookup users, and lookupPrincipalByGroupName should be used to
lookup groups.

Checked exception thrown when a lookup of UserPrincipal fails because
the principal does not exist.

Unchecked exception thrown when an attempt is made to invoke an operation on
a directory stream that is closed.

Unchecked exception thrown when an attempt is made to invoke an operation on
a file and the file system is closed.

Unchecked exception thrown when an attempt is made to invoke an operation on
a watch service that is closed.

An object that configures how to copy or move a file.

 Objects of this type may be used with the Files.copy(Path,Path,CopyOption...),
Files.copy(InputStream,Path,CopyOption...) and Files.move(Path,Path,CopyOption...) methods to configure how a file is
copied or moved.

 The StandardCopyOption enumeration type defines the
standard options.

Runtime exception thrown if an I/O error is encountered when iterating over
the entries in a directory. The I/O error is retrieved as an IOException using the getCause() method.

Checked exception thrown when a file system operation fails because a
directory is not empty.

An object to iterate over the entries in a directory. A directory stream
allows for the convenient use of the for-each construct to iterate over a
directory.

  While DirectoryStream extends Iterable, it is not a
general-purpose Iterable as it supports only a single Iterator; invoking the iterator method to obtain a second
or subsequent iterator throws IllegalStateException.

 An important property of the directory stream's Iterator is that
its hasNext method is guaranteed to read-ahead by
at least one element. If hasNext method returns true, and is
followed by a call to the next method, it is guaranteed that the
next method will not throw an exception due to an I/O error, or
because the stream has been closed. The Iterator does
not support the remove operation.

 A DirectoryStream is opened upon creation and is closed by
invoking the close method. Closing a directory stream releases any
resources associated with the stream. Failure to close the stream may result
in a resource leak. The try-with-resources statement provides a useful
construct to ensure that the stream is closed:


  Path dir = ...
  try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
      for (Path entry: stream) {
          ...
      }
  }

 Once a directory stream is closed, then further access to the directory,
using the Iterator, behaves as if the end of stream has been reached.
Due to read-ahead, the Iterator may return one or more elements
after the directory stream has been closed. Once these buffered elements
have been read, then subsequent calls to the hasNext method returns
false, and subsequent calls to the next method will throw
NoSuchElementException.

 A directory stream is not required to be asynchronously closeable.
If a thread is blocked on the directory stream's iterator reading from the
directory, and another thread invokes the close method, then the
second thread may block until the read operation is complete.

 If an I/O error is encountered when accessing the directory then it
causes the Iterator's hasNext or next methods to
throw DirectoryIteratorException with the IOException as the
cause. As stated above, the hasNext method is guaranteed to
read-ahead by at least one element. This means that if hasNext method
returns true, and is followed by a call to the next method,
then it is guaranteed that the next method will not fail with a
DirectoryIteratorException.

 The elements returned by the iterator are in no specific order. Some file
systems maintain special links to the directory itself and the directory's
parent directory. Entries representing these links are not returned by the
iterator.

 The iterator is weakly consistent. It is thread safe but does not
freeze the directory while iterating, so it may (or may not) reflect updates
to the directory that occur after the DirectoryStream is created.

 Usage Examples:
Suppose we want a list of the source files in a directory. This example uses
both the for-each and try-with-resources constructs.


  List<Path> listSourceFiles(Path dir) throws IOException {
      List<Path> result = new ArrayList<>();
      try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
          for (Path entry: stream) {
              result.add(entry);
          }
      } catch (DirectoryIteratorException ex) {
          // I/O error encounted during the iteration, the cause is an IOException
          throw ex.getCause();
      }
      return result;
  }

An interface that is implemented by objects that decide if a directory
entry should be accepted or filtered. A Filter is passed as the
parameter to the Files.newDirectoryStream(Path,DirectoryStream.Filter)
method when opening a directory to iterate over the entries in the
directory.

Checked exception thrown when an attempt is made to create a file or
directory and a file of that name already exists.

This class consists exclusively of static methods that operate on files,
directories, or other types of files.

 In most cases, the methods defined here will delegate to the associated
file system provider to perform the file operations.

Storage for files. A FileStore represents a storage pool, device,
partition, volume, concrete file system or other implementation specific means
of file storage. The FileStore for where a file is stored is obtained
by invoking the getFileStore method, or all file
stores can be enumerated by invoking the getFileStores method.

 In addition to the methods defined by this class, a file store may support
one or more FileStoreAttributeView classes
that provide a read-only or updatable view of a set of file store attributes.

Provides an interface to a file system and is the factory for objects to
access files and other objects in the file system.

 The default file system, obtained by invoking the FileSystems.getDefault method, provides access to the file system that is
accessible to the Java virtual machine. The FileSystems class defines
methods to create file systems that provide access to other types of (custom)
file systems.

 A file system is the factory for several types of objects:


   The getPath method converts a system dependent
    path string, returning a Path object that may be used
    to locate and access a file.
   The getPathMatcher method is used
    to create a PathMatcher that performs match operations on
    paths.
   The getFileStores method returns an iterator
    over the underlying file-stores.
   The getUserPrincipalLookupService
    method returns the UserPrincipalLookupService to lookup users or
    groups by name.
   The newWatchService method creates a
    WatchService that may be used to watch objects for changes and
    events.


 File systems vary greatly. In some cases the file system is a single
hierarchy of files with one top-level root directory. In other cases it may
have several distinct file hierarchies, each with its own top-level root
directory. The getRootDirectories method may be
used to iterate over the root directories in the file system. A file system
is typically composed of one or more underlying file-stores
that provide the storage for the files. Theses file stores can also vary in
the features they support, and the file attributes or meta-data that
they associate with files.

 A file system is open upon creation and can be closed by invoking its
close method. Once closed, any further attempt to access
objects in the file system cause ClosedFileSystemException to be
thrown. File systems created by the default provider
cannot be closed.

 A FileSystem can provide read-only or read-write access to the
file system. Whether or not a file system provides read-only access is
established when the FileSystem is created and can be tested by invoking
its isReadOnly method. Attempts to write to file stores
by means of an object associated with a read-only file system throws ReadOnlyFileSystemException.

 File systems are safe for use by multiple concurrent threads. The close method may be invoked at any time to close a file system but
whether a file system is asynchronously closeable is provider specific
and therefore unspecified. In other words, if a thread is accessing an
object in a file system, and another thread invokes the close method
then it may require to block until the first operation is complete. Closing
a file system causes all open channels, watch services, and other closeable objects associated with the file system to be closed.

Runtime exception thrown when an attempt is made to create a file system that
already exists.

Thrown when a file system operation fails on one or two files. This class is
the general class for file system exceptions.

Checked exception thrown when a file system loop, or cycle, is encountered.

Runtime exception thrown when a file system cannot be found.

Factory methods for file systems. This class defines the getDefault method to get the default file system and factory methods to
construct other types of file systems.

 The first invocation of any of the methods defined by this class causes
the default provider to be loaded. The default
provider, identified by the URI scheme "file", creates the FileSystem
that provides access to the file systems accessible to the Java virtual
machine. If the process of loading or initializing the default provider fails
then an unspecified error is thrown.

 The first invocation of the installedProviders method, by way of invoking any of the newFileSystem methods defined by this class, locates and loads all
installed file system providers. Installed providers are loaded using the
service-provider loading facility defined by the ServiceLoader class.
Installed providers are loaded using the system class loader. If the
system class loader cannot be found then the extension class loader is used;
if there is no extension class loader then the bootstrap class loader is used.
Providers are typically installed by placing them in a JAR file on the
application class path or in the extension directory, the JAR file contains a
provider-configuration file named java.nio.file.spi.FileSystemProvider
in the resource directory META-INF/services, and the file lists one or
more fully-qualified names of concrete subclass of FileSystemProvider
that have a zero argument constructor.
The ordering that installed providers are located is implementation specific.
If a provider is instantiated and its getScheme returns the same URI scheme of a provider that was previously
instantiated then the most recently instantiated duplicate is discarded. URI
schemes are compared without regard to case. During construction a provider
may safely access files associated with the default provider but care needs
to be taken to avoid circular loading of other installed providers. If
circular loading of installed providers is detected then an unspecified error
is thrown.

 This class also defines factory methods that allow a ClassLoader
to be specified when locating a provider. As with installed providers, the
provider classes are identified by placing the provider configuration file
in the resource directory META-INF/services.

 If a thread initiates the loading of the installed file system providers
and another thread invokes a method that also attempts to load the providers
then the method will block until the loading completes.

Path start = ...
Files.walkFileTree(start, new SimpleFileVisitor<Path>() {
    @Override
    public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
        throws IOException
    {
        Files.delete(file);
        return FileVisitResult.CONTINUE;
    }
    @Override
    public FileVisitResult postVisitDirectory(Path dir, IOException e)
        throws IOException
    {
        if (e == null) {
            Files.delete(dir);
            return FileVisitResult.CONTINUE;
        } else {
            // directory iteration failed
            throw e;
        }
    }
});

final Path source = ...
final Path target = ...

Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE,
    new SimpleFileVisitor<Path>() {
        @Override
        public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
            throws IOException
        {
            Path targetdir = target.resolve(source.relativize(dir));
            try {
                Files.copy(dir, targetdir);
            } catch (FileAlreadyExistsException e) {
                 if (!Files.isDirectory(targetdir))
                     throw e;
            }
            return CONTINUE;
        }
        @Override
        public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
            throws IOException
        {
            Files.copy(file, target.resolve(source.relativize(file)));
            return CONTINUE;
        }
    });

A visitor of files. An implementation of this interface is provided to the
Files.walkFileTree methods to visit each file in
a file tree.

 Usage Examples:
Suppose we want to delete a file tree. In that case, each directory should
be deleted after the entries in the directory are deleted.


    Path start = ...
    Files.walkFileTree(start, new SimpleFileVisitor<Path>() {
        @Override
        public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
            throws IOException
        {
            Files.delete(file);
            return FileVisitResult.CONTINUE;
        }
        @Override
        public FileVisitResult postVisitDirectory(Path dir, IOException e)
            throws IOException
        {
            if (e == null) {
                Files.delete(dir);
                return FileVisitResult.CONTINUE;
            } else {
                // directory iteration failed
                throw e;
            }
        }
    });
 Furthermore, suppose we want to copy a file tree to a target location.
In that case, symbolic links should be followed and the target directory
should be created before the entries in the directory are copied.


    final Path source = ...
    final Path target = ...

    Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE,
        new SimpleFileVisitor<Path>() {
            @Override
            public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
                throws IOException
            {
                Path targetdir = target.resolve(source.relativize(dir));
                try {
                    Files.copy(dir, targetdir);
                } catch (FileAlreadyExistsException e) {
                     if (!Files.isDirectory(targetdir))
                         throw e;
                }
                return CONTINUE;
            }
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
                throws IOException
            {
                Files.copy(file, target.resolve(source.relativize(file)));
                return CONTINUE;
            }
        });

Unchecked exception thrown when path string cannot be converted into a
Path because the path string contains invalid characters, or
the path string is invalid for other file system specific reasons.

The Permission class for link creation operations.

 The following table provides a summary description of what the permission
allows, and discusses the risks of granting code the permission.



Permission Target Name
What the Permission Allows
Risks of Allowing this Permission


  hard
   Ability to add an existing file to a directory. This is sometimes
  known as creating a link, or hard link.
   Extreme care should be taken when granting this permission. It allows
  linking to any file or directory in the file system thus allowing the
  attacker access to all files.


  symbolic
   Ability to create symbolic links.
   Extreme care should be taken when granting this permission. It allows
  linking to any file or directory in the file system thus allowing the
  attacker to access to all files.

Checked exception thrown when an attempt is made to access a file that does
not exist.

Checked exception thrown when a file system operation, intended for a
directory, fails because the file is not a directory.

Checked exception thrown when a file system operation fails because a file
is not a symbolic link.

An object that configures how to open or create a file.

 Objects of this type are used by methods such as newOutputStream, newByteChannel, FileChannel.open, and AsynchronousFileChannel.open
when opening or creating a file.

 The StandardOpenOption enumeration type defines the
standard options.

Path path = FileSystems.getDefault().getPath("logs", "access.log");
BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);

An object that may be used to locate a file in a file system. It will
typically represent a system dependent file path.

 A Path represents a path that is hierarchical and composed of a
sequence of directory and file name elements separated by a special separator
or delimiter. A root component, that identifies a file system
hierarchy, may also be present. The name element that is farthest
from the root of the directory hierarchy is the name of a file or directory.
The other name elements are directory names. A Path can represent a
root, a root and a sequence of names, or simply one or more name elements.
A Path is considered to be an empty path if it consists
solely of one name element that is empty. Accessing a file using an
empty path is equivalent to accessing the default directory of the
file system. Path defines the getFileName,
getParent, getRoot, and subpath methods to access the path components or a subsequence of its name
elements.

 In addition to accessing the components of a path, a Path also
defines the resolve and resolveSibling methods to combine paths. The relativize
method that can be used to construct a relative path between two paths.
Paths can be compared, and tested against each other using
the startsWith and endsWith methods.

 This interface extends Watchable interface so that a directory
located by a path can be registered with a WatchService and entries in the directory watched.

 WARNING: This interface is only intended to be implemented by
those developing custom file system implementations. Methods may be added to
this interface in future releases.

Accessing Files
 Paths may be used with the Files class to operate on files,
directories, and other types of files. For example, suppose we want a BufferedReader to read text from a file "access.log". The
file is located in a directory "logs" relative to the current working
directory and is UTF-8 encoded.


    Path path = FileSystems.getDefault().getPath("logs", "access.log");
    BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);

Interoperability
 Paths 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 toPath
method may be used to obtain a Path from the abstract path name
represented by a java.io.File object. The resulting Path can
be used to operate on the same file as the java.io.File object. In
addition, the toFile method is useful to construct a File from the String representation of a Path.

Concurrency
 Implementations of this interface are immutable and safe for use by
multiple concurrent threads.

An interface that is implemented by objects that perform match operations on
paths.

This class consists exclusively of static methods that return a Path
by converting a path string or URI.

Unchecked exception thrown when an attempt is made to invoke a method on an
object created by one file system provider with a parameter created by a
different file system provider.

Runtime exception thrown when a provider of the required type cannot be found.

Unchecked exception thrown when an attempt is made to update an object
associated with a read-only FileSystem.

A DirectoryStream that defines operations on files that are located
relative to an open directory. A SecureDirectoryStream is intended
for use by sophisticated or security sensitive applications requiring to
traverse file trees or otherwise operate on directories in a race-free manner.
Race conditions can arise when a sequence of file operations cannot be
carried out in isolation. Each of the file operations defined by this
interface specify a relative path. All access to the file is relative
to the open directory irrespective of if the directory is moved or replaced
by an attacker while the directory is open. A SecureDirectoryStream
may also be used as a virtual working directory.

 A SecureDirectoryStream requires corresponding support from the
underlying operating system. Where an implementation supports this features
then the DirectoryStream returned by the newDirectoryStream method will be a SecureDirectoryStream and must
be cast to that type in order to invoke the methods defined by this interface.

 In the case of the default provider, and a security manager is set, then the permission checks are
performed using the path obtained by resolving the given relative path
against the original path of the directory (irrespective of if the
directory is moved since it was opened).

A simple visitor of files with default behavior to visit all files and to
re-throw I/O errors.

 Methods in this class may be overridden subject to their general contract.

Service-provider class for file systems. The methods defined by the Files class will typically delegate to an instance of this
class.

 A file system provider is a concrete implementation of this class that
implements the abstract methods defined by this class. A provider is
identified by a URI scheme. The default provider
is identified by the URI scheme "file". It creates the FileSystem that
provides access to the file systems accessible to the Java virtual machine.
The FileSystems class defines how file system providers are located
and loaded. The default provider is typically a system-default provider but
may be overridden if the system property java.nio.file.spi.DefaultFileSystemProvider is set. In that case, the
provider has a one argument constructor whose formal parameter type is FileSystemProvider. All other providers have a zero argument constructor
that initializes the provider.

 A provider is a factory for one or more FileSystem instances. Each
file system is identified by a URI where the URI's scheme matches
the provider's scheme. The default file system, for example,
is identified by the URI "file:///". A memory-based file system,
for example, may be identified by a URI such as "memory:///?name=logfs".
The newFileSystem method may be used to create a file
system, and the getFileSystem method may be used to
obtain a reference to an existing file system created by the provider. Where
a provider is the factory for a single file system then it is provider dependent
if the file system is created when the provider is initialized, or later when
the newFileSystem method is invoked. In the case of the default
provider, the FileSystem is created when the provider is initialized.

 All of the methods in this class are safe for use by multiple concurrent
threads.

A file type detector for probing a file to guess its file type.

 A file type detector is a concrete implementation of this class, has a
zero-argument constructor, and implements the abstract methods specified
below.

 The means by which a file type detector determines the file type is
highly implementation specific. A simple implementation might examine the
file extension (a convention used in some platforms) and map it to
a file type. In other cases, the file type may be stored as a file  attribute or the bytes in a
file may be examined to guess its file type.

Defines the standard event kinds.

An object that may be registered with a watch service so that it can be
watched for changes and events.

 This interface defines the register method to register
the object with a WatchService returning a WatchKey to
represent the registration. An object may be registered with more than one
watch service. Registration with a watch service is cancelled by invoking the
key's cancel method.

An event or a repeated event for an object that is registered with a WatchService.

 An event is classified by its kind and has a count to indicate the number of times that the event has been
observed. This allows for efficient representation of repeated events. The
context method returns any context associated with
the event. In the case of a repeated event then the context is the same for
all events.

 Watch events are immutable and safe for use by multiple concurrent
threads.

An event kind, for the purposes of identification.

An event modifier that qualifies how a Watchable is registered
with a WatchService.

 This release does not define any standard modifiers.

for (;;) {
    // retrieve key
    WatchKey key = watcher.take();

    // process events
    for (WatchEvent<?> event: key.pollEvents()) {
        :
    }

    // reset the key
    boolean valid = key.reset();
    if (!valid) {
        // object no longer registered
    }
}

A token representing the registration of a watchable object
with a WatchService.

 A watch key is created when a watchable object is registered with a watch
service. The key remains valid until:

   It is cancelled, explicitly, by invoking its cancel
    method, or
   Cancelled implicitly, because the object is no longer accessible,
    or
   By closing the watch service.


 A watch key has a state. When initially created the key is said to be
ready. When an event is detected then the key is signalled
and queued so that it can be retrieved by invoking the watch service's poll or take methods. Once
signalled, a key remains in this state until its reset method
is invoked to return the key to the ready state. Events detected while the
key is in the signalled state are queued but do not cause the key to be
re-queued for retrieval from the watch service. Events are retrieved by
invoking the key's pollEvents method. This method
retrieves and removes all events accumulated for the object. When initially
created, a watch key has no pending events. Typically events are retrieved
when the key is in the signalled state leading to the following idiom:



    for (;;) {
        // retrieve key
        WatchKey key = watcher.take();

        // process events
        for (WatchEvent<?> event: key.pollEvents()) {
            :
        }

        // reset the key
        boolean valid = key.reset();
        if (!valid) {
            // object no longer registered
        }
    }

 Watch keys are safe for use by multiple concurrent threads. Where there
are several threads retrieving signalled keys from a watch service then care
should be taken to ensure that the reset method is only invoked after
the events for the object have been processed. This ensures that one thread
is processing the events for an object at any time.

A watch service that watches registered objects for changes and
events. For example a file manager may use a watch service to monitor a
directory for changes so that it can update its display of the list of files
when files are created or deleted.

 A Watchable object is registered with a watch service by invoking
its register method, returning a WatchKey
to represent the registration. When an event for an object is detected the
key is signalled, and if not currently signalled, it is queued to
the watch service so that it can be retrieved by consumers that invoke the
poll or take methods to retrieve keys
and process events. Once the events have been processed the consumer
invokes the key's reset method to reset the key which
allows the key to be signalled and re-queued with further events.

 Registration with a watch service is cancelled by invoking the key's
cancel method. A key that is queued at the time that
it is cancelled remains in the queue until it is retrieved. Depending on the
object, a key may be cancelled automatically. For example, suppose a
directory is watched and the watch service detects that it has been deleted
or its file system is no longer accessible. When a key is cancelled in this
manner it is signalled and queued, if not currently signalled. To ensure
that the consumer is notified the return value from the reset
method indicates if the key is valid.

 A watch service is safe for use by multiple concurrent consumers. To
ensure that only one consumer processes the events for a particular object at
any time then care should be taken to ensure that the key's reset
method is only invoked after its events have been processed. The close method may be invoked at any time to close the service causing
any threads waiting to retrieve keys, to throw ClosedWatchServiceException.

 File systems may report events faster than they can be retrieved or
processed and an implementation may impose an unspecified limit on the number
of events that it may accumulate. Where an implementation knowingly
discards events then it arranges for the key's pollEvents method to return an element with an event type of OVERFLOW. This event can be used by the
consumer as a trigger to re-examine the state of the object.

 When an event is reported to indicate that a file in a watched directory
has been modified then there is no guarantee that the program (or programs)
that have modified the file have completed. Care should be taken to coordinate
access with other programs that may be updating the file.
The FileChannel class defines methods
to lock regions of a file against access by other programs.

Platform dependencies

 The implementation that observes events from the file system is intended
to map directly on to the native file event notification facility where
available, or to use a primitive mechanism, such as polling, when a native
facility is not available. Consequently, many of the details on how events
are detected, their timeliness, and whether their ordering is preserved are
highly implementation specific. For example, when a file in a watched
directory is modified then it may result in a single ENTRY_MODIFY event in some
implementations but several events in other implementations. Short-lived
files (meaning files that are deleted very quickly after they are created)
may not be detected by primitive implementations that periodically poll the
file system to detect changes.

 If a watched file is not located on a local storage device then it is
implementation specific if changes to the file can be detected. In particular,
it is not required that changes to files carried out on remote systems be
detected.