3909N/A * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved. 893N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 893N/A * This code is free software; you can redistribute it and/or modify it 893N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 893N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 893N/A * This code is distributed in the hope that it will be useful, but WITHOUT 893N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 893N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 893N/A * version 2 for more details (a copy is included in the LICENSE file that 893N/A * accompanied this code). 893N/A * You should have received a copy of the GNU General Public License version 893N/A * 2 along with this work; if not, write to the Free Software Foundation, 893N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 893N/A * A file attribute view that supports reading or updating a file's Access 893N/A * Control Lists (ACL) or file owner attributes. 893N/A * <p> ACLs are used to specify access rights to file system objects. An ACL is 893N/A * an ordered list of {@link AclEntry access-control-entries}, each specifying a 893N/A * {@link UserPrincipal} and the level of access for that user principal. This 893N/A * file attribute view defines the {@link #getAcl() getAcl}, and {@link 893N/A * #setAcl(List) setAcl} methods to read and write ACLs based on the ACL 893N/A * Network File System (NFS) version 4 Protocol</i></a>. This file attribute view 893N/A * is intended for file system implementations that support the NFSv4 ACL model 893N/A * or have a <em>well-defined</em> mapping between the NFSv4 ACL model and the ACL 893N/A * model used by the file system. The details of such mapping are implementation 893N/A * dependent and are therefore unspecified. 893N/A * <p> This class also extends {@code FileOwnerAttributeView} so as to define 893N/A * methods to get and set the file owner. 893N/A * <p> When a file system provides access to a set of {@link FileStore 893N/A * file-systems} that are not homogeneous then only some of the file systems may 893N/A * support ACLs. The {@link FileStore#supportsFileAttributeView 893N/A * supportsFileAttributeView} method can be used to test if a file system 893N/A * <a name="interop"><h4>Interoperability</h4></a> 893N/A * RFC 3530 allows for special user identities to be used on platforms that 893N/A * support the POSIX defined access permissions. The special user identities 893N/A * are "{@code OWNER@}", "{@code GROUP@}", and "{@code EVERYONE@}". When both 893N/A * the {@code AclFileAttributeView} and the {@link PosixFileAttributeView} 893N/A * are supported then these special user identities may be included in ACL {@link 893N/A * AclEntry entries} that are read or written. The file system's {@link 893N/A * UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal} 893N/A * to represent these special identities by invoking the {@link 893N/A * UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName} 893N/A * <p> <b>Usage Example:</b> 893N/A * Suppose we wish to add an entry to an existing ACL to grant "joe" access: 893N/A * UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService() 893N/A * .lookupPrincipalByName("joe"); 3471N/A * AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class); 893N/A * // create ACE to give "joe" read access 893N/A * AclEntry entry = AclEntry.newBuilder() 893N/A * .setType(AclEntryType.ALLOW) 893N/A * .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES) 893N/A * // read ACL, insert ACE, re-write ACL 893N/A * List<AclEntry> acl = view.getAcl(); 893N/A * acl.add(0, entry); // insert before any DENY entries 893N/A * <h4> Dynamic Access </h4> 893N/A * <p> Where dynamic access to file attributes is required, the attributes 893N/A * supported by this attribute view are as follows: 893N/A * <table border="1" cellpadding="8"> 893N/A * <td> {@link List}<{@link AclEntry}> </td> 893N/A * <td> {@link UserPrincipal} </td> 3471N/A * <p> The {@link Files#getAttribute getAttribute} method may be used to read 1319N/A * the ACL or owner attributes as if by invoking the {@link #getAcl getAcl} or 1319N/A * {@link #getOwner getOwner} methods. 3471N/A * <p> The {@link Files#setAttribute setAttribute} method may be used to 1319N/A * update the ACL or owner attributes as if by invoking the {@link #setAcl setAcl} 1319N/A * or {@link #setOwner setOwner} methods. 893N/A * <h4> Setting the ACL when creating a file </h4> 893N/A * <p> Implementations supporting this attribute view may also support setting 893N/A * the initial ACL when creating a file or directory. The initial ACL 3471N/A * may be provided to methods such as {@link Files#createFile createFile} or {@link 3471N/A * Files#createDirectory createDirectory} as an {@link FileAttribute} with {@link 893N/A * FileAttribute#name name} {@code "acl:acl"} and a {@link FileAttribute#value 893N/A * value} that is the list of {@code AclEntry} objects. 893N/A * <p> Where an implementation supports an ACL model that differs from the NFSv4 893N/A * defined ACL model then setting the initial ACL when creating the file must 893N/A * translate the ACL to the model supported by the file system. Methods that 893N/A * create a file should reject (by throwing {@link IOException IOException}) 893N/A * any attempt to create a file that would be less secure as a result of the 893N/A * Returns the name of the attribute view. Attribute views of this type 893N/A * have the name {@code "acl"}. 893N/A * Reads the access control list. 893N/A * <p> When the file system uses an ACL model that differs from the NFSv4 893N/A * defined ACL model, then this method returns an ACL that is the translation 893N/A * of the ACL to the NFSv4 ACL model. 893N/A * <p> The returned list is modifiable so as to facilitate changes to the 893N/A * existing ACL. The {@link #setAcl setAcl} method is used to update 893N/A * the file's ACL attribute. 908N/A * @return an ordered list of {@link AclEntry entries} representing the 908N/A * if an I/O error occurs 893N/A * @throws SecurityException 893N/A * In the case of the default provider, a security manager is 893N/A * installed, and it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt> 893N/A * or its {@link SecurityManager#checkRead(String) checkRead} method 893N/A * denies read access to the file. 893N/A * Updates (replace) the access control list. 893N/A * <p> Where the file system supports Access Control Lists, and it uses an 893N/A * ACL model that differs from the NFSv4 defined ACL model, then this method 893N/A * must translate the ACL to the model supported by the file system. This 893N/A * method should reject (by throwing {@link IOException IOException}) any 893N/A * attempt to write an ACL that would appear to make the file more secure 893N/A * than would be the case if the ACL were updated. Where an implementation 893N/A * does not support a mapping of {@link AclEntryType#AUDIT} or {@link 893N/A * AclEntryType#ALARM} entries, then this method ignores these entries when 893N/A * <p> If an ACL entry contains a {@link AclEntry#principal user-principal} 893N/A * that is not associated with the same provider as this attribute view then 893N/A * {@link ProviderMismatchException} is thrown. Additional validation, if 893N/A * any, is implementation dependent. 893N/A * <p> If the file system supports other security related file attributes 893N/A * (such as a file {@link PosixFileAttributes#permissions 893N/A * access-permissions} for example), the updating the access control list 893N/A * may also cause these security related attributes to be updated. 908N/A * the new access control list 908N/A * if an I/O error occurs or the ACL is invalid 893N/A * @throws SecurityException 893N/A * In the case of the default provider, a security manager is 893N/A * installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt> 893N/A * or its {@link SecurityManager#checkWrite(String) checkWrite} 893N/A * method denies write access to the file.