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