Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
IIdentityManager |
|
| 1.0;1 |
1 | /** | |
2 | * 2007, Digitalis Informatica. All rights reserved. Distribuicao e Gestao de Informatica, Lda. Estrada de Paco de Arcos | |
3 | * num.9 - Piso -1 2780-666 Paco de Arcos Telefone: (351) 21 4408990 Fax: (351) 21 4408999 http://www.digitalis.pt | |
4 | */ | |
5 | ||
6 | package pt.digitalis.dif.controller.security.managers; | |
7 | ||
8 | import java.util.List; | |
9 | import java.util.Map; | |
10 | import java.util.Set; | |
11 | ||
12 | import pt.digitalis.dif.controller.security.objects.IDIFGroup; | |
13 | import pt.digitalis.dif.controller.security.objects.IDIFUser; | |
14 | import pt.digitalis.dif.exception.security.IdentityManagerException; | |
15 | import pt.digitalis.dif.utils.Pagination; | |
16 | ||
17 | /** | |
18 | * Defines the expected behavior for an identity manager. This manager supports users {@link IDIFUser} and groups | |
19 | * {@link IDIFGroup}. | |
20 | * | |
21 | * @author Rodrigo Gon�alves <a href="mailto:rgoncalves@digitalis.pt">rgoncalves@digitalis.pt</a><br/> | |
22 | * @author Luis Pinto <a href="lpinto@digitalis.pt">lpinto@digitalis.pt</a><br/> | |
23 | * @author Pedro Viegas <a href="mailto:pviegas@digitalis.pt">pviegas@digitalis.pt</a><br/> | |
24 | * @author Fábio Souto <a href="mailto:fsouto@digitalis.pt">fsouto@digitalis.pt</a><br/> | |
25 | * @created 2007/12/04 | |
26 | */ | |
27 | public interface IIdentityManager { | |
28 | ||
29 | // --------- User operations --------- | |
30 | ||
31 | /** | |
32 | * Adds a new group to the manager. | |
33 | * | |
34 | * @param newGroup | |
35 | * the group to add | |
36 | * @throws IdentityManagerException | |
37 | * if the user can't be added | |
38 | */ | |
39 | public void addGroup(IDIFGroup newGroup) throws IdentityManagerException; | |
40 | ||
41 | /** | |
42 | * Adds a managed attribute. | |
43 | * | |
44 | * @param attribute | |
45 | * The attribute | |
46 | */ | |
47 | public void addManagedAttribute(String attribute); | |
48 | ||
49 | /** | |
50 | * Adds a comma-separated list of managed attributes. | |
51 | * | |
52 | * @param attributes | |
53 | * The comma-separated list of managed attributes. | |
54 | */ | |
55 | public void addManagedAttributes(String attributes); | |
56 | ||
57 | /** | |
58 | * Adds a new user to the manager. | |
59 | * | |
60 | * @param newUser | |
61 | * the new user to add to the manager | |
62 | * @throws IdentityManagerException | |
63 | * if the user can't be added | |
64 | */ | |
65 | public void addUser(IDIFUser newUser) throws IdentityManagerException; | |
66 | ||
67 | /** | |
68 | * Adds an existing user to an existing group. | |
69 | * | |
70 | * @param groupID | |
71 | * the group ID | |
72 | * @param userID | |
73 | * the user ID | |
74 | * @throws IdentityManagerException | |
75 | * if the user can't be added to the group | |
76 | */ | |
77 | public void addUserToGroup(String userID, String groupID) throws IdentityManagerException; | |
78 | ||
79 | /** | |
80 | * Changes the password for the supplied user. | |
81 | * | |
82 | * @param userID | |
83 | * the user ID | |
84 | * @param newPassword | |
85 | * the new password | |
86 | * @throws IdentityManagerException | |
87 | * if the password can't be changed | |
88 | */ | |
89 | public void changePassword(String userID, String newPassword) throws IdentityManagerException; | |
90 | ||
91 | /** | |
92 | * Checks if a parameter exists. | |
93 | * | |
94 | * @param userID | |
95 | * the user ID | |
96 | * @param parameterID | |
97 | * the parameter ID | |
98 | * @return T if the parameter exists, F otherwise | |
99 | */ | |
100 | public boolean containsUserParameter(String userID, String parameterID); | |
101 | ||
102 | /** | |
103 | * Counts the number of groups in the system | |
104 | * | |
105 | * @return The number of groups in the system | |
106 | * @throws IdentityManagerException | |
107 | * * If the operation cannot be executed | |
108 | */ | |
109 | public int countAllGroups() throws IdentityManagerException; | |
110 | ||
111 | /** | |
112 | * Counts all groups of a given user. | |
113 | * | |
114 | * @param userId | |
115 | * The user identifier | |
116 | * @return The number of groups of this user. | |
117 | * @throws IdentityManagerException | |
118 | */ | |
119 | public int countAllGroupsOfUser(String userId) throws IdentityManagerException; | |
120 | ||
121 | /** | |
122 | * Counts all groups of a given user. | |
123 | * | |
124 | * @param userId | |
125 | * The user identifier | |
126 | * @param parseGroupHierarchy | |
127 | * contemplates the group Hierarchy | |
128 | * @return The number of groups of this user. | |
129 | * @throws IdentityManagerException | |
130 | */ | |
131 | public int countAllGroupsOfUser(String userId, boolean parseGroupHierarchy) throws IdentityManagerException; | |
132 | ||
133 | /** | |
134 | * Counts the number of users in the system | |
135 | * | |
136 | * @return The number of users on the system | |
137 | * @throws IdentityManagerException | |
138 | * If the operation cannot be executed | |
139 | */ | |
140 | public int countAllUsers() throws IdentityManagerException; | |
141 | ||
142 | /** | |
143 | * Counts all users of a given group. | |
144 | * | |
145 | * @param groupId | |
146 | * The group identifier | |
147 | * @return The number of users of this group. | |
148 | * @throws IdentityManagerException | |
149 | */ | |
150 | public int countAllUsers(String groupId) throws IdentityManagerException; | |
151 | ||
152 | /** | |
153 | * Count the number of users in the system which match all of the provided attributes | |
154 | * | |
155 | * @param attributes | |
156 | * The attributes | |
157 | * @return The number of users in the system which match all of the provided attributes | |
158 | * @throws IdentityManagerException | |
159 | * If the operation cannot be executed | |
160 | */ | |
161 | public int countUsers(Map<String, String> attributes) throws IdentityManagerException; | |
162 | ||
163 | /** | |
164 | * Gathers the managed attributes. This method must be used to initialize the managed attributes. | |
165 | * | |
166 | * @return The list containing the managed attributes | |
167 | */ | |
168 | public List<String> gatherManagedAttributes(); | |
169 | ||
170 | /** | |
171 | * Get all the groups registered in the system | |
172 | * | |
173 | * @return A set containing all the groups | |
174 | * @throws IdentityManagerException | |
175 | * If the operation cannot be executed | |
176 | */ | |
177 | public Set<IDIFGroup> getAllGroups() throws IdentityManagerException; | |
178 | ||
179 | /** | |
180 | * Get all the users in the system | |
181 | * | |
182 | * @return A set containing all the users | |
183 | * @throws IdentityManagerException | |
184 | * If the operation cannot be executed | |
185 | */ | |
186 | public Set<IDIFUser> getAllUsers() throws IdentityManagerException; | |
187 | ||
188 | /** | |
189 | * Get the exclusion charaters | |
190 | * | |
191 | * @return value | |
192 | */ | |
193 | public String getExclusionCharaters(); | |
194 | ||
195 | /** | |
196 | * Gets a group from its id, if it exists. | |
197 | * | |
198 | * @param groupID | |
199 | * the group id | |
200 | * @return the group with the given id if it exists, null otherwise | |
201 | * @throws IdentityManagerException | |
202 | * if the group can't be found | |
203 | */ | |
204 | public IDIFGroup getGroup(String groupID) throws IdentityManagerException; | |
205 | ||
206 | /** | |
207 | * Gets the group attribute name | |
208 | * | |
209 | * @return The string containing the attribute name | |
210 | */ | |
211 | public String getGroupAttributeName(); | |
212 | ||
213 | /** | |
214 | * Returns the list of groups whose parent group is the given group | |
215 | * | |
216 | * @param parentGroupID | |
217 | * the parent group to search for children groups | |
218 | * @return the list of groups | |
219 | * @throws IdentityManagerException | |
220 | * if the group's groups can't be found | |
221 | */ | |
222 | public Map<String, IDIFGroup> getGroupGroups(String parentGroupID) throws IdentityManagerException; | |
223 | ||
224 | /** | |
225 | * Returns a subset of all groups in the system, according to the parameters | |
226 | * | |
227 | * @param page | |
228 | * The required page | |
229 | * @return A set of groups containing the specified subset | |
230 | * @throws IdentityManagerException | |
231 | * If the operation can't be executed | |
232 | */ | |
233 | public Set<IDIFGroup> getGroups(Pagination page) throws IdentityManagerException; | |
234 | ||
235 | /** | |
236 | * Returns the list of users of a given group | |
237 | * | |
238 | * @param groupID | |
239 | * the group | |
240 | * @return the list of users | |
241 | * @throws IdentityManagerException | |
242 | * if the operation can't be executed | |
243 | */ | |
244 | public Map<String, IDIFUser> getGroupUsers(String groupID) throws IdentityManagerException; | |
245 | ||
246 | /** | |
247 | * Gets the mail attribute name | |
248 | * | |
249 | * @return The string containing the attribute name. | |
250 | */ | |
251 | public String getMailAttributeName(); | |
252 | ||
253 | /** | |
254 | * Gets the framework managed attributes. | |
255 | * | |
256 | * @return the managedAttributes value | |
257 | */ | |
258 | public List<String> getManagedAttributes(); | |
259 | ||
260 | /** | |
261 | * Gets the name attribute name | |
262 | * | |
263 | * @return The string containing the attribute name. | |
264 | */ | |
265 | public String getNameAttributeName(); | |
266 | ||
267 | /** | |
268 | * Gets an user from its id, if it exists. | |
269 | * | |
270 | * @param userID | |
271 | * the user id | |
272 | * @return the user that matches the supplied id if it exists, null otherwise | |
273 | * @throws IdentityManagerException | |
274 | * if the user can't be fetched | |
275 | */ | |
276 | public IDIFUser getUser(String userID) throws IdentityManagerException; | |
277 | ||
278 | /** | |
279 | * Returns the list of groups of a given user | |
280 | * | |
281 | * @param userID | |
282 | * the user | |
283 | * @return the list of groups | |
284 | * @throws IdentityManagerException | |
285 | * if the group's users can't be found | |
286 | */ | |
287 | public Map<String, IDIFGroup> getUserGroups(String userID) throws IdentityManagerException; | |
288 | ||
289 | /** | |
290 | * Returns the list of groups of a given user | |
291 | * | |
292 | * @param userID | |
293 | * the user | |
294 | * @param parseGroupHierarchy | |
295 | * contemplates the group Hierarchy | |
296 | * @return the list of groups | |
297 | * @throws IdentityManagerException | |
298 | * if the group's users can't be found | |
299 | */ | |
300 | public Map<String, IDIFGroup> getUserGroups(String userID, boolean parseGroupHierarchy) | |
301 | throws IdentityManagerException; | |
302 | ||
303 | /** | |
304 | * Returns the list of group IDs of a given user | |
305 | * | |
306 | * @param userID | |
307 | * the user | |
308 | * @return the list of groups | |
309 | * @throws IdentityManagerException | |
310 | * if the group's users can't be found | |
311 | */ | |
312 | public Set<String> getUserGroupsIDs(String userID) throws IdentityManagerException; | |
313 | ||
314 | /** | |
315 | * Returns the list of group IDs of a given user | |
316 | * | |
317 | * @param userID | |
318 | * the user | |
319 | * @param parseGroupHierarchy | |
320 | * contemplates the group Hierarchy | |
321 | * @return the list of groups | |
322 | * @throws IdentityManagerException | |
323 | * if the group's users can't be found | |
324 | */ | |
325 | public Set<String> getUserGroupsIDs(String userID, boolean parseGroupHierarchy) throws IdentityManagerException; | |
326 | ||
327 | /** | |
328 | * Returns the list of groups of a given user, with pagination. This method doesn't consider the profile as a group. | |
329 | * | |
330 | * @param userID | |
331 | * the user | |
332 | * @param page | |
333 | * The page to be returned | |
334 | * @return the list of groups | |
335 | * @throws IdentityManagerException | |
336 | * if the group's users can't be found | |
337 | */ | |
338 | public Map<String, IDIFGroup> getUserGroupsPagination(String userID, Pagination page) | |
339 | throws IdentityManagerException; | |
340 | ||
341 | // --------- Group operations --------- | |
342 | ||
343 | /** | |
344 | * Returns the list of user IDs of a given group | |
345 | * | |
346 | * @param groupID | |
347 | * the group | |
348 | * @return the list of users | |
349 | * @throws IdentityManagerException | |
350 | * if the operation can't be executed | |
351 | */ | |
352 | public Set<String> getUserIDsInGroup(String groupID) throws IdentityManagerException; | |
353 | ||
354 | /** | |
355 | * Gets the user login attribute name | |
356 | * | |
357 | * @return The string containing the attribute name. | |
358 | */ | |
359 | public String getUserLoginAttributeName(); | |
360 | ||
361 | /** | |
362 | * Gets a given parameter from a given user. | |
363 | * | |
364 | * @param userID | |
365 | * @param parameterID | |
366 | * @return the parameter value if it exists, null otherwise | |
367 | */ | |
368 | public Object getUserParameter(String userID, String parameterID); | |
369 | ||
370 | /** | |
371 | * Gets all the parameters from a given user. | |
372 | * | |
373 | * @param userID | |
374 | * the user ID | |
375 | * @return the parameters map if it exists, null otherwise | |
376 | */ | |
377 | public Map<String, Object> getUserParameters(String userID); | |
378 | ||
379 | /** | |
380 | * Returns the user parent group attribute name | |
381 | * | |
382 | * @return A string containing the user parent group attribute name | |
383 | */ | |
384 | public String getUserParentGroupAttributeName(); | |
385 | ||
386 | /** | |
387 | * Returns a subset of all users in the system, according to the parameters | |
388 | * | |
389 | * @param page | |
390 | * The required page | |
391 | * @return A set of users containing the specified subset | |
392 | * @throws IdentityManagerException | |
393 | * If the operation can't be executed | |
394 | */ | |
395 | public Set<IDIFUser> getUsers(Pagination page) throws IdentityManagerException; | |
396 | ||
397 | // --------- Relation operations --------- | |
398 | ||
399 | /** | |
400 | * Returns the list of users with a given attribute value.<br/> | |
401 | * Supports partial matches by adding "%" or "*" before and/or after the attribute value | |
402 | * | |
403 | * @param attribute | |
404 | * the attribute to search | |
405 | * @param value | |
406 | * the value for the attribute | |
407 | * @return the LDAPUser with the given login name | |
408 | * @throws IdentityManagerException | |
409 | * if the operation cannot be executed | |
410 | */ | |
411 | public Set<IDIFUser> getUsersByAttribute(String attribute, String value) throws IdentityManagerException; | |
412 | ||
413 | /** | |
414 | * Get users that match specified attributes.<br/> | |
415 | * Supports partial matches by adding "%" or "*" before and/or after the attribute value | |
416 | * | |
417 | * @param attributes | |
418 | * A map of attributes to be searched, where the keys are the attribute names, and the values are the | |
419 | * attribute values. | |
420 | * @return A set containing the users that obey all of the specified criteria | |
421 | * @throws IdentityManagerException | |
422 | * If the operation can't be executed | |
423 | */ | |
424 | public Set<IDIFUser> getUsersByAttributes(Map<String, String> attributes) throws IdentityManagerException; | |
425 | ||
426 | /** | |
427 | * Get users that match specified attributes.<br/> | |
428 | * Supports partial matches by adding "%" or "*" before and/or after the attribute value | |
429 | * | |
430 | * @param attributes | |
431 | * A map of attributes to be searched, where the keys are the attribute names, and the values are the | |
432 | * attribute values. | |
433 | * @param page | |
434 | * The page to be obtained | |
435 | * @return A set containing the users that obey all of the specified criteria | |
436 | * @throws IdentityManagerException | |
437 | * If the operation can't be executed | |
438 | */ | |
439 | public Set<IDIFUser> getUsersByAttributes(Map<String, String> attributes, Pagination page) | |
440 | throws IdentityManagerException; | |
441 | ||
442 | /** | |
443 | * Returns the list of users with a given email attribute value. | |
444 | * | |
445 | * @param value | |
446 | * the value for the attribute email | |
447 | * @return the LDAPUser with the given login name | |
448 | * @throws IdentityManagerException | |
449 | * if the operation cannot be executed | |
450 | */ | |
451 | public Set<IDIFUser> getUsersByEmail(String value) throws IdentityManagerException; | |
452 | ||
453 | /** | |
454 | * Checks if a group exists on the manager. | |
455 | * | |
456 | * @param groupID | |
457 | * the ID of the group | |
458 | * @return T if the group exists, F otherwise | |
459 | * @throws IdentityManagerException | |
460 | * if the operation can't be executed | |
461 | */ | |
462 | public boolean groupExists(String groupID) throws IdentityManagerException; | |
463 | ||
464 | /** | |
465 | * Checks if the supplied password matches the one defined for a user with a given ID. | |
466 | * | |
467 | * @param userID | |
468 | * the user ID | |
469 | * @param suppliedPassword | |
470 | * the supplied user password | |
471 | * @return T if user if its identity is valid, F otherwise | |
472 | * @throws IdentityManagerException | |
473 | * if the group can't be added as member of the parent group | |
474 | */ | |
475 | public boolean isIdentityValid(String userID, String suppliedPassword) throws IdentityManagerException; | |
476 | ||
477 | /** | |
478 | * Get the ldap readOnly configuration value. | |
479 | * | |
480 | * @return true or false | |
481 | */ | |
482 | public boolean isReadOnly(); | |
483 | ||
484 | /** | |
485 | * Checks if a given user belongs to a given group. | |
486 | * | |
487 | * @param userID | |
488 | * the user ID | |
489 | * @param groupID | |
490 | * the group ID | |
491 | * @return T if the user belongs to the group, F otherwise | |
492 | * @throws IdentityManagerException | |
493 | * if the operation can't be executed | |
494 | */ | |
495 | public boolean isUserInGroup(String userID, String groupID) throws IdentityManagerException; | |
496 | ||
497 | /** | |
498 | * Checks if a given user belongs to a given group. | |
499 | * | |
500 | * @param userID | |
501 | * the user ID | |
502 | * @param groupID | |
503 | * the group ID | |
504 | * @param parseGroupHierarchy | |
505 | * contemplates the group Hierarchy | |
506 | * @return T if the user belongs to the group, F otherwise | |
507 | * @throws IdentityManagerException | |
508 | * if the operation can't be executed | |
509 | */ | |
510 | public boolean isUserInGroup(String userID, String groupID, boolean parseGroupHierarchy) | |
511 | throws IdentityManagerException; | |
512 | ||
513 | // --------- Identity manager related operations --------- | |
514 | ||
515 | /** | |
516 | * Removes an existing group from the manager, if it exists. | |
517 | * | |
518 | * @param groupID | |
519 | * the id of the group to remove | |
520 | * @throws IdentityManagerException | |
521 | * if the group can't be removed | |
522 | */ | |
523 | public void removeGroup(String groupID) throws IdentityManagerException; | |
524 | ||
525 | /** | |
526 | * Removes an existing user from the manager, if it exists. | |
527 | * | |
528 | * @param userID | |
529 | * the id of the user to remove | |
530 | * @throws IdentityManagerException | |
531 | * if the user can't be removed | |
532 | */ | |
533 | public void removeUser(String userID) throws IdentityManagerException; | |
534 | ||
535 | /** | |
536 | * Removes an existing user from an existing group. | |
537 | * | |
538 | * @param groupID | |
539 | * the group ID | |
540 | * @param userID | |
541 | * the user ID | |
542 | * @throws IdentityManagerException | |
543 | * if the user can't be removed from the group | |
544 | */ | |
545 | public void removeUserFromGroup(String userID, String groupID) throws IdentityManagerException; | |
546 | ||
547 | /** | |
548 | * Removes a given parameter from a given user. | |
549 | * | |
550 | * @param userID | |
551 | * the user ID | |
552 | * @param parameterID | |
553 | * the parameter ID | |
554 | */ | |
555 | public void removeUserParameter(String userID, String parameterID); | |
556 | ||
557 | /** Resets the identity manager. Different implementations will offer distinct types of reset. */ | |
558 | public void resetIdentityManager(); | |
559 | ||
560 | /** | |
561 | * Sets an user parameter. | |
562 | * | |
563 | * @param userID | |
564 | * the user ID | |
565 | * @param parameterID | |
566 | * the parameter ID | |
567 | * @param parameterValue | |
568 | * the parameter value | |
569 | */ | |
570 | public void setUserParameter(String userID, String parameterID, Object parameterValue); | |
571 | ||
572 | /** | |
573 | * Sets the user parameters as an whole. | |
574 | * | |
575 | * @param userID | |
576 | * the user ID | |
577 | * @param parametersMap | |
578 | * the parameters map | |
579 | */ | |
580 | public void setUserParameters(String userID, Map<String, Object> parametersMap); | |
581 | ||
582 | /** | |
583 | * Updates an existing group. Does nothing if the group doesn't exist. | |
584 | * | |
585 | * @param existingGroup | |
586 | * the group to update | |
587 | * @throws IdentityManagerException | |
588 | * if the group can't be updated | |
589 | */ | |
590 | public void updateGroup(IDIFGroup existingGroup) throws IdentityManagerException; | |
591 | ||
592 | /** | |
593 | * Updates an existing user. Does nothing if the user doesn't exist. | |
594 | * | |
595 | * @param existingUser | |
596 | * the user to update | |
597 | * @param userID | |
598 | * the user ID (must be supplied separately to ensure data integrity if the user ID is changed) | |
599 | * @throws IdentityManagerException | |
600 | * if the operation can't be executed | |
601 | */ | |
602 | public void updateUser(IDIFUser existingUser, String userID) throws IdentityManagerException; | |
603 | ||
604 | /** | |
605 | * Updates an attribute value on a given user and persists it. | |
606 | * | |
607 | * @param userID | |
608 | * the ID of the user to update | |
609 | * @param attributeID | |
610 | * the ID of the attribute to update | |
611 | * @param attributeValue | |
612 | * the value of the attribute to update | |
613 | * @throws IdentityManagerException | |
614 | * if the attribute can't be updated | |
615 | */ | |
616 | public void updateUserAttribute(String userID, String attributeID, Object attributeValue) | |
617 | throws IdentityManagerException; | |
618 | ||
619 | /** | |
620 | * Updates all of the user's attributes. | |
621 | * | |
622 | * @param userID | |
623 | * the ID of the user to update | |
624 | * @param attributes | |
625 | * the attributes to update | |
626 | * @throws IdentityManagerException | |
627 | * if the attribute can't be updated | |
628 | */ | |
629 | public void updateUserAttributes(String userID, Map<String, Object> attributes) throws IdentityManagerException; | |
630 | ||
631 | /** | |
632 | * Checks if a user exists on the manager. | |
633 | * | |
634 | * @param userID | |
635 | * the ID of the user | |
636 | * @return T if the user exists, F otherwise | |
637 | * @throws IdentityManagerException | |
638 | * if the operation can't be executed | |
639 | */ | |
640 | public boolean userExists(String userID) throws IdentityManagerException; | |
641 | ||
642 | } |