/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package java.security.acl;

import java.security.Principal;
import java.util.Enumeration;

/**
 * The <i>Access Control List</i> (<b>ACL</b>) interface definition.
 * <p>
 * An ACL is a set of {@link AclEntry} objects.
 * <p>
 * An {@code AclEntry} is a list of {@link Permission}s that are granted
 * (<i>positive</i>) or denied
 * (<i>negative</i>) to a {@link Principal}.
 * <p>
 * An {@code Acl} has a list of owners ({@link Owner}) which are principals as
 * well {@code Principal}. Only those principals which are the {@code Acl}'s
 * owners are allowed to modify the {@code
 * Acl}.
 * <p>
 * The <i>ACL</i> has to conform to the following rules:
 * <ul>
 * <li>For each {@code Principal} there can be only one <i>positive</i> and one
 * <i>negative</i> {@code AclEntry}.</li>
 * <li>If the two {@code AclEntry}'s (<i>positive</i> and <i>negative</i>) for a
 * specific {@code Principal} grant and deny the same {@code Permission} to that
 * {@code Principal}, then that {@code Permission} is treated as
 * neither granted nor denied to that {@code Principal}.</li>
 * <li>Permissions associated with an individual {@code Principal} always
 * override permissions of the group(s) to which the individual belongs.</li>
 * <li>If there is no {@code AclEntry} associated with a specific {@code
 * Principal}, then it is interpreted as an empty list of permissions.</li>
 * </ul>
 */
public interface Acl extends Owner {

    /**
     * Sets the name of this <i>ACL</i> instance.
     *
     * @param caller
     *            the invoking {@code Principal}.
     * @param name
     *            the name to be set.
     * @throws NotOwnerException
     *             if the invoking {@code Principal} is not an owner of this
     *             <i>ACL</i>.
     */
    void setName(Principal caller, String name) throws NotOwnerException;

    /**
     * Returns the name of this <i>ACL</i> instance.
     *
     * @return the name of this <i>ACL</i> instance.
     */
    String getName();

    /**
     * Adds an {@code AclEntry} to this <i>ACL</i> instance.
     * <p>
     * If the <i>ACL</i> already has an {@code AclEntry} of the same type (<i>
     * positive</i> or <i>negative</i>) and principal, then the new entry is not added.
     *
     * @param caller
     *            the invoking {@code Principal}.
     * @param entry
     *            the ACL entry to add.
     * @return {@code true} if the entry is added, {@code false} if there is
     *             already an entry of the same type for the same principal
     * @throws NotOwnerException
     *             if the invoking {@code Principal} is not an owner of this
     *             <i>ACL</i>.
     */
    boolean addEntry(Principal caller, AclEntry entry) throws NotOwnerException;

    /**
     * Removes an {@code AclEntry} from this <i>ACL</i> instance.
     *
     * @param caller
     *            the invoking {@code Principal}.
     * @param entry
     *            the ACL entry to remove.
     * @return {@code true} if the entry is removed, {@code false} if the entry
     *            is not in this <i>ACL</i>.
     * @throws NotOwnerException
     *             if the invoking {@code Principal} is not an owner of this
     *             <i>ACL</i>.
     */
    boolean removeEntry(Principal caller, AclEntry entry)
                throws NotOwnerException;

    /**
     * Returns the set of allowed permissions for the specified {@code
     * Principal}.
     * <p>
     * If the specified principal has no entry in this ACL, an empty set is
     * returned.
     * <p>
     * The allowed permissions are collected according to the following rules:
     * <ul>
     * <li>The two permission lists (<i>positive</i> and <i>negative</i>) of the
     * principal's groups ({@link Group}) are collected. The positive (granted)
     * permissions are the union of all group's positive permissions that the
     * principal belongs to, the negative (denied) permissions are the union of
     * all group's negative permissions that the principal belongs to. If a
     * specific permission is in both the positive and the negative list, it is
     * removed from both lists.</li>
     * <li>The individual permissions (<i>positive</i> and <i>negative</i>) of
     * the principal override the group permissions. The positive individual
     * permissions override the group's negative permissions and the negative
     * individual permissions override the grpup's positive permissions.</li>
     * </ul>
     *
     * @param user
     *            the principal to get the allowed permissions for.
     * @return the set of allowed permissions for the specified principal.
     */
    Enumeration<Permission> getPermissions(Principal user);

    /**
     * Returns an {@code Enumeration} of the {@code AclEntry} of this
     * <i>ACL</i>.
     *
     * @return an {@code Enumeration} of the {@code AclEntry} of this
     *         <i>ACL</i>.
     */
    Enumeration<AclEntry> entries();

    /**
     * Checks whether the specified principal is granted the specified
     * permission.
     * <p>
     * The list of granted permissions is determined according to the rules
     * specified by {@code getPermissions}.
     *
     * @param principal
     *            the principal the check the permissions for.
     * @param permission
     *            the permission to check for the principal.
     * @return {@code true} if the principal is granted the permission,
     *            otherwise {@code false}.
     * @see #getPermissions(Principal)
     */
    boolean checkPermission(Principal principal, Permission permission);

    /**
     * Returns the string representation of this ACL.
     *
     * @return the string representation of this ACL.
     */
    String toString();
}