KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > security > acl > Acl


1 /*
2  * @(#)Acl.java 1.23 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.security.acl;
9
10 import java.util.Enumeration JavaDoc;
11 import java.security.Principal JavaDoc;
12
13 /**
14  * Interface representing an Access Control List (ACL). An Access
15  * Control List is a data structure used to guard access to
16  * resources.<p>
17  *
18  * An ACL can be thought of as a data structure with multiple ACL
19  * entries. Each ACL entry, of interface type AclEntry, contains a
20  * set of permissions associated with a particular principal. (A
21  * principal represents an entity such as an individual user or a
22  * group). Additionally, each ACL entry is specified as being either
23  * positive or negative. If positive, the permissions are to be
24  * granted to the associated principal. If negative, the permissions
25  * are to be denied.<p>
26  *
27  * The ACL Entries in each ACL observe the following rules:<p>
28  *
29  * <ul> <li>Each principal can have at most one positive ACL entry and
30  * one negative entry; that is, multiple positive or negative ACL
31  * entries are not allowed for any principal. Each entry specifies
32  * the set of permissions that are to be granted (if positive) or
33  * denied (if negative). <p>
34  *
35  * <li>If there is no entry for a particular principal, then the
36  * principal is considered to have a null (empty) permission set.<p>
37  *
38  * <li>If there is a positive entry that grants a principal a
39  * particular permission, and a negative entry that denies the
40  * principal the same permission, the result is as though the
41  * permission was never granted or denied. <p>
42  *
43  * <li>Individual permissions always override permissions of the
44  * group(s) to which the individual belongs. That is, individual
45  * negative permissions (specific denial of permissions) override the
46  * groups' positive permissions. And individual positive permissions
47  * override the groups' negative permissions.<p>
48  *
49  * </ul>
50  *
51  * The <code> java.security.acl </code> package provides the
52  * interfaces to the ACL and related data structures (ACL entries,
53  * groups, permissions, etc.), and the <code> sun.security.acl </code>
54  * classes provide a default implementation of the interfaces. For
55  * example, <code> java.security.acl.Acl </code> provides the
56  * interface to an ACL and the <code> sun.security.acl.AclImpl </code>
57  * class provides the default implementation of the interface.<p>
58  *
59  * The <code> java.security.acl.Acl </code> interface extends the
60  * <code> java.security.acl.Owner </code> interface. The Owner
61  * interface is used to maintain a list of owners for each ACL. Only
62  * owners are allowed to modify an ACL. For example, only an owner can
63  * call the ACL's <code>addEntry</code> method to add a new ACL entry
64  * to the ACL.
65  *
66  * @see java.security.acl.AclEntry
67  * @see java.security.acl.Owner
68  * @see java.security.acl.Acl#getPermissions
69  *
70  * @version 1.23, 04/05/05
71  * @author Satish Dharmaraj
72  */

