/*

 * Copyright 2007-2009 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.nio.file.attribute;

import java.nio.file.*;

import java.util.List;

import java.io.IOException;

/**

 * A file attribute view that supports reading or updating a file's Access

 * Control Lists (ACL) or file owner attributes.

 *

 * <p> 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 <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC&nbsp;3530:

 * Network File System (NFS) version 4 Protocol</i></a>. This file attribute view

 * is intended for file system implementations that support the NFSv4 ACL model

 * or have a <em>well-defined</em> 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.

 *

 * <p> This class also extends {@code FileOwnerAttributeView} so as to define

 * methods to get and set the file owner.

 *

 * <p> 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.

 *

 * <a name="interop"><h4>Interoperability</h4></a>

 *

 * 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.

 *

 * <p> <b>Usage Example:</b>

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

 * <pre>

 *     // 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&gt acl = view.getAcl();

 *     acl.add(0, entry);   // insert before any DENY entries

 *     view.setAcl(acl);

 * </pre>

 *

 * <h4> Dynamic Access </h4>

 * <p> Where dynamic access to file attributes is required, the attributes

 * supported by this attribute view are as follows:

 * <blockquote>

 * <table border="1" cellpadding="8">

 *   <tr>

 *     <th> Name </th>

 *     <th> Type </th>

 *   </tr>

 *   <tr>

 *     <td> "acl" </td>

 *     <td> {@link List}&lt;{@link AclEntry}&gt; </td>

 *   </tr>

 *   <tr>

 *     <td> "owner" </td>

 *     <td> {@link UserPrincipal} </td>

 *   </tr>

 * </table>

 * </blockquote>

 *

 * <p> 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.

 *

 * <p> 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.

 *

 * <h4> Setting the ACL when creating a file </h4>

 *

 * <p> 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.

 *

 * <p> 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.

     *

     * <p> 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.

     *

     * <p> 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}<tt>("accessUserInformation")</tt>

     *          or its {@link SecurityManager#checkRead(String) checkRead} method

     *          denies read access to the file.

     */

    List<AclEntry> getAcl() throws IOException;

    /**

     * Updates (replace) the access control list.

     *

     * <p> 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.

     *

     * <p> 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.

     *

     * <p> 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}<tt>("accessUserInformation")</tt>

     *          or its {@link SecurityManager#checkWrite(String) checkWrite}

     *          method denies write access to the file.

     */

    void setAcl(List<AclEntry> acl) throws IOException;

}