001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/authz/tags/sakai_2-4-1/authz-api/api/src/java/org/sakaiproject/authz/api/AuthzGroupService.java $
003: * $Id: AuthzGroupService.java 13785 2006-08-16 18:42:22Z jholtzman@berkeley.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.util.Collection;
023: import java.util.List;
024: import java.util.Map;
025: import java.util.Set;
026:
027: import org.sakaiproject.entity.api.EntityProducer;
028: import org.sakaiproject.javax.PagingPosition;
029:
030: /**
031: * <p>
032: * AuthzGroupService manages authorization grops.
033: * </p>
034: */
035: public interface AuthzGroupService extends EntityProducer {
036: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
037: static final String APPLICATION_ID = "sakai:authzGroup";
038:
039: /** This string starts the references to resources in this service. */
040: static final String REFERENCE_ROOT = "/realm";
041:
042: /** Name for the event of adding an AuthzGroup. */
043: static final String SECURE_ADD_AUTHZ_GROUP = "realm.add";
044:
045: /** Name for the event of removing an AuthzGroup. */
046: static final String SECURE_REMOVE_AUTHZ_GROUP = "realm.del";
047:
048: /** Name for the event of updating an AuthzGroup. */
049: static final String SECURE_UPDATE_AUTHZ_GROUP = "realm.upd";
050:
051: /** Name for the event of updating ones own relationship in an AuthzGroup. */
052: static final String SECURE_UPDATE_OWN_AUTHZ_GROUP = "realm.upd.own";
053:
054: /** Standard role name for the anon. role. */
055: static final String ANON_ROLE = ".anon";
056:
057: /** Standard role name for the auth. role. */
058: static final String AUTH_ROLE = ".auth";
059:
060: /**
061: * Access a list of AuthzGroups that meet specified criteria, naturally sorted.
062: *
063: * @param criteria
064: * Selection criteria: AuthzGroups returned will match this string somewhere in their id, or provider group id.
065: * @param page
066: * The PagePosition subset of items to return.
067: * @return The List (AuthzGroup) that meet specified criteria.
068: */
069: List getAuthzGroups(String criteria, PagingPosition page);
070:
071: /**
072: * Count the AuthzGroups that meet specified criteria.
073: *
074: * @param criteria
075: * Selection criteria: AuthzGroups returned will match this string somewhere in their id, or provider group id.
076: * @return The count of AuthzGroups that meet specified criteria.
077: */
078: int countAuthzGroups(String criteria);
079:
080: /**
081: * Access an AuthzGroup.
082: *
083: * @param id
084: * The id string.
085: * @return The AuthzGroup.
086: * @exception GroupNotDefinedException
087: * if not found.
088: */
089: AuthzGroup getAuthzGroup(String id) throws GroupNotDefinedException;
090:
091: /**
092: * Check permissions for updating an AuthzGroup.
093: *
094: * @param id
095: * The id.
096: * @return true if the user is allowed to update the AuthzGroup, false if not.
097: */
098: boolean allowUpdate(String id);
099:
100: /**
101: * Save the changes made to the AuthzGroup. The AuthzGroup must already exist, and the user must have permission to update.
102: *
103: * @param azGroup
104: * The AuthzGroup to save.
105: * @exception GroupNotDefinedException
106: * if the AuthzGroup id is not defined.
107: * @exception AuthzPermissionException
108: * if the current user does not have permission to update the AuthzGroup.
109: */
110: void save(AuthzGroup azGroup) throws GroupNotDefinedException,
111: AuthzPermissionException;
112:
113: /**
114: * Check permissions for adding an AuthzGroup.
115: *
116: * @param id
117: * The authzGroup id.
118: * @return true if the current user is allowed add the AuthzGroup, false if not.
119: */
120: boolean allowAdd(String id);
121:
122: /**
123: * Add a new AuthzGroup
124: *
125: * @param id
126: * The AuthzGroup id.
127: * @return The new AuthzGroup.
128: * @exception GroupIdInvalidException
129: * if the id is invalid.
130: * @exception GroupAlreadyDefinedException
131: * if the id is already used.
132: * @exception AuthzPermissionException
133: * if the current user does not have permission to add the AuthzGroup.
134: */
135: AuthzGroup addAuthzGroup(String id) throws GroupIdInvalidException,
136: GroupAlreadyDefinedException, AuthzPermissionException;
137:
138: /**
139: * Add a new AuthzGroup, as a copy of another AuthzGroup (except for id), and give a user "maintain" access based on the other's definition of "maintain".
140: *
141: * @param id
142: * The id.
143: * @param other
144: * The AuthzGroup to copy into this new AuthzGroup.
145: * @param maintainUserId
146: * Optional user id to get "maintain" access, or null if none.
147: * @return The new AuthzGroup object.
148: * @exception GroupIdInvalidException
149: * if the id is invalid.
150: * @exception GroupAlreadyDefinedException
151: * if the id is already used.
152: * @exception AuthzPermissionException
153: * if the current user does not have permission to add the AuthzGroup.
154: */
155: AuthzGroup addAuthzGroup(String id, AuthzGroup other,
156: String maintainUserId) throws GroupIdInvalidException,
157: GroupAlreadyDefinedException, AuthzPermissionException;
158:
159: /**
160: * Check permissions for removing an AuthzGroup.
161: *
162: * @param id
163: * The AuthzGroup id.
164: * @return true if the user is allowed to remove the AuthzGroup, false if not.
165: */
166: boolean allowRemove(String id);
167:
168: /**
169: * Remove this AuthzGroup.
170: *
171: * @param azGroup
172: * The AuthzGroup to remove.
173: * @exception AuthzPermissionException
174: * if the current user does not have permission to remove this AuthzGroup.
175: */
176: void removeAuthzGroup(AuthzGroup azGroup)
177: throws AuthzPermissionException;
178:
179: /**
180: * Remove the AuthzGroup with this id, if it exists (fails quietly if not).
181: *
182: * @param id
183: * The AuthzGroup id.
184: * @exception AuthzPermissionException
185: * if the current user does not have permission to remove this AthzGroup.
186: */
187: void removeAuthzGroup(String id) throws AuthzPermissionException;
188:
189: /**
190: * Access the internal reference which can be used to access the AuthzGroup from within the system.
191: *
192: * @param id
193: * The AuthzGroup id.
194: * @return The the internal reference which can be used to access the AuthzGroup from within the system.
195: */
196: String authzGroupReference(String id);
197:
198: /**
199: * Cause the current user to join the given AuthzGroup with this role, using SECURE_UPDATE_OWN_AUTHZ_GROUP security.
200: *
201: * @param authzGroupId
202: * the id of the AuthzGroup.
203: * @param role
204: * the name of the Role.
205: * @throws GroupNotDefinedException
206: * if the authzGroupId or role are not defined.
207: * @throws AuthzPermissionException
208: * if the current user does not have permission to join this AuthzGroup.
209: */
210: void joinGroup(String authzGroupId, String role)
211: throws GroupNotDefinedException, AuthzPermissionException;
212:
213: /**
214: * Cause the current user to unjoin the given AuthzGroup, using SECURE_UPDATE_OWN_AUTHZ_GROUP security.
215: *
216: * @param authzGroupId
217: * the id of the AuthzGroup.
218: * @throws GroupNotDefinedException
219: * if the authzGroupId or role are not defined.
220: * @throws AuthzPermissionException
221: * if the current user does not have permission to unjoin this site.
222: */
223: void unjoinGroup(String authzGroupId)
224: throws GroupNotDefinedException, AuthzPermissionException;
225:
226: /**
227: * Check permissions for the current user joining a group.
228: *
229: * @param id
230: * The AuthzGroup id.
231: * @return true if the user is allowed to join the group, false if not.
232: */
233: boolean allowJoinGroup(String id);
234:
235: /**
236: * Check permissions for the current user unjoining a group.
237: *
238: * @param id
239: * The AuthzGroup id.
240: * @return true if the user is allowed to unjoin the group, false if not.
241: */
242: boolean allowUnjoinGroup(String id);
243:
244: /**
245: * Test if this user is allowed to perform the function in the named AuthzGroup.
246: *
247: * @param userId
248: * The user id.
249: * @param function
250: * The function to open.
251: * @param azGroupId
252: * The AuthzGroup id to consult, if it exists.
253: * @return true if this user is allowed to perform the function in the named AuthzGroup, false if not.
254: */
255: boolean isAllowed(String userId, String function, String azGroupId);
256:
257: /**
258: * Test if this user is allowed to perform the function in the named AuthzGroups.
259: *
260: * @param userId
261: * The user id.
262: * @param function
263: * The function to open.
264: * @param azGroups
265: * A collection of AuthzGroup ids to consult.
266: * @return true if this user is allowed to perform the function in the named AuthzGroups, false if not.
267: */
268: boolean isAllowed(String userId, String function,
269: Collection azGroups);
270:
271: /**
272: * Get the set of user ids of users who are allowed to perform the function in the named AuthzGroups.
273: *
274: * @param function
275: * The function to check.
276: * @param azGroups
277: * A collection of the ids of AuthzGroups to consult.
278: * @return the Set (String) of user ids of users who are allowed to perform the function in the named AuthzGroups.
279: */
280: Set getUsersIsAllowed(String function, Collection azGroups);
281:
282: /**
283: * Get the set of AuthzGroup ids in which this user is allowed to perform this function.
284: *
285: * @param userId
286: * The user id.
287: * @param function
288: * The function to check.
289: * @param azGroups
290: * The Collection of AuthzGroup ids to search; if null, search them all.
291: * @return the Set (String) of AuthzGroup ids in which this user is allowed to perform this function.
292: */
293: Set getAuthzGroupsIsAllowed(String userId, String function,
294: Collection azGroups);
295:
296: /**
297: * Get the set of functions that users with this role in these AuthzGroups are allowed to perform.
298: *
299: * @param role
300: * The role name.
301: * @param azGroups
302: * A collection of AuthzGroup ids to consult.
303: * @return the Set (String) of functions that users with this role in these AuthzGroups are allowed to perform
304: */
305: Set getAllowedFunctions(String role, Collection azGroups);
306:
307: /**
308: * Get the role name for this user in this AuthzGroup, if the user has membership (the membership gives the user a single role).
309: *
310: * @param userId
311: * The user id.
312: * @param function
313: * The function to open.
314: * @param azGroupId
315: * The AuthzGroup id to consult, if it exists.
316: * @return the role name for this user in this AuthzGroup, if the user has active membership, or null if not.
317: */
318: String getUserRole(String userId, String azGroupId);
319:
320: /**
321: * Get the role name for each user in the userIds Collection in this AuthzGroup, for each of these users who have membership (membership gives the user a single role).
322: *
323: * @param userIds
324: * The user ids as a Collection of String.
325: * @param function
326: * The function to open.
327: * @param azGroupId
328: * The AuthzGroup id to consult, if it exists.
329: * @return A Map (userId (String) -> role name (String)) of role names for each user who have active membership; if the user does not, it will not be in the Map.
330: */
331: Map getUsersRole(Collection userIds, String azGroupId);
332:
333: /**
334: * Refresh this user's AuthzGroup external definitions.
335: *
336: * @param userId
337: * The user id.
338: */
339: void refreshUser(String userId);
340:
341: /**
342: * Create a new AuthzGroup, as a copy of another AuthzGroup (except for id), and give a user "maintain" access based on the other's definition of "maintain", but do not store - it can be saved with a save() call
343: *
344: * @param id
345: * The id.
346: * @param other
347: * The AuthzGroup to copy into this new AuthzGroup (or null if none).
348: * @param maintainUserId
349: * Optional user id to get "maintain" access, or null if none.
350: * @return The new AuthzGroup object.
351: * @exception GroupAlreadyDefinedException
352: * if the id is already used.
353: */
354: AuthzGroup newAuthzGroup(String id, AuthzGroup other,
355: String maintainUserId) throws GroupAlreadyDefinedException;
356:
357: /**
358: * Gets the IDs of the AuthzGroups with the given provider ID.
359: *
360: * @return The Set of Strings representing authzGroup IDs (such as /site/1234 or /site/1234/group/5678) for all authzGroups with the given providerId.
361: */
362: public Set getAuthzGroupIds(String providerId);
363:
364: /**
365: * Gets the provider IDs associated with an AuthzGroup.
366: *
367: * @return The Set of Strings representing external group IDs, as recognized by the GroupProvider implementation, that are associated with the given groupId. These strings
368: * must not be "compound IDs", as defined by the GroupProvider's String[] unpackId(String id) method.
369: */
370: public Set getProviderIds(String authzGroupId);
371: }
|