KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > useradmin > Group


1 /*
2  * $Header: /cvshome/build/org.osgi.service.useradmin/src/org/osgi/service/useradmin/Group.java,v 1.8 2006/06/16 16:31:41 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.service.useradmin;
19
20 /**
21  * A named grouping of roles (<code>Role</code> objects).
22  * <p>
23  * Whether or not a given <code>Authorization</code> context implies a
24  * <code>Group</code> object depends on the members of that <code>Group</code>
25  * object.
26  * <p>
27  * A <code>Group</code> object can have two kinds of members: <i>basic </i> and
28  * <i>required </i>. A <code>Group</code> object is implied by an
29  * <code>Authorization</code> context if all of its required members are implied
30  * and at least one of its basic members is implied.
31  * <p>
32  * A <code>Group</code> object must contain at least one basic member in order to
33  * be implied. In other words, a <code>Group</code> object without any basic
34  * member roles is never implied by any <code>Authorization</code> context.
35  * <p>
36  * A <code>User</code> object always implies itself.
37  * <p>
38  * No loop detection is performed when adding members to <code>Group</code>
39  * objects, which means that it is possible to create circular implications.
40  * Loop detection is instead done when roles are checked. The semantics is that
41  * if a role depends on itself (i.e., there is an implication loop), the role is
42  * not implied.
43  * <p>
44  * The rule that a <code>Group</code> object must have at least one basic member
45  * to be implied is motivated by the following example:
46  *
47  * <pre>
48  *
49  * group foo
50  * required members: marketing
51  * basic members: alice, bob
52  *
53  * </pre>
54  *
55  * Privileged operations that require membership in "foo" can be performed only
56  * by "alice" and "bob", who are in marketing.
57  * <p>
58  * If "alice" and "bob" ever transfer to a different department, anybody in
59  * marketing will be able to assume the "foo" role, which certainly must be
60  * prevented. Requiring that "foo" (or any <code>Group</code> object for that
61  * matter) must have at least one basic member accomplishes that.
62  * <p>
63  * However, this would make it impossible for a <code>Group</code> object to be
64  * implied by just its required members. An example where this implication might
65  * be useful is the following declaration: "Any citizen who is an adult is
66  * allowed to vote." An intuitive configuration of "voter" would be:
67  *
68  * <pre>
69  *
70  * group voter
71  * required members: citizen, adult
72  * basic members:
73  *
74  * </pre>
75  *
76  * However, according to the above rule, the "voter" role could never be assumed
77  * by anybody, since it lacks any basic members. In order to address this issue
78  * a predefined role named "user.anyone" can be specified, which is always
79  * implied. The desired implication of the "voter" group can then be achieved by
80  * specifying "user.anyone" as its basic member, as follows:
81  *
82  * <pre>
83  *
84  * group voter
85  * required members: citizen, adult
86  * basic members: user.anyone
87  *
88  * </pre>
89  *
90  * @version $Revision: 1.8 $
91  */
92 public interface Group extends User {
93     /**
94      * Adds the specified <code>Role</code> object as a basic member to this
95      * <code>Group</code> object.
96      *
97      * @param role The role to add as a basic member.
98      *
99      * @return <code>true</code> if the given role could be added as a basic
100      * member, and <code>false</code> if this <code>Group</code> object
101      * already contains a <code>Role</code> object whose name matches that
102      * of the specified role.
103      *
104      * @throws SecurityException If a security manager exists and the caller
105      * does not have the <code>UserAdminPermission</code> with name
106      * <code>admin</code>.
107      */
108     public boolean addMember(Role role);
109
110     /**
111      * Adds the specified <code>Role</code> object as a required member to this
112      * <code>Group</code> object.
113      *
114      * @param role The <code>Role</code> object to add as a required member.
115      *
116      * @return <code>true</code> if the given <code>Role</code> object could be
117      * added as a required member, and <code>false</code> if this
118      * <code>Group</code> object already contains a <code>Role</code> object
119      * whose name matches that of the specified role.
120      *
121      * @throws SecurityException If a security manager exists and the caller
122      * does not have the <code>UserAdminPermission</code> with name
123      * <code>admin</code>.
124      */
125     public boolean addRequiredMember(Role role);
126
127     /**
128      * Removes the specified <code>Role</code> object from this <code>Group</code>
129      * object.
130      *
131      * @param role The <code>Role</code> object to remove from this <code>Group</code>
132      * object.
133      *
134      * @return <code>true</code> if the <code>Role</code> object could be removed,
135      * otherwise <code>false</code>.
136      *
137      * @throws SecurityException If a security manager exists and the caller
138      * does not have the <code>UserAdminPermission</code> with name
139      * <code>admin</code>.
140      */
141     public boolean removeMember(Role role);
142
143     /**
144      * Gets the basic members of this <code>Group</code> object.
145      *
146      * @return The basic members of this <code>Group</code> object, or
147      * <code>null</code> if this <code>Group</code> object does not contain
148      * any basic members.
149      */
150     public Role[] getMembers();
151
152     /**
153      * Gets the required members of this <code>Group</code> object.
154      *
155      * @return The required members of this <code>Group</code> object, or
156      * <code>null</code> if this <code>Group</code> object does not contain
157      * any required members.
158      */
159     public Role[] getRequiredMembers();
160 }
161
Popular Tags