/*
* 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();
}