View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.security.acl;
27  
28  import java.util.Enumeration;
29  import java.security.Principal;
30  
31  /**
32   * This is the interface used for representing one entry in an Access
33   * Control List (ACL).<p>
34   *
35   * An ACL can be thought of as a data structure with multiple ACL entry
36   * objects. Each ACL entry object contains a set of permissions associated
37   * with a particular principal. (A principal represents an entity such as
38   * an individual user or a group). Additionally, each ACL entry is specified
39   * as being either positive or negative. If positive, the permissions are
40   * to be granted to the associated principal. If negative, the permissions
41   * are to be denied. Each principal can have at most one positive ACL entry
42   * and one negative entry; that is, multiple positive or negative ACL
43   * entries are not allowed for any principal.
44   *
45   * Note: ACL entries are by default positive. An entry becomes a
46   * negative entry only if the
47   * {@link #setNegativePermissions() setNegativePermissions}
48   * method is called on it.
49   *
50   * @see java.security.acl.Acl
51   *
52   * @author      Satish Dharmaraj
53   */
54  public interface AclEntry extends Cloneable {
55  
56      /**
57       * Specifies the principal for which permissions are granted or denied
58       * by this ACL entry. If a principal was already set for this ACL entry,
59       * false is returned, otherwise true is returned.
60       *
61       * @param user the principal to be set for this entry.
62       *
63       * @return true if the principal is set, false if there was
64       * already a principal set for this entry.
65       *
66       * @see #getPrincipal
67       */
68      public boolean setPrincipal(Principal user);
69  
70      /**
71       * Returns the principal for which permissions are granted or denied by
72       * this ACL entry. Returns null if there is no principal set for this
73       * entry yet.
74       *
75       * @return the principal associated with this entry.
76       *
77       * @see #setPrincipal
78       */
79      public Principal getPrincipal();
80  
81      /**
82       * Sets this ACL entry to be a negative one. That is, the associated
83       * principal (e.g., a user or a group) will be denied the permission set
84       * specified in the entry.
85       *
86       * Note: ACL entries are by default positive. An entry becomes a
87       * negative entry only if this {@code setNegativePermissions}
88       * method is called on it.
89       */
90      public void setNegativePermissions();
91  
92      /**
93       * Returns true if this is a negative ACL entry (one denying the
94       * associated principal the set of permissions in the entry), false
95       * otherwise.
96       *
97       * @return true if this is a negative ACL entry, false if it's not.
98       */
99      public boolean isNegative();
100 
101     /**
102      * Adds the specified permission to this ACL entry. Note: An entry can
103      * have multiple permissions.
104      *
105      * @param permission the permission to be associated with
106      * the principal in this entry.
107      *
108      * @return true if the permission was added, false if the
109      * permission was already part of this entry's permission set.
110      */
111     public boolean addPermission(Permission permission);
112 
113     /**
114      * Removes the specified permission from this ACL entry.
115      *
116      * @param permission the permission to be removed from this entry.
117      *
118      * @return true if the permission is removed, false if the
119      * permission was not part of this entry's permission set.
120      */
121     public boolean removePermission(Permission permission);
122 
123     /**
124      * Checks if the specified permission is part of the
125      * permission set in this entry.
126      *
127      * @param permission the permission to be checked for.
128      *
129      * @return true if the permission is part of the
130      * permission set in this entry, false otherwise.
131      */
132     public boolean checkPermission(Permission permission);
133 
134     /**
135      * Returns an enumeration of the permissions in this ACL entry.
136      *
137      * @return an enumeration of the permissions in this ACL entry.
138      */
139     public Enumeration<Permission> permissions();
140 
141     /**
142      * Returns a string representation of the contents of this ACL entry.
143      *
144      * @return a string representation of the contents.
145      */
146     public String toString();
147 
148     /**
149      * Clones this ACL entry.
150      *
151      * @return a clone of this ACL entry.
152      */
153     public Object clone();
154 }