73
74 public interface Acl extends Owner JavaDoc {
75
76     /**
77      * Sets the name of this ACL.
78      *
79      * @param caller the principal invoking this method. It must be an
80      * owner of this ACL.
81      *
82      * @param name the name to be given to this ACL.
83      *
84      * @exception NotOwnerException if the caller principal
85      * is not an owner of this ACL.
86      *
87      * @see #getName
88      */

89     public void setName(Principal JavaDoc caller, String JavaDoc name)
90       throws NotOwnerException JavaDoc;
91
92     /**
93      * Returns the name of this ACL.
94      *
95      * @return the name of this ACL.
96      *
97      * @see #setName
98      */

99     public String JavaDoc getName();
100
101     /**
102      * Adds an ACL entry to this ACL. An entry associates a principal
103      * (e.g., an individual or a group) with a set of
104      * permissions. Each principal can have at most one positive ACL
105      * entry (specifying permissions to be granted to the principal)
106      * and one negative ACL entry (specifying permissions to be
107      * denied). If there is already an ACL entry of the same type
108      * (negative or positive) already in the ACL, false is returned.
109      *
110      * @param caller the principal invoking this method. It must be an
111      * owner of this ACL.
112      *
113      * @param entry the ACL entry to be added to this ACL.
114      *
115      * @return true on success, false if an entry of the same type
116      * (positive or negative) for the same principal is already
117      * present in this ACL.
118      *
119      * @exception NotOwnerException if the caller principal
120      * is not an owner of this ACL.
121      */

122     public boolean addEntry(Principal JavaDoc caller, AclEntry JavaDoc entry)
123       throws NotOwnerException JavaDoc;
124
125     /**
126      * Removes an ACL entry from this ACL.
127      *
128      * @param caller the principal invoking this method. It must be an
129      * owner of this ACL.
130      *
131      * @param entry the ACL entry to be removed from this ACL.
132      *
133      * @return true on success, false if the entry is not part of this ACL.
134      *
135      * @exception NotOwnerException if the caller principal is not
136      * an owner of this Acl.
137      */

138     public boolean removeEntry(Principal JavaDoc caller, AclEntry JavaDoc entry)
139           throws NotOwnerException JavaDoc;
140
141     /**
142      * Returns an enumeration for the set of allowed permissions for the
143      * specified principal (representing an entity such as an individual or
144      * a group). This set of allowed permissions is calculated as
145      * follows:<p>
146      *
147      * <ul>
148      *
149      * <li>If there is no entry in this Access Control List for the
150      * specified principal, an empty permission set is returned.<p>
151      *
152      * <li>Otherwise, the principal's group permission sets are determined.
153      * (A principal can belong to one or more groups, where a group is a
154      * group of principals, represented by the Group interface.)
155      * The group positive permission set is the union of all
156      * the positive permissions of each group that the principal belongs to.
157      * The group negative permission set is the union of all
158      * the negative permissions of each group that the principal belongs to.
159      * If there is a specific permission that occurs in both
160      * the positive permission set and the negative permission set,
161      * it is removed from both.<p>
162      *
163      * The individual positive and negative permission sets are also
164      * determined. The positive permission set contains the permissions
165      * specified in the positive ACL entry (if any) for the principal.
166      * Similarly, the negative permission set contains the permissions
167      * specified in the negative ACL entry (if any) for the principal.
168      * The individual positive (or negative) permission set is considered
169      * to be null if there is not a positive (negative) ACL entry for the
170      * principal in this ACL.<p>
171      *
172      * The set of permissions granted to the principal is then calculated
173      * using the simple rule that individual permissions always override
174      * the group permissions. That is, the principal's individual negative
175      * permission set (specific denial of permissions) overrides the group
176      * positive permission set, and the principal's individual positive
177      * permission set overrides the group negative permission set.
178      *
179      * </ul>
180      *
181      * @param user the principal whose permission set is to be returned.
182      *
183      * @return the permission set specifying the permissions the principal
184      * is allowed.
185      */

186     public Enumeration JavaDoc<Permission JavaDoc> getPermissions(Principal JavaDoc user);
187
188     /**
189      * Returns an enumeration of the entries in this ACL. Each element in
190      * the enumeration is of type AclEntry.
191      *
192      * @return an enumeration of the entries in this ACL.
193      */

194     public Enumeration JavaDoc<AclEntry JavaDoc> entries();
195
196     /**
197      * Checks whether or not the specified principal has the specified
198      * permission. If it does, true is returned, otherwise false is returned.
199      *
200      * More specifically, this method checks whether the passed permission
201      * is a member of the allowed permission set of the specified principal.
202      * The allowed permission set is determined by the same algorithm as is
203      * used by the <code>getPermissions</code> method.
204      *
205      * @param principal the principal, assumed to be a valid authenticated
206      * Principal.
207      *
208      * @param permission the permission to be checked for.
209      *
210      * @return true if the principal has the specified permission, false
211      * otherwise.
212      *
213      * @see #getPermissions
214      */

215     public boolean checkPermission(Principal JavaDoc principal, Permission JavaDoc permission);
216
217     /**
218      * Returns a string representation of the
219      * ACL contents.
220      *
221      * @return a string representation of the ACL contents.
222      */

223     public String JavaDoc toString();
224 }
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
Popular Tags