001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/authz/tags/sakai_2-4-1/authz-api/api/src/java/org/sakaiproject/authz/api/AuthzGroup.java $
003: * $Id: AuthzGroup.java 7063 2006-03-27 17:46:13Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.authz.api;
021:
022: import java.io.Serializable;
023: import java.util.Set;
024:
025: import org.sakaiproject.entity.api.Edit;
026: import org.sakaiproject.time.api.Time;
027: import org.sakaiproject.user.api.User;
028:
029: /**
030: * <p>
031: * AuthzGroup is a authorization group; a group of users, each with a role, and a set of permissions of functions made to each role.
032: * </p>
033: * <p>
034: * AuthzGroups can related to Entities in Sakai; The entity reference forms the AuthzGroup id.
035: * </p>
036: * <p>
037: * Special AuthzGroups not related to an entity have ids that begin with a "!".
038: * </p>
039: */
040: public interface AuthzGroup extends Edit, Comparable, Serializable {
041: /**
042: * Add a member to the AuthzGroup.
043: *
044: * @param userId
045: * The user.
046: * @param role
047: * The role name.
048: * @param active
049: * The active flag.
050: * @param provided
051: * If true, from an external provider.
052: */
053: void addMember(String userId, String roleId, boolean active,
054: boolean provided);
055:
056: /**
057: * Create a new Role within this AuthzGroup.
058: *
059: * @param id
060: * The role id.
061: * @return the new Role.
062: * @exception IdUsedException
063: * if the id is already a Role in this AuthzGroup.
064: */
065: Role addRole(String id) throws RoleAlreadyDefinedException;
066:
067: /**
068: * Create a new Role within this AuthzGroup, as a copy of this other role
069: *
070: * @param id
071: * The role id.
072: * @param other
073: * The role to copy.
074: * @return the new Role.
075: * @exception IdUsedException
076: * if the id is already a Role in this AuthzGroup.
077: */
078: Role addRole(String id, Role other)
079: throws RoleAlreadyDefinedException;
080:
081: /**
082: * @return the user who created this.
083: */
084: User getCreatedBy();
085:
086: /**
087: * @return the time created.
088: */
089: Time getCreatedTime();
090:
091: /**
092: * @return a description of the item this realm applies to.
093: */
094: String getDescription();
095:
096: /**
097: * Access the name of the role to use for giving a user membership with "maintain" access.
098: *
099: * @return The name of the "maintain" role.
100: */
101: public String getMaintainRole();
102:
103: /**
104: * Access the user's membership record for this AuthzGroup; the role, and status flags.
105: *
106: * @param userId
107: * The user id.
108: * @return The Membership record for the user in this AuthzGroup, or null if the use is not a member.
109: */
110: public Member getMember(String userId);
111:
112: /**
113: * Access all Membership records defined for this AuthzGroup.
114: *
115: * @return The set of Membership records (Membership) defined for this AuthzGroup.
116: */
117: public Set getMembers();
118:
119: /**
120: * @return the user who last modified this.
121: */
122: User getModifiedBy();
123:
124: /**
125: * @return the time last modified.
126: */
127: Time getModifiedTime();
128:
129: /**
130: * Access the group id for the GroupProvider for this AuthzGroup.
131: *
132: * @return The the group id for the GroupProvider for this AuthzGroup, or null if none defined.
133: */
134: public String getProviderGroupId();
135:
136: /**
137: * Access a Role defined in this AuthzGroup.
138: *
139: * @param id
140: * The role id.
141: * @return The Role, if found, or null, if not.
142: */
143: public Role getRole(String id);
144:
145: /**
146: * Access all Roles defined for this AuthzGroup.
147: *
148: * @return The set of roles (Role) defined for this AuthzGroup.
149: */
150: public Set getRoles();
151:
152: /**
153: * Access all roles that have been granted permission to this function.
154: *
155: * @param function
156: * The function to check.
157: * @return The Set of role names (String) that have been granted permission to this function.
158: */
159: public Set getRolesIsAllowed(String function);
160:
161: /**
162: * Access the active role for this user's membership.
163: *
164: * @param userId
165: * The user id.
166: * @return The Role for this user's membership, or null if the user has no active membership.
167: */
168: public Role getUserRole(String userId);
169:
170: /**
171: * Access all users who have active role membership in the AuthzGroup.
172: *
173: * @return The Set of users ids (String) who have active role membership in the AuthzGroup.
174: */
175: public Set getUsers();
176:
177: /**
178: * Access all users who have an active role membership with this role.
179: *
180: * @return The Set of user ids (String) who have an active role membership with this role.
181: */
182: public Set getUsersHasRole(String role);
183:
184: /**
185: * Access all users who have an active role membership to a role that is allowed this function.
186: *
187: * @param function
188: * The function to check.
189: * @return The Set of user ids (String) who have an active role membership to a role that is allowed this function.
190: */
191: public Set getUsersIsAllowed(String function);
192:
193: /**
194: * Test if this user has a membership in this AuthzGroup that has this role and is active.
195: *
196: * @param userId
197: * The user id.
198: * @param role
199: * The role name.
200: * @return true if the User has has a membership in this AuthzGroup that has this role and is active.
201: */
202: boolean hasRole(String userId, String role);
203:
204: /**
205: * Test if this user is allowed to perform the function in this AuthzGroup.
206: *
207: * @param userId
208: * The user id.
209: * @param function
210: * The function to open.
211: * @return true if this user is allowed to perform the function in this AuthzGroup, false if not.
212: */
213: boolean isAllowed(String userId, String function);
214:
215: /**
216: * Is this AuthzGroup empty of any roles or membership?
217: *
218: * @return true if the AuthzGroup is empty, false if not.
219: */
220: public boolean isEmpty();
221:
222: /**
223: * Remove membership for for this user from the AuthzGroup.
224: *
225: * @param userId
226: * The user.
227: */
228: void removeMember(String userId);
229:
230: /**
231: * Remove all membership from this AuthzGroup.
232: */
233: void removeMembers();
234:
235: /**
236: * Remove this Role from this AuthzGroup. Any grants of this Role in the AuthzGroup are also removed.
237: *
238: * @param role
239: * The role name.
240: */
241: void removeRole(String role);
242:
243: /**
244: * Remove all Roles from this AuthzGroup.
245: */
246: void removeRoles();
247:
248: /**
249: * Set the role name to use for "maintain" access.
250: *
251: * @param role
252: * The name of the "maintain" role.
253: */
254: void setMaintainRole(String role);
255:
256: /**
257: * Set the external group id for the GroupProvider for this AuthzGroup (set to null to have none).
258: *
259: * @param id
260: * The external group id for the GroupProvider, or null if there is to be none.
261: */
262: void setProviderGroupId(String id);
263:
264: /**
265: * Adjust membership so that active members are all active in other, and inactive members are all defined in other
266: *
267: * @param other
268: * The other azg to adjust to.
269: * @return true if any changes were made, false if not.
270: */
271: boolean keepIntersection(AuthzGroup other);
272: }
|