1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.security.acl;
19
20import java.security.Principal;
21import java.util.Enumeration;
22
23/**
24 * The <i>Access Control List</i> (<b>ACL</b>) interface definition.
25 * <p>
26 * An ACL is a set of {@link AclEntry} objects.
27 * <p>
28 * An {@code AclEntry} is a list of {@link Permission}s that are granted
29 * (<i>positive</i>) or denied
30 * (<i>negative</i>) to a {@link Principal}.
31 * <p>
32 * An {@code Acl} has a list of owners ({@link Owner}) which are principals as
33 * well {@code Principal}. Only those principals which are the {@code Acl}'s
34 * owners are allowed to modify the {@code
35 * Acl}.
36 * <p>
37 * The <i>ACL</i> has to conform to the following rules:
38 * <ul>
39 * <li>For each {@code Principal} there can be only one <i>positive</i> and one
40 * <i>negative</i> {@code AclEntry}.</li>
41 * <li>If the two {@code AclEntry}'s (<i>positive</i> and <i>negative</i>) for a
42 * specific {@code Principal} grant and deny the same {@code Permission} to that
43 * {@code Principal}, then that {@code Permission} is treated as
44 * neither granted nor denied to that {@code Principal}.</li>
45 * <li>Permissions associated with an individual {@code Principal} always
46 * override permissions of the group(s) to which the individual belongs.</li>
47 * <li>If there is no {@code AclEntry} associated with a specific {@code
48 * Principal}, then it is interpreted as an empty list of permissions.</li>
49 * </ul>
50 */
51public interface Acl extends Owner {
52
53    /**
54     * Sets the name of this <i>ACL</i> instance.
55     *
56     * @param caller
57     *            the invoking {@code Principal}.
58     * @param name
59     *            the name to be set.
60     * @throws NotOwnerException
61     *             if the invoking {@code Principal} is not an owner of this
62     *             <i>ACL</i>.
63     */
64    void setName(Principal caller, String name) throws NotOwnerException;
65
66    /**
67     * Returns the name of this <i>ACL</i> instance.
68     *
69     * @return the name of this <i>ACL</i> instance.
70     */
71    String getName();
72
73    /**
74     * Adds an {@code AclEntry} to this <i>ACL</i> instance.
75     * <p>
76     * If the <i>ACL</i> already has an {@code AclEntry} of the same type (<i>
77     * positive</i> or <i>negative</i>) and principal, then the new entry is not added.
78     *
79     * @param caller
80     *            the invoking {@code Principal}.
81     * @param entry
82     *            the ACL entry to add.
83     * @return {@code true} if the entry is added, {@code false} if there is
84     *             already an entry of the same type for the same principal
85     * @throws NotOwnerException
86     *             if the invoking {@code Principal} is not an owner of this
87     *             <i>ACL</i>.
88     */
89    boolean addEntry(Principal caller, AclEntry entry) throws NotOwnerException;
90
91    /**
92     * Removes an {@code AclEntry} from this <i>ACL</i> instance.
93     *
94     * @param caller
95     *            the invoking {@code Principal}.
96     * @param entry
97     *            the ACL entry to remove.
98     * @return {@code true} if the entry is removed, {@code false} if the entry
99     *            is not in this <i>ACL</i>.
100     * @throws NotOwnerException
101     *             if the invoking {@code Principal} is not an owner of this
102     *             <i>ACL</i>.
103     */
104    boolean removeEntry(Principal caller, AclEntry entry)
105                throws NotOwnerException;
106
107    /**
108     * Returns the set of allowed permissions for the specified {@code
109     * Principal}.
110     * <p>
111     * If the specified principal has no entry in this ACL, an empty set is
112     * returned.
113     * <p>
114     * The allowed permissions are collected according to the following rules:
115     * <ul>
116     * <li>The two permission lists (<i>positive</i> and <i>negative</i>) of the
117     * principal's groups ({@link Group}) are collected. The positive (granted)
118     * permissions are the union of all group's positive permissions that the
119     * principal belongs to, the negative (denied) permissions are the union of
120     * all group's negative permissions that the principal belongs to. If a
121     * specific permission is in both the positive and the negative list, it is
122     * removed from both lists.</li>
123     * <li>The individual permissions (<i>positive</i> and <i>negative</i>) of
124     * the principal override the group permissions. The positive individual
125     * permissions override the group's negative permissions and the negative
126     * individual permissions override the grpup's positive permissions.</li>
127     * </ul>
128     *
129     * @param user
130     *            the principal to get the allowed permissions for.
131     * @return the set of allowed permissions for the specified principal.
132     */
133    Enumeration<Permission> getPermissions(Principal user);
134
135    /**
136     * Returns an {@code Enumeration} of the {@code AclEntry} of this
137     * <i>ACL</i>.
138     *
139     * @return an {@code Enumeration} of the {@code AclEntry} of this
140     *         <i>ACL</i>.
141     */
142    Enumeration<AclEntry> entries();
143
144    /**
145     * Checks whether the specified principal is granted the specified
146     * permission.
147     * <p>
148     * The list of granted permissions is determined according to the rules
149     * specified by {@code getPermissions}.
150     *
151     * @param principal
152     *            the principal the check the permissions for.
153     * @param permission
154     *            the permission to check for the principal.
155     * @return {@code true} if the principal is granted the permission,
156     *            otherwise {@code false}.
157     * @see #getPermissions(Principal)
158     */
159    boolean checkPermission(Principal principal, Permission permission);
160
161    /**
162     * Returns the string representation of this ACL.
163     *
164     * @return the string representation of this ACL.
165     */
166    String toString();
167}
168