ACLs are used to specify access rights to file system objects. An ACL is * an ordered list of {@link AclEntry access-control-entries}, each specifying a * {@link UserPrincipal} and the level of access for that user principal. This * file attribute view defines the {@link #getAcl() getAcl}, and {@link * #setAcl(List) 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 {@code FileOwnerAttributeView} so as to define * methods to get and set the file owner. * *
When a file system provides access to a set of {@link FileStore
* file-systems} that are not homogeneous then only some of the file systems may
* support ACLs. The {@link FileStore#supportsFileAttributeView
* 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 "{@code OWNER@}", "{@code GROUP@}", and "{@code EVERYONE@}". When both
* the {@code AclFileAttributeView} and the {@link PosixFileAttributeView}
* are supported then these special user identities may be included in ACL {@link
* AclEntry entries} that are read or written. The file system's {@link
* UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal}
* to represent these special identities by invoking the {@link
* UserPrincipalLookupService#lookupPrincipalByName 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 = file.newFileAttributeView(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);
*
*
* Where dynamic access to file attributes is required, the attributes * supported by this attribute view are as follows: *
** **
** *Name *Type ** *"acl" *{@link List}<{@link AclEntry}> ** *"owner" *{@link UserPrincipal} *
The {@link #getAttribute getAttribute} or {@link #readAttributes * readAttributes} methods may be used to read the ACL or owner attributes as if * by invoking the {@link #getAcl getAcl} or {@link #getOwner getOwner} methods. * *
The {@link #setAttribute setAttribute} method may be used to update the * ACL or owner attributes as if by invoking the {@link #setAcl setAcl} or {@link * #setOwner setOwner} methods. * *
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 {@link Path#createFile createFile} or {@link * Path#createDirectory createDirectory} as an {@link FileAttribute} with {@link * FileAttribute#name name} {@code "acl:acl"} and a {@link FileAttribute#value * value} that is the list of {@code 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 {@link IOException IOException}) * any attempt to create a file that would be less secure as a result of the * translation. * * @since 1.7 * @see Attributes#getAcl * @see Attributes#setAcl */ public interface AclFileAttributeView extends FileOwnerAttributeView { /** * Returns the name of the attribute view. Attribute views of this type * have the name {@code "acl"}. */ @Override String name(); /** * Reads the access control list. * *
When the file system uses an ACL model that differs from the NFSv4 * defined ACL model, then this method returns an ACL that is the translation * of the ACL to the NFSv4 ACL model. * *
The returned list is modifiable so as to facilitate changes to the
* existing ACL. The {@link #setAcl setAcl} method is used to update
* the file's ACL attribute.
*
* @return An ordered list of {@link AclEntry entries} representing the
* ACL
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link RuntimePermission}("accessUserInformation")
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
List Where the file system supports Access Control Lists, and it uses an
* ACL model that differs from the NFSv4 defined ACL model, then this method
* must translate the ACL to the model supported by the file system. This
* method should reject (by throwing {@link IOException IOException}) any
* attempt to write an ACL that would appear to make the file more secure
* than would be the case if the ACL were updated. Where an implementation
* does not support a mapping of {@link AclEntryType#AUDIT} or {@link
* AclEntryType#ALARM} entries, then this method ignores these entries when
* writing the ACL.
*
* If an ACL entry contains a {@link AclEntry#principal user-principal}
* that is not associated with the same provider as this attribute view then
* {@link ProviderMismatchException} is thrown. Additional validation, if
* any, is implementation dependent.
*
* If the file system supports other security related file attributes
* (such as a file {@link PosixFileAttributes#permissions
* access-permissions} for example), the updating the access control list
* may also cause these security related attributes to be updated.
*
* @param acl
* The new access control list
*
* @throws IOException
* If an I/O error occurs or the ACL is invalid
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, it denies {@link RuntimePermission}("accessUserInformation")
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
void setAcl(List