java.security.acl.Acl Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* 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();
}