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  ;
11  import java.security.Principal  ;
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   {
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   caller, String   name)
90        throws NotOwnerException  ;
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   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   caller, AclEntry   entry)
123       throws NotOwnerException  ;
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   caller, AclEntry   entry)
139           throws NotOwnerException  ;
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  <Permission  > getPermissions(Principal   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  <AclEntry  > 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   principal, Permission   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   toString();
224 }
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
240 
241
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags