1 package org.apache.turbine.services.security;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import java.util.List;
23 import java.util.Map;
24
25 import org.apache.torque.util.Criteria;
26
27 import org.apache.turbine.om.security.Group;
28 import org.apache.turbine.om.security.Permission;
29 import org.apache.turbine.om.security.Role;
30 import org.apache.turbine.om.security.TurbineGroup;
31 import org.apache.turbine.om.security.TurbinePermission;
32 import org.apache.turbine.om.security.TurbineRole;
33 import org.apache.turbine.om.security.TurbineUser;
34 import org.apache.turbine.om.security.User;
35 import org.apache.turbine.services.Service;
36 import org.apache.turbine.services.security.db.DBUserManager;
37 import org.apache.turbine.util.security.AccessControlList;
38 import org.apache.turbine.util.security.DataBackendException;
39 import org.apache.turbine.util.security.EntityExistsException;
40 import org.apache.turbine.util.security.GroupSet;
41 import org.apache.turbine.util.security.PasswordMismatchException;
42 import org.apache.turbine.util.security.PermissionSet;
43 import org.apache.turbine.util.security.RoleSet;
44 import org.apache.turbine.util.security.TurbineAccessControlList;
45 import org.apache.turbine.util.security.UnknownEntityException;
46
47 /***
48 * The Security Service manages Users, Groups Roles and Permissions in the
49 * system.
50 *
51 * The task performed by the security service include creation and removal of
52 * accounts, groups, roles, and permissions; assigning users roles in groups;
53 * assigning roles specific permissions and construction of objects
54 * representing these logical entities.
55 *
56 * <p> Because of pluggable nature of the Services, it is possible to create
57 * multiple implementations of SecurityService, for example employing database
58 * and directory server as the data backend.<br>
59 *
60 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
61 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
62 * @author <a href="mailto:marco@intermeta.de">Marco Knüttel</a>
63 * @version $Id: SecurityService.java 534527 2007-05-02 16:10:59Z tv $
64 */
65 public interface SecurityService
66 extends Service
67 {
68 /*** The name of the service */
69 String SERVICE_NAME = "SecurityService";
70
71 /***
72 * the key within services's properties for user implementation
73 * classname (user.class)
74 */
75 String USER_CLASS_KEY = "user.class";
76
77 /***
78 * the default implementation of User interface
79 * (org.apache.turbine.om.security.TurbineUser)
80 */
81 String USER_CLASS_DEFAULT
82 = TurbineUser.class.getName();
83
84 /***
85 * The key within services' properties for the GROUP
86 * implementation classname (group.class)
87 */
88 String GROUP_CLASS_KEY = "group.class";
89
90 /***
91 * The default implementation of the Group interface
92 * (org.apache.turbine.om.security.TurbineGroup)
93 */
94 String GROUP_CLASS_DEFAULT
95 = TurbineGroup.class.getName();
96
97 /***
98 * The key within services' properties for the PERMISSION
99 * implementation classname (permission.class)
100 */
101 String PERMISSION_CLASS_KEY = "permission.class";
102
103 /***
104 * The default implementation of the Permissions interface
105 * (org.apache.turbine.om.security.TurbinePermission)
106 */
107 String PERMISSION_CLASS_DEFAULT
108 = TurbinePermission.class.getName();
109
110 /***
111 * The key within services' properties for the ROLE
112 * implementation classname (role.class)
113 */
114 String ROLE_CLASS_KEY = "role.class";
115
116 /***
117 * The default implementation of the Role Interface
118 * (org.apache.turbine.om.security.TurbineRole)
119 */
120 String ROLE_CLASS_DEFAULT
121 = TurbineRole.class.getName();
122
123 /***
124 * The key within services' properties for the
125 * ACL implementation classname (acl.class)
126 */
127 String ACL_CLASS_KEY = "acl.class";
128
129 /***
130 * The default implementation of the Acl Interface
131 * (org.apache.turbine.util.security.TurbineAccessControlList)
132 */
133 String ACL_CLASS_DEFAULT
134 = TurbineAccessControlList.class.getName();
135
136 /***
137 * the key within services's properties for user implementation
138 * classname (user.manager)
139 */
140 String USER_MANAGER_KEY = "user.manager";
141
142 /***
143 * the default implementation of UserManager interface
144 * (org.apache.turbine.services.security.DBUserManager)
145 */
146 String USER_MANAGER_DEFAULT
147 = DBUserManager.class.getName();
148
149 /***
150 * the key within services's properties for secure passwords flag
151 * (secure.passwords)
152 */
153 String SECURE_PASSWORDS_KEY = "secure.passwords";
154
155 /*** the value of secure passwords flag (false) */
156 String SECURE_PASSWORDS_DEFAULT = "false";
157
158 /***
159 * the key within services's properties for secure passwords algorithm
160 * (secure.passwords.algorithm)
161 */
162 String SECURE_PASSWORDS_ALGORITHM_KEY
163 = "secure.passwords.algorithm";
164
165 /*** the default algorithm for password encryption (SHA) */
166 String SECURE_PASSWORDS_ALGORITHM_DEFAULT = "SHA";
167
168
169
170
171
172 /***
173 * Returns the Class object for the implementation of User interface
174 * used by the system.
175 *
176 * @return the implementation of User interface used by the system.
177 * @throws UnknownEntityException if the system's implementation of User
178 * interface could not be determined.
179 */
180 Class getUserClass()
181 throws UnknownEntityException;
182
183 /***
184 * Construct a blank User object.
185 *
186 * This method calls getUserClass, and then creates a new object using
187 * the default constructor.
188 *
189 * @return an object implementing User interface.
190 * @throws UnknownEntityException if the object could not be instantiated.
191 */
192 User getUserInstance()
193 throws UnknownEntityException;
194
195 /***
196 * Construct a blank User object.
197 *
198 * This method calls getUserClass, and then creates a new object using
199 * the default constructor.
200 *
201 * @param userName The name of the user.
202 *
203 * @return an object implementing User interface.
204 * @throws UnknownEntityException if the object could not be instantiated.
205 */
206 User getUserInstance(String userName)
207 throws UnknownEntityException;
208
209 /***
210 * Returns the Class object for the implementation of Group interface
211 * used by the system.
212 *
213 * @return the implementation of Group interface used by the system.
214 * @throws UnknownEntityException if the system's implementation of Group
215 * interface could not be determined.
216 */
217 Class getGroupClass()
218 throws UnknownEntityException;
219
220 /***
221 * Construct a blank Group object.
222 *
223 * This method calls getGroupClass, and then creates a new object using
224 * the default constructor.
225 *
226 * @return an object implementing Group interface.
227 * @throws UnknownEntityException if the object could not be instantiated.
228 */
229 Group getGroupInstance()
230 throws UnknownEntityException;
231
232 /***
233 * Construct a blank Group object.
234 *
235 * This method calls getGroupClass, and then creates a new object using
236 * the default constructor.
237 *
238 * @param groupName The name of the Group
239 *
240 * @return an object implementing Group interface.
241 * @throws UnknownEntityException if the object could not be instantiated.
242 */
243 Group getGroupInstance(String groupName)
244 throws UnknownEntityException;
245
246 /***
247 * Returns the Class object for the implementation of Permission interface
248 * used by the system.
249 *
250 * @return the implementation of Permission interface used by the system.
251 * @throws UnknownEntityException if the system's implementation of Permission
252 * interface could not be determined.
253 */
254 Class getPermissionClass()
255 throws UnknownEntityException;
256
257 /***
258 * Construct a blank Permission object.
259 *
260 * This method calls getPermissionClass, and then creates a new object using
261 * the default constructor.
262 *
263 * @return an object implementing Permission interface.
264 * @throws UnknownEntityException if the object could not be instantiated.
265 */
266 Permission getPermissionInstance()
267 throws UnknownEntityException;
268
269 /***
270 * Construct a blank Permission object.
271 *
272 * This method calls getPermissionClass, and then creates a new object using
273 * the default constructor.
274 *
275 * @param permName The name of the Permission
276 *
277 * @return an object implementing Permission interface.
278 * @throws UnknownEntityException if the object could not be instantiated.
279 */
280 Permission getPermissionInstance(String permName)
281 throws UnknownEntityException;
282
283 /***
284 * Returns the Class object for the implementation of Role interface
285 * used by the system.
286 *
287 * @return the implementation of Role interface used by the system.
288 * @throws UnknownEntityException if the system's implementation of Role
289 * interface could not be determined.
290 */
291 Class getRoleClass()
292 throws UnknownEntityException;
293
294 /***
295 * Construct a blank Role object.
296 *
297 * This method calls getRoleClass, and then creates a new object using
298 * the default constructor.
299 *
300 * @return an object implementing Role interface.
301 * @throws UnknownEntityException if the object could not be instantiated.
302 */
303 Role getRoleInstance()
304 throws UnknownEntityException;
305
306 /***
307 * Construct a blank Role object.
308 *
309 * This method calls getRoleClass, and then creates a new object using
310 * the default constructor.
311 *
312 * @param roleName The name of the Role
313 *
314 * @return an object implementing Role interface.
315 * @throws UnknownEntityException if the object could not be instantiated.
316 */
317 Role getRoleInstance(String roleName)
318 throws UnknownEntityException;
319
320 /***
321 * Returns the Class object for the implementation of AccessControlList interface
322 * used by the system.
323 *
324 * @return the implementation of AccessControlList interface used by the system.
325 * @throws UnknownEntityException if the system's implementation of AccessControlList
326 * interface could not be determined.
327 */
328 Class getAclClass()
329 throws UnknownEntityException;
330
331 /***
332 * Construct a new ACL object.
333 *
334 * This constructs a new ACL object from the configured class and
335 * initializes it with the supplied roles and permissions.
336 *
337 * @param roles The roles that this ACL should contain
338 * @param permissions The permissions for this ACL
339 *
340 * @return an object implementing ACL interface.
341 * @throws UnknownEntityException if the object could not be instantiated.
342 */
343 AccessControlList getAclInstance(Map roles, Map permissions)
344 throws UnknownEntityException;
345
346 /***
347 * Returns the configured UserManager.
348 *
349 * @return An UserManager object
350 */
351 UserManager getUserManager();
352
353 /***
354 * Configure a new user Manager.
355 *
356 * @param userManager An UserManager object
357 */
358 void setUserManager(UserManager userManager);
359
360 /***
361 * Check whether a specified user's account exists.
362 *
363 * The login name is used for looking up the account.
364 *
365 * @param userName The user to be checked.
366 * @return true if the specified account exists
367 * @throws DataBackendException if there was an error accessing the data
368 * backend.
369 */
370 boolean accountExists(String userName)
371 throws DataBackendException;
372
373 /***
374 * Check whether a specified user's account exists.
375 * An User object is used for looking up the account.
376 *
377 * @param user The user object to be checked.
378 * @return true if the specified account exists
379 * @throws DataBackendException if there was an error accessing the data
380 * backend.
381 */
382 boolean accountExists(User user)
383 throws DataBackendException;
384
385 /***
386 * Authenticates an user, and constructs an User object to represent
387 * him/her.
388 *
389 * @param username The user name.
390 * @param password The user password.
391 * @return An authenticated Turbine User.
392 * @throws DataBackendException if there was an error accessing the data
393 * backend.
394 * @throws UnknownEntityException if user account is not present.
395 * @throws PasswordMismatchException if the supplied password was incorrect.
396 */
397 User getAuthenticatedUser(String username, String password)
398 throws DataBackendException, UnknownEntityException,
399 PasswordMismatchException;
400
401 /***
402 * Constructs an User object to represent a registered user of the
403 * application.
404 *
405 * @param username The user name.
406 * @return A Turbine User.
407 * @throws DataBackendException if there was an error accessing the data
408 * backend.
409 * @throws UnknownEntityException if user account is not present.
410 */
411 User getUser(String username)
412 throws DataBackendException, UnknownEntityException;
413
414 /***
415 * Retrieve a set of users that meet the specified criteria.
416 *
417 * As the keys for the criteria, you should use the constants that
418 * are defined in {@link User} interface, plus the names
419 * of the custom attributes you added to your user representation
420 * in the data storage. Use verbatim names of the attributes -
421 * without table name prefix in case of DB implementation.
422 *
423 * @param criteria The criteria of selection.
424 * @return a List of users meeting the criteria.
425 * @throws DataBackendException if there is a problem accessing the
426 * storage.
427 * @deprecated Use <a href="#retrieveList">retrieveList</a> instead.
428 */
429 User[] getUsers(Criteria criteria)
430 throws DataBackendException;
431
432 /***
433 * Retrieve a set of users that meet the specified criteria.
434 *
435 * As the keys for the criteria, you should use the constants that
436 * are defined in {@link User} interface, plus the names
437 * of the custom attributes you added to your user representation
438 * in the data storage. Use verbatim names of the attributes -
439 * without table name prefix in case of Torque implementation.
440 *
441 * @param criteria The criteria of selection.
442 * @return a List of users meeting the criteria.
443 * @throws DataBackendException if there is a problem accessing the
444 * storage.
445 */
446 List getUserList(Criteria criteria)
447 throws DataBackendException;
448
449 /***
450 * Constructs an User object to represent an anonymous user of the
451 * application.
452 *
453 * @return An anonymous Turbine User.
454 * @throws UnknownEntityException if the anonymous User object couldn't be
455 * constructed.
456 */
457 User getAnonymousUser()
458 throws UnknownEntityException;
459
460 /***
461 * Checks whether a passed user object matches the anonymous user pattern
462 * according to the configured user manager
463 *
464 * @param An user object
465 *
466 * @return True if this is an anonymous user
467 *
468 */
469 boolean isAnonymousUser(User u);
470
471 /***
472 * Saves User's data in the permanent storage. The user account is required
473 * to exist in the storage.
474 *
475 * @param user the user object to save
476 * @throws UnknownEntityException if the user's account does not
477 * exist in the database.
478 * @throws DataBackendException if there is a problem accessing the storage.
479 */
480 void saveUser(User user)
481 throws UnknownEntityException, DataBackendException;
482
483 /***
484 * Saves User data when the session is unbound. The user account is required
485 * to exist in the storage.
486 *
487 * LastLogin, AccessCounter, persistent pull tools, and any data stored
488 * in the permData hashtable that is not mapped to a column will be saved.
489 *
490 * @exception UnknownEntityException if the user's account does not
491 * exist in the database.
492 * @exception DataBackendException if there is a problem accessing the
493 * storage.
494 */
495 void saveOnSessionUnbind(User user)
496 throws UnknownEntityException, DataBackendException;
497
498
499
500
501
502 /***
503 * Creates new user account with specified attributes.
504 *
505 * @param user the object describing account to be created.
506 * @param password The password to use.
507 * @throws DataBackendException if there was an error accessing the data
508 * backend.
509 * @throws EntityExistsException if the user account already exists.
510 */
511 void addUser(User user, String password)
512 throws DataBackendException, EntityExistsException;
513
514 /***
515 * Removes an user account from the system.
516 *
517 * @param user the object describing the account to be removed.
518 * @throws DataBackendException if there was an error accessing the data
519 * backend.
520 * @throws UnknownEntityException if the user account is not present.
521 */
522 void removeUser(User user)
523 throws DataBackendException, UnknownEntityException;
524
525
526
527
528
529 /***
530 * This method provides client-side encryption mechanism for passwords.
531 *
532 * This is an utility method that is used by other classes to maintain
533 * a consistent approach to encrypting password. The behavior of the
534 * method can be configured in service's properties.
535 *
536 * @param password the password to process
537 * @return processed password
538 */
539 String encryptPassword(String password);
540
541 /***
542 * This method provides client-side encryption mechanism for passwords.
543 *
544 * This is an utility method that is used by other classes to maintain
545 * a consistent approach to encrypting password. The behavior of the
546 * method can be configured in service's properties.
547 *
548 * Algorithms that must supply a salt for encryption
549 * can use this method to provide it.
550 *
551 * @param password the password to process
552 * @param salt Salt parameter for some crypto algorithms
553 *
554 * @return processed password
555 */
556 String encryptPassword(String password, String salt);
557
558 /***
559 * Checks if a supplied password matches the encrypted password
560 * when using the current encryption algorithm
561 *
562 * @param checkpw The clear text password supplied by the user
563 * @param encpw The current, encrypted password
564 *
565 * @return true if the password matches, else false
566 *
567 */
568 boolean checkPassword(String checkpw, String encpw);
569
570 /***
571 * Change the password for an User.
572 *
573 * @param user an User to change password for.
574 * @param oldPassword the current password supplied by the user.
575 * @param newPassword the current password requested by the user.
576 * @exception PasswordMismatchException if the supplied password was
577 * incorrect.
578 * @exception UnknownEntityException if the user's record does not
579 * exist in the database.
580 * @exception DataBackendException if there is a problem accessing the
581 * storage.
582 */
583 void changePassword(User user, String oldPassword,
584 String newPassword)
585 throws PasswordMismatchException, UnknownEntityException,
586 DataBackendException;
587
588 /***
589 * Forcibly sets new password for an User.
590 *
591 * This is supposed by the administrator to change the forgotten or
592 * compromised passwords. Certain implementatations of this feature
593 * would require administrative level access to the authenticating
594 * server / program.
595 *
596 * @param user an User to change password for.
597 * @param password the new password.
598 * @exception UnknownEntityException if the user's record does not
599 * exist in the database.
600 * @exception DataBackendException if there is a problem accessing the
601 * storage.
602 */
603 void forcePassword(User user, String password)
604 throws UnknownEntityException, DataBackendException;
605
606
607
608
609
610 /***
611 * Constructs an AccessControlList for a specific user.
612 *
613 * @param user the user for whom the AccessControlList are to be retrieved
614 * @return A new AccessControlList object.
615 * @throws DataBackendException if there was an error accessing the data backend.
616 * @throws UnknownEntityException if user account is not present.
617 */
618 AccessControlList getACL(User user)
619 throws DataBackendException, UnknownEntityException;
620
621 /***
622 * Retrieves all permissions associated with a role.
623 *
624 * @param role the role name, for which the permissions are to be retrieved.
625 * @return the permissions associated with the role
626 * @throws DataBackendException if there was an error accessing the data
627 * backend.
628 * @throws UnknownEntityException if the role is not present.
629 */
630 PermissionSet getPermissions(Role role)
631 throws DataBackendException, UnknownEntityException;
632
633
634
635
636
637 /***
638 * Grant an User a Role in a Group.
639 *
640 * @param user the user.
641 * @param group the group.
642 * @param role the role.
643 * @throws DataBackendException if there was an error accessing the data
644 * backend.
645 * @throws UnknownEntityException if user account, group or role is not
646 * present.
647 */
648 void grant(User user, Group group, Role role)
649 throws DataBackendException, UnknownEntityException;
650
651 /***
652 * Revoke a Role in a Group from an User.
653 *
654 * @param user the user.
655 * @param group the group.
656 * @param role the role.
657 * @throws DataBackendException if there was an error accessing the data
658 * backend.
659 * @throws UnknownEntityException if user account, group or role is not
660 * present.
661 */
662 void revoke(User user, Group group, Role role)
663 throws DataBackendException, UnknownEntityException;
664
665 /***
666 * Revokes all roles from an User.
667 *
668 * This method is used when deleting an account.
669 *
670 * @param user the User.
671 * @throws DataBackendException if there was an error accessing the data
672 * backend.
673 * @throws UnknownEntityException if the account is not present.
674 */
675 void revokeAll(User user)
676 throws DataBackendException, UnknownEntityException;
677
678 /***
679 * Grants a Role a Permission
680 *
681 * @param role the Role.
682 * @param permission the Permission.
683 * @throws DataBackendException if there was an error accessing the data
684 * backend.
685 * @throws UnknownEntityException if role or permission is not present.
686 */
687 void grant(Role role, Permission permission)
688 throws DataBackendException, UnknownEntityException;
689
690 /***
691 * Revokes a Permission from a Role.
692 *
693 * @param role the Role.
694 * @param permission the Permission.
695 * @throws DataBackendException if there was an error accessing the data
696 * backend.
697 * @throws UnknownEntityException if role or permission is not present.
698 */
699 void revoke(Role role, Permission permission)
700 throws DataBackendException, UnknownEntityException;
701
702 /***
703 * Revokes all permissions from a Role.
704 *
705 * This method is user when deleting a Role.
706 *
707 * @param role the Role
708 * @throws DataBackendException if there was an error accessing the data
709 * backend.
710 * @throws UnknownEntityException if the Role is not present.
711 */
712 void revokeAll(Role role)
713 throws DataBackendException, UnknownEntityException;
714
715
716
717
718
719 /***
720 * Provides a reference to the Group object that represents the
721 * <a href="#global">global group</a>.
722 *
723 * @return A Group object that represents the global group.
724 */
725 Group getGlobalGroup();
726
727 /***
728 * @deprecated Use getGroupInstance(String name) instead.
729 */
730 Group getNewGroup(String groupName);
731
732 /***
733 * @deprecated Use getRoleInstance(String name) instead.
734 */
735 Role getNewRole(String roleName);
736
737 /***
738 * @deprecated Use getPermissionInstance(String name) instead.
739 */
740 Permission getNewPermission(String permissionName);
741
742 /***
743 * Retrieve a Group object with specified name.
744 *
745 * @param name the name of the Group.
746 * @return an object representing the Group with specified name.
747 * @throws DataBackendException if there was an error accessing the data
748 * backend.
749 * @throws UnknownEntityException if the group does not exist.
750 * @deprecated Use <a href="#getGroupByName">getGroupByName</a> instead.
751 */
752 Group getGroup(String name)
753 throws DataBackendException, UnknownEntityException;
754
755 /***
756 * Retrieve a Group object with specified name.
757 *
758 * @param name the name of the Group.
759 * @return an object representing the Group with specified name.
760 * @throws DataBackendException if there was an error accessing the data
761 * backend.
762 * @throws UnknownEntityException if the group does not exist.
763 */
764 Group getGroupByName(String name)
765 throws DataBackendException, UnknownEntityException;
766
767 /***
768 * Retrieve a Group object with specified Id.
769 *
770 * @param name the name of the Group.
771 *
772 * @return an object representing the Group with specified name.
773 *
774 * @exception UnknownEntityException if the permission does not
775 * exist in the database.
776 * @exception DataBackendException if there is a problem accessing the
777 * storage.
778 */
779 Group getGroupById(int id)
780 throws DataBackendException,
781 UnknownEntityException;
782
783 /***
784 * Retrieve a Role object with specified name.
785 *
786 * @param name the name of the Role.
787 * @return an object representing the Role with specified name.
788 * @throws DataBackendException if there was an error accessing the data
789 * backend.
790 * @throws UnknownEntityException if the role does not exist.
791 * @deprecated Use <a href="#getRoleByName">getRoleByName</a> instead.
792 */
793 Role getRole(String name)
794 throws DataBackendException, UnknownEntityException;
795
796 /***
797 * Retrieve a Role object with specified name.
798 *
799 * @param name the name of the Role.
800 * @return an object representing the Role with specified name.
801 * @throws DataBackendException if there was an error accessing the data
802 * backend.
803 * @throws UnknownEntityException if the role does not exist.
804 */
805 Role getRoleByName(String name)
806 throws DataBackendException, UnknownEntityException;
807
808 /***
809 * Retrieve a Role object with specified Id.
810 *
811 * @param name the name of the Role.
812 *
813 * @return an object representing the Role with specified name.
814 *
815 * @exception UnknownEntityException if the permission does not
816 * exist in the database.
817 * @exception DataBackendException if there is a problem accessing the
818 * storage.
819 */
820 Role getRoleById(int id)
821 throws DataBackendException,
822 UnknownEntityException;
823
824 /***
825 * Retrieve a Permission object with specified name.
826 *
827 * @param name the name of the Permission.
828 * @return an object representing the Permission with specified name.
829 * @throws DataBackendException if there was an error accessing the data
830 * backend.
831 * @throws UnknownEntityException if the permission does not exist.
832 * @deprecated Use <a href="#getPermissionByName">getPermissionByName</a> instead.
833 */
834 Permission getPermission(String name)
835 throws DataBackendException, UnknownEntityException;
836
837 /***
838 * Retrieve a Permission object with specified name.
839 *
840 * @param name the name of the Permission.
841 * @return an object representing the Permission with specified name.
842 * @throws DataBackendException if there was an error accessing the data
843 * backend.
844 * @throws UnknownEntityException if the permission does not exist.
845 */
846 Permission getPermissionByName(String name)
847 throws DataBackendException, UnknownEntityException;
848
849 /***
850 * Retrieve a Permission object with specified Id.
851 *
852 * @param name the name of the Permission.
853 *
854 * @return an object representing the Permission with specified name.
855 *
856 * @exception UnknownEntityException if the permission does not
857 * exist in the database.
858 * @exception DataBackendException if there is a problem accessing the
859 * storage.
860 */
861 Permission getPermissionById(int id)
862 throws DataBackendException,
863 UnknownEntityException;
864
865 /***
866 * Retrieve a set of Groups that meet the specified Criteria.
867 *
868 * @param criteria a Criteria of Group selection.
869 * @return a set of Groups that meet the specified Criteria.
870 * @throws DataBackendException if there was an error accessing the data
871 * backend.
872 */
873 GroupSet getGroups(Criteria criteria)
874 throws DataBackendException;
875
876 /***
877 * Retrieve a set of Roles that meet the specified Criteria.
878 *
879 * @param criteria a Criteria of Roles selection.
880 * @return a set of Roles that meet the specified Criteria.
881 * @throws DataBackendException if there was an error accessing the data
882 * backend.
883 */
884 RoleSet getRoles(Criteria criteria)
885 throws DataBackendException;
886
887 /***
888 * Retrieve a set of Permissions that meet the specified Criteria.
889 *
890 * @param criteria a Criteria of Permissions selection.
891 * @return a set of Permissions that meet the specified Criteria.
892 * @throws DataBackendException if there was an error accessing the data
893 * backend.
894 */
895 PermissionSet getPermissions(Criteria criteria)
896 throws DataBackendException;
897
898 /***
899 * Retrieves all groups defined in the system.
900 *
901 * @return the names of all groups defined in the system.
902 * @throws DataBackendException if there was an error accessing the data
903 * backend.
904 */
905 GroupSet getAllGroups()
906 throws DataBackendException;
907
908 /***
909 * Retrieves all roles defined in the system.
910 *
911 * @return the names of all roles defined in the system.
912 * @throws DataBackendException if there was an error accessing the data
913 * backend.
914 */
915 RoleSet getAllRoles()
916 throws DataBackendException;
917
918 /***
919 * Retrieves all permissions defined in the system.
920 *
921 * @return the names of all roles defined in the system.
922 * @throws DataBackendException if there was an error accessing the data
923 * backend.
924 */
925 PermissionSet getAllPermissions()
926 throws DataBackendException;
927
928 /***
929 * Stores Group's attributes. The Groups is required to exist in the system.
930 *
931 * @param group The Group to be stored.
932 * @throws DataBackendException if there was an error accessing the data
933 * backend.
934 * @throws UnknownEntityException if the group does not exist.
935 */
936 void saveGroup(Group group)
937 throws DataBackendException, UnknownEntityException;
938
939 /***
940 * Stores Role's attributes. The Roles is required to exist in the system.
941 *
942 * @param role The Role to be stored.
943 * @throws DataBackendException if there was an error accessing the data
944 * backend.
945 * @throws UnknownEntityException if the role does not exist.
946 */
947 void saveRole(Role role)
948 throws DataBackendException, UnknownEntityException;
949
950 /***
951 * Stores Permission's attributes. The Permission is required to exist in
952 * the system.
953 *
954 * @param permission The Permission to be stored.
955 * @throws DataBackendException if there was an error accessing the data
956 * backend.
957 * @throws UnknownEntityException if the permission does not exist.
958 */
959 void savePermission(Permission permission)
960 throws DataBackendException, UnknownEntityException;
961
962
963
964
965
966 /***
967 * Creates a new group with specified attributes.
968 *
969 * @param group the object describing the group to be created.
970 * @return the new Group object.
971 * @throws DataBackendException if there was an error accessing the data
972 * backend.
973 * @throws EntityExistsException if the group already exists.
974 */
975 Group addGroup(Group group)
976 throws DataBackendException, EntityExistsException;
977
978 /***
979 * Creates a new role with specified attributes.
980 *
981 * @param role The object describing the role to be created.
982 * @return the new Role object.
983 * @throws DataBackendException if there was an error accessing the data
984 * backend.
985 * @throws EntityExistsException if the role already exists.
986 */
987 Role addRole(Role role)
988 throws DataBackendException, EntityExistsException;
989
990 /***
991 * Creates a new permission with specified attributes.
992 *
993 * @param permission The object describing the permission to be created.
994 * @return the new Permission object.
995 * @throws DataBackendException if there was an error accessing the data
996 * backend.
997 * @throws EntityExistsException if the permission already exists.
998 */
999 Permission addPermission(Permission permission)
1000 throws DataBackendException, EntityExistsException;
1001
1002 /***
1003 * Removes a Group from the system.
1004 *
1005 * @param group The object describing the group to be removed.
1006 * @throws DataBackendException if there was an error accessing the data
1007 * backend.
1008 * @throws UnknownEntityException if the group does not exist.
1009 */
1010 void removeGroup(Group group)
1011 throws DataBackendException, UnknownEntityException;
1012
1013 /***
1014 * Removes a Role from the system.
1015 *
1016 * @param role The object describing the role to be removed.
1017 * @throws DataBackendException if there was an error accessing the data
1018 * backend.
1019 * @throws UnknownEntityException if the role does not exist.
1020 */
1021 void removeRole(Role role)
1022 throws DataBackendException, UnknownEntityException;
1023
1024 /***
1025 * Removes a Permission from the system.
1026 *
1027 * @param permission The object describing the permission to be removed.
1028 * @throws DataBackendException if there was an error accessing the data
1029 * backend.
1030 * @throws UnknownEntityException if the permission does not exist.
1031 */
1032 void removePermission(Permission permission)
1033 throws DataBackendException, UnknownEntityException;
1034
1035 /***
1036 * Renames an existing Group.
1037 *
1038 * @param group The object describing the group to be renamed.
1039 * @param name the new name for the group.
1040 * @throws DataBackendException if there was an error accessing the data
1041 * backend.
1042 * @throws UnknownEntityException if the group does not exist.
1043 */
1044 void renameGroup(Group group, String name)
1045 throws DataBackendException, UnknownEntityException;
1046
1047 /***
1048 * Renames an existing Role.
1049 *
1050 * @param role The object describing the role to be renamed.
1051 * @param name the new name for the role.
1052 * @throws DataBackendException if there was an error accessing the data
1053 * backend.
1054 * @throws UnknownEntityException if the role does not exist.
1055 */
1056 void renameRole(Role role, String name)
1057 throws DataBackendException, UnknownEntityException;
1058
1059 /***
1060 * Renames an existing Permission.
1061 *
1062 * @param permission The object describing the permission to be renamed.
1063 * @param name the new name for the permission.
1064 * @throws DataBackendException if there was an error accessing the data
1065 * backend.
1066 * @throws UnknownEntityException if the permission does not exist.
1067 */
1068 void renamePermission(Permission permission, String name)
1069 throws DataBackendException, UnknownEntityException;
1070 }