java.security.acl.Acl Maven / Gradle / Ivy

/*
 *  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 Access Control List (ACL) interface definition.
 * 
 * An ACL is a set of {@link AclEntry} objects.
 * 

 * An {@code AclEntry} is a list of {@link Permission}s that are granted
 * (positive) or denied
 * (negative) to a {@link Principal}.
 * 

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

 * The ACL has to conform to the following rules:
 * 

 * For each {@code Principal} there can be only one positive and one
 * negative {@code AclEntry}.
 * If the two {@code AclEntry}'s (positive and negative) 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}.
 * Permissions associated with an individual {@code Principal} always
 * override permissions of the group(s) to which the individual belongs.
 * If there is no {@code AclEntry} associated with a specific {@code
 * Principal}, then it is interpreted as an empty list of permissions.
 * 
 */
public interface Acl extends Owner {

    /**
     * Sets the name of this ACL 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
     *             ACL.
     */
    void setName(Principal caller, String name) throws NotOwnerException;

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

    /**
     * Adds an {@code AclEntry} to this ACL instance.
     * 
     * If the ACL already has an {@code AclEntry} of the same type (
     * positive or negative) 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
     *             ACL.
     */
    boolean addEntry(Principal caller, AclEntry entry) throws NotOwnerException;

    /**
     * Removes an {@code AclEntry} from this ACL 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 ACL.
     * @throws NotOwnerException
     *             if the invoking {@code Principal} is not an owner of this
     *             ACL.
     */
    boolean removeEntry(Principal caller, AclEntry entry)
                throws NotOwnerException;

    /**
     * Returns the set of allowed permissions for the specified {@code
     * Principal}.
     * 

     * If the specified principal has no entry in this ACL, an empty set is
     * returned.
     * 

     * The allowed permissions are collected according to the following rules:
     * 

     * The two permission lists (positive and negative) 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.
     * The individual permissions (positive and negative) 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.
     * 
     *
     * @param user
     *            the principal to get the allowed permissions for.
     * @return the set of allowed permissions for the specified principal.
     */
    Enumeration getPermissions(Principal user);

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

    /**
     * Checks whether the specified principal is granted the specified
     * permission.
     * 
     * 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();
}