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