001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/user/tags/sakai_2-4-1/user-api/api/src/java/org/sakaiproject/user/api/UserDirectoryService.java $
003: * $Id: UserDirectoryService.java 15728 2006-10-06 13:49:59Z ajpoland@iupui.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.user.api;
021:
022: import java.util.Collection;
023: import java.util.List;
024:
025: import org.sakaiproject.entity.api.EntityProducer;
026: import org.sakaiproject.entity.api.ResourceProperties;
027: import org.w3c.dom.Element;
028:
029: /**
030: * <p>
031: * UserDirectoryService manages the end-user modeling for Sakai.
032: * </p>
033: */
034: public interface UserDirectoryService extends EntityProducer {
035: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
036: static final String APPLICATION_ID = "sakai:user";
037:
038: /** This string starts the references to resources in this service. */
039: static final String REFERENCE_ROOT = "/user";
040:
041: /** Name for the event of adding a group. */
042: static final String SECURE_ADD_USER = "user.add";
043:
044: /** Name for the event of removing a user. */
045: static final String SECURE_REMOVE_USER = "user.del";
046:
047: /** Name for the event of updating any user info. */
048: static final String SECURE_UPDATE_USER_ANY = "user.upd.any";
049:
050: /** Name for the event of updating one's own user info. */
051: static final String SECURE_UPDATE_USER_OWN = "user.upd.own";
052:
053: /** Name for the ability for updating one's own name. */
054: static final String SECURE_UPDATE_USER_OWN_NAME = "user.upd.own.name";
055:
056: /** Name for the ability for updating one's own email. */
057: static final String SECURE_UPDATE_USER_OWN_EMAIL = "user.upd.own.email";
058:
059: /** Name for the ability for updating one's own password. */
060: static final String SECURE_UPDATE_USER_OWN_PASSWORD = "user.upd.own.passwd";
061:
062: /** Name for the ability for updating one's own type. */
063: static final String SECURE_UPDATE_USER_OWN_TYPE = "user.upd.own.type";
064:
065: /** User id for the admin user. */
066: static final String ADMIN_ID = "admin";
067:
068: /** User eid for the admin user. */
069: static final String ADMIN_EID = "admin";
070:
071: /**
072: * Add a new user to the directory. Must commitEdit() to make official, or cancelEdit() when done! Id is auto-generated.
073: *
074: * @param id
075: * The user uuid string. Leave null for auto-assignment.
076: * @param eid
077: * The user eid.
078: * @return A locked UserEdit object (reserving the id).
079: * @exception UserIdInvalidException
080: * if the user eid is invalid.
081: * @exception UserAlreadyDefinedException
082: * if the user id or eid is already used.
083: * @exception UserPermissionException
084: * if the current user does not have permission to add a user.
085: */
086: UserEdit addUser(String id, String eid)
087: throws UserIdInvalidException, UserAlreadyDefinedException,
088: UserPermissionException;
089:
090: /**
091: * Add a new user to the directory, complete in one operation. Id is auto-generated.
092: *
093: * @param id
094: * The user uuid string. Leave null for auto-assignment.
095: * @param eid
096: * The user eid.
097: * @param firstName
098: * The user first name.
099: * @param lastName
100: * The user last name.
101: * @param email
102: * The user email.
103: * @param pw
104: * The user password.
105: * @param type
106: * The user type.
107: * @param properties
108: * Other user properties.
109: * @return The User object created.
110: * @exception UserIdInvalidException
111: * if the user eid is invalid.
112: * @exception UserAlreadyDefinedException
113: * if the user eid is already used.
114: * @exception UserPermissionException
115: * if the current user does not have permission to add a user.
116: */
117: User addUser(String id, String eid, String firstName,
118: String lastName, String email, String pw, String type,
119: ResourceProperties properties)
120: throws UserIdInvalidException, UserAlreadyDefinedException,
121: UserPermissionException;
122:
123: /**
124: * check permissions for addUser().
125: *
126: * @return true if the user is allowed to add a user, false if not.
127: */
128: boolean allowAddUser();
129:
130: /**
131: * check permissions for removeUser().
132: *
133: * @param id
134: * The group id.
135: * @return true if the user is allowed to removeUser(id), false if not.
136: */
137: boolean allowRemoveUser(String id);
138:
139: /**
140: * check permissions for editUser()
141: *
142: * @param id
143: * The user id.
144: * @return true if the user is allowed to update the user, false if not.
145: */
146: boolean allowUpdateUser(String id);
147:
148: /**
149: * check permissions for editUser()
150: *
151: * @param id
152: * The user id.
153: * @return true if the user is allowed to update their own first and last names, false if not.
154: */
155: public boolean allowUpdateUserName(String id);
156:
157: /**
158: * check permissions for editUser()
159: *
160: * @param id
161: * The user id.
162: * @return true if the user is allowed to update their own email address, false if not.
163: */
164: public boolean allowUpdateUserEmail(String id);
165:
166: /**
167: * check permissions for editUser()
168: *
169: * @param id
170: * The user id.
171: * @return true if the user is allowed to update their own password, false if not.
172: */
173: public boolean allowUpdateUserPassword(String id);
174:
175: /**
176: * check permissions for editUser()
177: *
178: * @param id
179: * The user id.
180: * @return true if the user is allowed to update their own type, false if not.
181: */
182: public boolean allowUpdateUserType(String id);
183:
184: /**
185: * Authenticate a user / password.
186: *
187: * @param eid
188: * The user eid.
189: * @param password
190: * The password.
191: * @return The User object of the authenticated user if successfull, null if not.
192: */
193: User authenticate(String eid, String password);
194:
195: /**
196: * Cancel the changes made to a UserEdit object, and release the lock. The UserEdit is disabled, and not to be used after this call.
197: *
198: * @param user
199: * The UserEdit object to commit.
200: */
201: void cancelEdit(UserEdit user);
202:
203: /**
204: * Commit the changes made to a UserEdit object, and release the lock. The UserEdit is disabled, and not to be used after this call.
205: *
206: * @param user
207: * The UserEdit object to commit.
208: * @exception UserAlreadyDefinedException
209: * if the User eid is already in use by another User object.
210: */
211: void commitEdit(UserEdit user) throws UserAlreadyDefinedException;
212:
213: /**
214: * Count all the users that match this criteria in id or target, first or last name.
215: *
216: * @return The count of all users matching the criteria.
217: */
218: int countSearchUsers(String criteria);
219:
220: /**
221: * Count all the users.
222: *
223: * @return The count of all users.
224: */
225: int countUsers();
226:
227: /**
228: * Remove authentication for the current user.
229: */
230: void destroyAuthentication();
231:
232: /**
233: * Get a locked user object for editing. Must commitEdit() to make official, or cancelEdit() when done!
234: *
235: * @param id
236: * The user id string.
237: * @return A UserEdit object for editing.
238: * @exception UserNotDefinedException
239: * if not found, or if not an UserEdit object
240: * @exception UserPermissionException
241: * if the current user does not have permission to mess with this user.
242: * @exception UserLockedException
243: * if the User object is locked by someone else.
244: */
245: UserEdit editUser(String id) throws UserNotDefinedException,
246: UserPermissionException, UserLockedException;
247:
248: /**
249: * Find the user objects which have this email address.
250: *
251: * @param email
252: * The email address string.
253: * @return A Collection (User) of user objects which have this email address (may be empty).
254: */
255: Collection findUsersByEmail(String email);
256:
257: /**
258: * Access the anonymous user object.
259: *
260: * @return the anonymous user object.
261: */
262: User getAnonymousUser();
263:
264: /**
265: * Access the user object associated with the "current" request.
266: *
267: * @return The current user (may be anon).
268: */
269: User getCurrentUser();
270:
271: /**
272: * Access a user object.
273: *
274: * @param id
275: * The user id string.
276: * @return A user object containing the user information
277: * @exception UserNotDefinedException
278: * if not found
279: */
280: User getUser(String id) throws UserNotDefinedException;
281:
282: /**
283: * Access a user object, given an enterprise id.
284: *
285: * @param eid
286: * The user eid string.
287: * @return A user object containing the user information
288: * @exception UserNotDefinedException
289: * if not found
290: */
291: User getUserByEid(String eid) throws UserNotDefinedException;
292:
293: /**
294: * Find the user eid from a user id.
295: *
296: * @param id
297: * The user id.
298: * @return The eid for the user with this id.
299: * @exception UserNotDefinedException
300: * if we don't know anything about the user with this id.
301: */
302: String getUserEid(String id) throws UserNotDefinedException;
303:
304: /**
305: * Find the user id from a user eid.
306: *
307: * @param eid
308: * The user eid.
309: * @return The id for the user with this eid.
310: * @exception UserNotDefinedException
311: * if we don't know anything about the user with this eid.
312: */
313: String getUserId(String eid) throws UserNotDefinedException;
314:
315: /**
316: * Access all user objects - known to us (not from external providers).
317: *
318: * @return A list of user objects containing each user's information.
319: * @exception IdUnusedException
320: * if not found.
321: */
322: List getUsers();
323:
324: /**
325: * Access a bunch of user object.
326: *
327: * @param ids
328: * The Collection (String) of user ids.
329: * @return A List (User) of user objects for valid ids.
330: */
331: List getUsers(Collection ids);
332:
333: /**
334: * Find all the users within the record range given (sorted by sort name).
335: *
336: * @param first
337: * The first record position to return.
338: * @param last
339: * The last record position to return.
340: * @return A list (User) of all the users within the record range given (sorted by sort name).
341: */
342: List getUsers(int first, int last);
343:
344: /**
345: * Add a new user to the directory, from a definition in XML. Must commitEdit() to make official, or cancelEdit() when done!
346: *
347: * @param el
348: * The XML DOM Element defining the user.
349: * @return A locked UserEdit object (reserving the id).
350: * @exception UserIdInvalidException
351: * if the user id is invalid.
352: * @exception UserAlreadyDefinedException
353: * if the user id is already used.
354: * @exception UserPermissionException
355: * if the current user does not have permission to add a user.
356: */
357: UserEdit mergeUser(Element el) throws UserIdInvalidException,
358: UserAlreadyDefinedException, UserPermissionException;
359:
360: /**
361: * Remove this user's information from the directory - it must be a user with a lock from editUser(). The UserEdit is disabled, and not to be used after this call.
362: *
363: * @param user
364: * The locked user object to remove.
365: * @exception UserPermissionException
366: * if the current user does not have permission to remove this user.
367: */
368: void removeUser(UserEdit user) throws UserPermissionException;
369:
370: /**
371: * Search all the users that match this criteria in id or email, first or last name, returning a subset of records within the record range given (sorted by sort name).
372: *
373: * @param criteria
374: * The search criteria.
375: * @param first
376: * The first record position to return.
377: * @param last
378: * The last record position to return.
379: * @return A list (User) of all the aliases matching the criteria, within the record range given (sorted by sort name).
380: */
381: List searchUsers(String criteria, int first, int last);
382:
383: /**
384: * Access the internal reference which can be used to access the resource from within the system.
385: *
386: * @param id
387: * The user id string.
388: * @return The the internal reference which can be used to access the resource from within the system.
389: */
390: String userReference(String id);
391: }
|