48 * <p> This class also extends {@code FileOwnerAttributeView} so as to define 49 * methods to get and set the file owner. 50 * 51 * <p> When a file system provides access to a set of {@link FileStore 52 * file-systems} that are not homogeneous then only some of the file systems may 53 * support ACLs. The {@link FileStore#supportsFileAttributeView 54 * supportsFileAttributeView} method can be used to test if a file system 55 * supports ACLs. 56 * 57 * <a name="interop"><h4>Interoperability</h4></a> 58 * 59 * RFC 3530 allows for special user identities to be used on platforms that 60 * support the POSIX defined access permissions. The special user identities 61 * are "{@code OWNER@}", "{@code GROUP@}", and "{@code EVERYONE@}". When both 62 * the {@code AclFileAttributeView} and the {@link PosixFileAttributeView} 63 * are supported then these special user identities may be included in ACL {@link 64 * AclEntry entries} that are read or written. The file system's {@link 65 * UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal} 66 * to represent these special identities by invoking the {@link 67 * UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName} 68 * method. 69 * 70 * <p> <b>Usage Example:</b> 71 * Suppose we wish to add an entry to an existing ACL to grant "joe" access: 72 * <pre> 73 * // lookup "joe" 74 * UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService() 75 * .lookupPrincipalByName("joe"); 76 * 77 * // get view 78 * AclFileAttributeView view = file.getFileAttributeView(AclFileAttributeView.class); 79 * 80 * // create ACE to give "joe" read access 81 * AclEntry entry = AclEntry.newBuilder() 82 * .setType(AclEntryType.ALLOW) 83 * .setPrincipal(joe) 84 * .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES) 85 * .build(); 86 * 87 * // read ACL, insert ACE, re-write ACL 88 * List<AclEntry> acl = view.getAcl(); 89 * acl.add(0, entry); // insert before any DENY entries 90 * view.setAcl(acl); 91 * </pre> 92 * 93 * <h4> Dynamic Access </h4> 94 * <p> Where dynamic access to file attributes is required, the attributes 95 * supported by this attribute view are as follows: 96 * <blockquote> 97 * <table border="1" cellpadding="8"> 98 * <tr> 99 * <th> Name </th> 100 * <th> Type </th> 101 * </tr> 102 * <tr> 103 * <td> "acl" </td> 104 * <td> {@link List}<{@link AclEntry}> </td> 105 * </tr> 106 * <tr> 107 * <td> "owner" </td> 108 * <td> {@link UserPrincipal} </td> 109 * </tr> 110 * </table> 111 * </blockquote> 112 * 113 * <p> The {@link FileRef#getAttribute getAttribute} method may be used to read 114 * the ACL or owner attributes as if by invoking the {@link #getAcl getAcl} or 115 * {@link #getOwner getOwner} methods. 116 * 117 * <p> The {@link FileRef#setAttribute setAttribute} method may be used to 118 * update the ACL or owner attributes as if by invoking the {@link #setAcl setAcl} 119 * or {@link #setOwner setOwner} methods. 120 * 121 * <h4> Setting the ACL when creating a file </h4> 122 * 123 * <p> Implementations supporting this attribute view may also support setting 124 * the initial ACL when creating a file or directory. The initial ACL 125 * may be provided to methods such as {@link Path#createFile createFile} or {@link 126 * Path#createDirectory createDirectory} as an {@link FileAttribute} with {@link 127 * FileAttribute#name name} {@code "acl:acl"} and a {@link FileAttribute#value 128 * value} that is the list of {@code AclEntry} objects. 129 * 130 * <p> Where an implementation supports an ACL model that differs from the NFSv4 131 * defined ACL model then setting the initial ACL when creating the file must 132 * translate the ACL to the model supported by the file system. Methods that 133 * create a file should reject (by throwing {@link IOException IOException}) 134 * any attempt to create a file that would be less secure as a result of the 135 * translation. 136 * 137 * @since 1.7 138 * @see Attributes#getAcl 139 * @see Attributes#setAcl 140 */ 141 142 public interface AclFileAttributeView 143 extends FileOwnerAttributeView 144 { 145 /** 146 * Returns the name of the attribute view. Attribute views of this type 147 * have the name {@code "acl"}. 148 */ 149 @Override 150 String name(); 151 152 /** 153 * Reads the access control list. 154 * 155 * <p> When the file system uses an ACL model that differs from the NFSv4 156 * defined ACL model, then this method returns an ACL that is the translation 157 * of the ACL to the NFSv4 ACL model. 158 * 159 * <p> The returned list is modifiable so as to facilitate changes to the | 48 * <p> This class also extends {@code FileOwnerAttributeView} so as to define 49 * methods to get and set the file owner. 50 * 51 * <p> When a file system provides access to a set of {@link FileStore 52 * file-systems} that are not homogeneous then only some of the file systems may 53 * support ACLs. The {@link FileStore#supportsFileAttributeView 54 * supportsFileAttributeView} method can be used to test if a file system 55 * supports ACLs. 56 * 57 * <a name="interop"><h4>Interoperability</h4></a> 58 * 59 * RFC 3530 allows for special user identities to be used on platforms that 60 * support the POSIX defined access permissions. The special user identities 61 * are "{@code OWNER@}", "{@code GROUP@}", and "{@code EVERYONE@}". When both 62 * the {@code AclFileAttributeView} and the {@link PosixFileAttributeView} 63 * are supported then these special user identities may be included in ACL {@link 64 * AclEntry entries} that are read or written. The file system's {@link 65 * UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal} 66 * to represent these special identities by invoking the {@link 67 * UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName} 68 * method. </p> 69 * 70 * <p> <b>Usage Example:</b> 71 * Suppose we wish to add an entry to an existing ACL to grant "joe" access: 72 * <pre> 73 * // lookup "joe" 74 * UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService() 75 * .lookupPrincipalByName("joe"); 76 * 77 * // get view 78 * AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class); 79 * 80 * // create ACE to give "joe" read access 81 * AclEntry entry = AclEntry.newBuilder() 82 * .setType(AclEntryType.ALLOW) 83 * .setPrincipal(joe) 84 * .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES) 85 * .build(); 86 * 87 * // read ACL, insert ACE, re-write ACL 88 * List<AclEntry> acl = view.getAcl(); 89 * acl.add(0, entry); // insert before any DENY entries 90 * view.setAcl(acl); 91 * </pre> 92 * 93 * <h4> Dynamic Access </h4> 94 * <p> Where dynamic access to file attributes is required, the attributes 95 * supported by this attribute view are as follows: 96 * <blockquote> 97 * <table border="1" cellpadding="8"> 98 * <tr> 99 * <th> Name </th> 100 * <th> Type </th> 101 * </tr> 102 * <tr> 103 * <td> "acl" </td> 104 * <td> {@link List}<{@link AclEntry}> </td> 105 * </tr> 106 * <tr> 107 * <td> "owner" </td> 108 * <td> {@link UserPrincipal} </td> 109 * </tr> 110 * </table> 111 * </blockquote> 112 * 113 * <p> The {@link Files#getAttribute getAttribute} method may be used to read 114 * the ACL or owner attributes as if by invoking the {@link #getAcl getAcl} or 115 * {@link #getOwner getOwner} methods. 116 * 117 * <p> The {@link Files#setAttribute setAttribute} method may be used to 118 * update the ACL or owner attributes as if by invoking the {@link #setAcl setAcl} 119 * or {@link #setOwner setOwner} methods. 120 * 121 * <h4> Setting the ACL when creating a file </h4> 122 * 123 * <p> Implementations supporting this attribute view may also support setting 124 * the initial ACL when creating a file or directory. The initial ACL 125 * may be provided to methods such as {@link Files#createFile createFile} or {@link 126 * Files#createDirectory createDirectory} as an {@link FileAttribute} with {@link 127 * FileAttribute#name name} {@code "acl:acl"} and a {@link FileAttribute#value 128 * value} that is the list of {@code AclEntry} objects. 129 * 130 * <p> Where an implementation supports an ACL model that differs from the NFSv4 131 * defined ACL model then setting the initial ACL when creating the file must 132 * translate the ACL to the model supported by the file system. Methods that 133 * create a file should reject (by throwing {@link IOException IOException}) 134 * any attempt to create a file that would be less secure as a result of the 135 * translation. 136 * 137 * @since 1.7 138 */ 139 140 public interface AclFileAttributeView 141 extends FileOwnerAttributeView 142 { 143 /** 144 * Returns the name of the attribute view. Attribute views of this type 145 * have the name {@code "acl"}. 146 */ 147 @Override 148 String name(); 149 150 /** 151 * Reads the access control list. 152 * 153 * <p> When the file system uses an ACL model that differs from the NFSv4 154 * defined ACL model, then this method returns an ACL that is the translation 155 * of the ACL to the NFSv4 ACL model. 156 * 157 * <p> The returned list is modifiable so as to facilitate changes to the |