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.