001 /*
002 * Copyright (c) OSGi Alliance (2001, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.useradmin;
017
018 /**
019 * A named grouping of roles (<code>Role</code> objects).
020 * <p>
021 * Whether or not a given <code>Authorization</code> context implies a
022 * <code>Group</code> object depends on the members of that <code>Group</code>
023 * object.
024 * <p>
025 * A <code>Group</code> object can have two kinds of members: <i>basic </i> and
026 * <i>required </i>. A <code>Group</code> object is implied by an
027 * <code>Authorization</code> context if all of its required members are implied
028 * and at least one of its basic members is implied.
029 * <p>
030 * A <code>Group</code> object must contain at least one basic member in order to
031 * be implied. In other words, a <code>Group</code> object without any basic
032 * member roles is never implied by any <code>Authorization</code> context.
033 * <p>
034 * A <code>User</code> object always implies itself.
035 * <p>
036 * No loop detection is performed when adding members to <code>Group</code>
037 * objects, which means that it is possible to create circular implications.
038 * Loop detection is instead done when roles are checked. The semantics is that
039 * if a role depends on itself (i.e., there is an implication loop), the role is
040 * not implied.
041 * <p>
042 * The rule that a <code>Group</code> object must have at least one basic member
043 * to be implied is motivated by the following example:
044 *
045 * <pre>
046 *
047 * group foo
048 * required members: marketing
049 * basic members: alice, bob
050 *
051 * </pre>
052 *
053 * Privileged operations that require membership in "foo" can be performed only
054 * by "alice" and "bob", who are in marketing.
055 * <p>
056 * If "alice" and "bob" ever transfer to a different department, anybody in
057 * marketing will be able to assume the "foo" role, which certainly must be
058 * prevented. Requiring that "foo" (or any <code>Group</code> object for that
059 * matter) must have at least one basic member accomplishes that.
060 * <p>
061 * However, this would make it impossible for a <code>Group</code> object to be
062 * implied by just its required members. An example where this implication might
063 * be useful is the following declaration: "Any citizen who is an adult is
064 * allowed to vote." An intuitive configuration of "voter" would be:
065 *
066 * <pre>
067 *
068 * group voter
069 * required members: citizen, adult
070 * basic members:
071 *
072 * </pre>
073 *
074 * However, according to the above rule, the "voter" role could never be assumed
075 * by anybody, since it lacks any basic members. In order to address this issue
076 * a predefined role named "user.anyone" can be specified, which is always
077 * implied. The desired implication of the "voter" group can then be achieved by
078 * specifying "user.anyone" as its basic member, as follows:
079 *
080 * <pre>
081 *
082 * group voter
083 * required members: citizen, adult
084 * basic members: user.anyone
085 *
086 * </pre>
087 *
088 * @version $Revision: 5673 $
089 */
090 public interface Group extends User {
091 /**
092 * Adds the specified <code>Role</code> object as a basic member to this
093 * <code>Group</code> object.
094 *
095 * @param role The role to add as a basic member.
096 *
097 * @return <code>true</code> if the given role could be added as a basic
098 * member, and <code>false</code> if this <code>Group</code> object
099 * already contains a <code>Role</code> object whose name matches that
100 * of the specified role.
101 *
102 * @throws SecurityException If a security manager exists and the caller
103 * does not have the <code>UserAdminPermission</code> with name
104 * <code>admin</code>.
105 */
106 public boolean addMember(Role role);
107
108 /**
109 * Adds the specified <code>Role</code> object as a required member to this
110 * <code>Group</code> object.
111 *
112 * @param role The <code>Role</code> object to add as a required member.
113 *
114 * @return <code>true</code> if the given <code>Role</code> object could be
115 * added as a required member, and <code>false</code> if this
116 * <code>Group</code> object already contains a <code>Role</code> object
117 * whose name matches that of the specified role.
118 *
119 * @throws SecurityException If a security manager exists and the caller
120 * does not have the <code>UserAdminPermission</code> with name
121 * <code>admin</code>.
122 */
123 public boolean addRequiredMember(Role role);
124
125 /**
126 * Removes the specified <code>Role</code> object from this <code>Group</code>
127 * object.
128 *
129 * @param role The <code>Role</code> object to remove from this <code>Group</code>
130 * object.
131 *
132 * @return <code>true</code> if the <code>Role</code> object could be removed,
133 * otherwise <code>false</code>.
134 *
135 * @throws SecurityException If a security manager exists and the caller
136 * does not have the <code>UserAdminPermission</code> with name
137 * <code>admin</code>.
138 */
139 public boolean removeMember(Role role);
140
141 /**
142 * Gets the basic members of this <code>Group</code> object.
143 *
144 * @return The basic members of this <code>Group</code> object, or
145 * <code>null</code> if this <code>Group</code> object does not contain
146 * any basic members.
147 */
148 public Role[] getMembers();
149
150 /**
151 * Gets the required members of this <code>Group</code> object.
152 *
153 * @return The required members of this <code>Group</code> object, or
154 * <code>null</code> if this <code>Group</code> object does not contain
155 * any required members.
156 */
157 public Role[] getRequiredMembers();
158 }