001 package org.apache.turbine.services.security;
002
003
004 /*
005 * Licensed to the Apache Software Foundation (ASF) under one
006 * or more contributor license agreements. See the NOTICE file
007 * distributed with this work for additional information
008 * regarding copyright ownership. The ASF licenses this file
009 * to you under the Apache License, Version 2.0 (the
010 * "License"); you may not use this file except in compliance
011 * with the License. You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing,
016 * software distributed under the License is distributed on an
017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018 * KIND, either express or implied. See the License for the
019 * specific language governing permissions and limitations
020 * under the License.
021 */
022
023
024 import java.util.List;
025 import java.util.Map;
026
027 import org.apache.turbine.om.security.Group;
028 import org.apache.turbine.om.security.Permission;
029 import org.apache.turbine.om.security.Role;
030 import org.apache.turbine.om.security.TurbineGroup;
031 import org.apache.turbine.om.security.TurbinePermission;
032 import org.apache.turbine.om.security.TurbineRole;
033 import org.apache.turbine.om.security.TurbineUser;
034 import org.apache.turbine.om.security.User;
035 import org.apache.turbine.services.Service;
036 import org.apache.turbine.services.security.passive.PassiveUserManager;
037 import org.apache.turbine.util.security.AccessControlList;
038 import org.apache.turbine.util.security.DataBackendException;
039 import org.apache.turbine.util.security.EntityExistsException;
040 import org.apache.turbine.util.security.GroupSet;
041 import org.apache.turbine.util.security.PasswordMismatchException;
042 import org.apache.turbine.util.security.PermissionSet;
043 import org.apache.turbine.util.security.RoleSet;
044 import org.apache.turbine.util.security.TurbineAccessControlList;
045 import org.apache.turbine.util.security.UnknownEntityException;
046
047 /**
048 * The Security Service manages Users, Groups Roles and Permissions in the
049 * system.
050 *
051 * The task performed by the security service include creation and removal of
052 * accounts, groups, roles, and permissions; assigning users roles in groups;
053 * assigning roles specific permissions and construction of objects
054 * representing these logical entities.
055 *
056 * <p> Because of pluggable nature of the Services, it is possible to create
057 * multiple implementations of SecurityService, for example employing database
058 * and directory server as the data backend.<br>
059 *
060 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
061 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
062 * @author <a href="mailto:marco@intermeta.de">Marco Knüttel</a>
063 * @version $Id: SecurityService.java 1096130 2011-04-23 10:37:19Z ludwig $
064 */
065 public interface SecurityService
066 extends Service
067 {
068 /** The name of the service */
069 String SERVICE_NAME = "SecurityService";
070
071 /**
072 * the key within services's properties for user implementation
073 * classname (user.class)
074 */
075 String USER_CLASS_KEY = "user.class";
076
077 /**
078 * the default implementation of User interface
079 * (org.apache.turbine.om.security.TurbineUser)
080 */
081 String USER_CLASS_DEFAULT
082 = TurbineUser.class.getName();
083
084 /**
085 * The key within services' properties for the GROUP
086 * implementation classname (group.class)
087 */
088 String GROUP_CLASS_KEY = "group.class";
089
090 /**
091 * The default implementation of the Group interface
092 * (org.apache.turbine.om.security.TurbineGroup)
093 */
094 String GROUP_CLASS_DEFAULT
095 = TurbineGroup.class.getName();
096
097 /**
098 * The key within services' properties for the PERMISSION
099 * 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.passive.PassiveUserManager)
145 */
146 String USER_MANAGER_DEFAULT
147 = PassiveUserManager.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 Management of User objects
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 Torque 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 */
428 List getUserList(Object criteria)
429 throws DataBackendException;
430
431 /**
432 * Constructs an User object to represent an anonymous user of the
433 * application.
434 *
435 * @return An anonymous Turbine User.
436 * @throws UnknownEntityException if the anonymous User object couldn't be
437 * constructed.
438 */
439 User getAnonymousUser()
440 throws UnknownEntityException;
441
442 /**
443 * Checks whether a passed user object matches the anonymous user pattern
444 * according to the configured user manager
445 *
446 * @param An user object
447 *
448 * @return True if this is an anonymous user
449 *
450 */
451 boolean isAnonymousUser(User u);
452
453 /**
454 * Saves User's data in the permanent storage. The user account is required
455 * to exist in the storage.
456 *
457 * @param user the user object to save
458 * @throws UnknownEntityException if the user's account does not
459 * exist in the database.
460 * @throws DataBackendException if there is a problem accessing the storage.
461 */
462 void saveUser(User user)
463 throws UnknownEntityException, DataBackendException;
464
465 /**
466 * Saves User data when the session is unbound. The user account is required
467 * to exist in the storage.
468 *
469 * LastLogin, AccessCounter, persistent pull tools, and any data stored
470 * in the permData hashtable that is not mapped to a column will be saved.
471 *
472 * @exception UnknownEntityException if the user's account does not
473 * exist in the database.
474 * @exception DataBackendException if there is a problem accessing the
475 * storage.
476 */
477 void saveOnSessionUnbind(User user)
478 throws UnknownEntityException, DataBackendException;
479
480 /*-----------------------------------------------------------------------
481 Account management
482 -----------------------------------------------------------------------*/
483
484 /**
485 * Creates new user account with specified attributes.
486 *
487 * @param user the object describing account to be created.
488 * @param password The password to use.
489 * @throws DataBackendException if there was an error accessing the data
490 * backend.
491 * @throws EntityExistsException if the user account already exists.
492 */
493 void addUser(User user, String password)
494 throws DataBackendException, EntityExistsException;
495
496 /**
497 * Removes an user account from the system.
498 *
499 * @param user the object describing the account to be removed.
500 * @throws DataBackendException if there was an error accessing the data
501 * backend.
502 * @throws UnknownEntityException if the user account is not present.
503 */
504 void removeUser(User user)
505 throws DataBackendException, UnknownEntityException;
506
507 /*-----------------------------------------------------------------------
508 Management of passwords
509 -----------------------------------------------------------------------*/
510
511 /**
512 * This method provides client-side encryption mechanism for passwords.
513 *
514 * This is an utility method that is used by other classes to maintain
515 * a consistent approach to encrypting password. The behavior of the
516 * method can be configured in service's properties.
517 *
518 * @param password the password to process
519 * @return processed password
520 */
521 String encryptPassword(String password);
522
523 /**
524 * This method provides client-side encryption mechanism for passwords.
525 *
526 * This is an utility method that is used by other classes to maintain
527 * a consistent approach to encrypting password. The behavior of the
528 * method can be configured in service's properties.
529 *
530 * Algorithms that must supply a salt for encryption
531 * can use this method to provide it.
532 *
533 * @param password the password to process
534 * @param salt Salt parameter for some crypto algorithms
535 *
536 * @return processed password
537 */
538 String encryptPassword(String password, String salt);
539
540 /**
541 * Checks if a supplied password matches the encrypted password
542 * when using the current encryption algorithm
543 *
544 * @param checkpw The clear text password supplied by the user
545 * @param encpw The current, encrypted password
546 *
547 * @return true if the password matches, else false
548 *
549 */
550 boolean checkPassword(String checkpw, String encpw);
551
552 /**
553 * Change the password for an User.
554 *
555 * @param user an User to change password for.
556 * @param oldPassword the current password supplied by the user.
557 * @param newPassword the current password requested by the user.
558 * @exception PasswordMismatchException if the supplied password was
559 * incorrect.
560 * @exception UnknownEntityException if the user's record does not
561 * exist in the database.
562 * @exception DataBackendException if there is a problem accessing the
563 * storage.
564 */
565 void changePassword(User user, String oldPassword,
566 String newPassword)
567 throws PasswordMismatchException, UnknownEntityException,
568 DataBackendException;
569
570 /**
571 * Forcibly sets new password for an User.
572 *
573 * This is supposed by the administrator to change the forgotten or
574 * compromised passwords. Certain implementatations of this feature
575 * would require administrative level access to the authenticating
576 * server / program.
577 *
578 * @param user an User to change password for.
579 * @param password the new password.
580 * @exception UnknownEntityException if the user's record does not
581 * exist in the database.
582 * @exception DataBackendException if there is a problem accessing the
583 * storage.
584 */
585 void forcePassword(User user, String password)
586 throws UnknownEntityException, DataBackendException;
587
588 /*-----------------------------------------------------------------------
589 Retrieval of security information
590 -----------------------------------------------------------------------*/
591
592 /**
593 * Constructs an AccessControlList for a specific user.
594 *
595 * @param user the user for whom the AccessControlList are to be retrieved
596 * @return A new AccessControlList object.
597 * @throws DataBackendException if there was an error accessing the data backend.
598 * @throws UnknownEntityException if user account is not present.
599 */
600 AccessControlList getACL(User user)
601 throws DataBackendException, UnknownEntityException;
602
603 /**
604 * Retrieves all permissions associated with a role.
605 *
606 * @param role the role name, for which the permissions are to be retrieved.
607 * @return the permissions associated with the role
608 * @throws DataBackendException if there was an error accessing the data
609 * backend.
610 * @throws UnknownEntityException if the role is not present.
611 */
612 PermissionSet getPermissions(Role role)
613 throws DataBackendException, UnknownEntityException;
614
615 /*-----------------------------------------------------------------------
616 Manipulation of security information
617 -----------------------------------------------------------------------*/
618
619 /**
620 * Grant an User a Role in a Group.
621 *
622 * @param user the user.
623 * @param group the group.
624 * @param role the role.
625 * @throws DataBackendException if there was an error accessing the data
626 * backend.
627 * @throws UnknownEntityException if user account, group or role is not
628 * present.
629 */
630 void grant(User user, Group group, Role role)
631 throws DataBackendException, UnknownEntityException;
632
633 /**
634 * Revoke a Role in a Group from an User.
635 *
636 * @param user the user.
637 * @param group the group.
638 * @param role the role.
639 * @throws DataBackendException if there was an error accessing the data
640 * backend.
641 * @throws UnknownEntityException if user account, group or role is not
642 * present.
643 */
644 void revoke(User user, Group group, Role role)
645 throws DataBackendException, UnknownEntityException;
646
647 /**
648 * Revokes all roles from an User.
649 *
650 * This method is used when deleting an account.
651 *
652 * @param user the User.
653 * @throws DataBackendException if there was an error accessing the data
654 * backend.
655 * @throws UnknownEntityException if the account is not present.
656 */
657 void revokeAll(User user)
658 throws DataBackendException, UnknownEntityException;
659
660 /**
661 * Grants a Role a Permission
662 *
663 * @param role the Role.
664 * @param permission the Permission.
665 * @throws DataBackendException if there was an error accessing the data
666 * backend.
667 * @throws UnknownEntityException if role or permission is not present.
668 */
669 void grant(Role role, Permission permission)
670 throws DataBackendException, UnknownEntityException;
671
672 /**
673 * Revokes a Permission from a Role.
674 *
675 * @param role the Role.
676 * @param permission the Permission.
677 * @throws DataBackendException if there was an error accessing the data
678 * backend.
679 * @throws UnknownEntityException if role or permission is not present.
680 */
681 void revoke(Role role, Permission permission)
682 throws DataBackendException, UnknownEntityException;
683
684 /**
685 * Revokes all permissions from a Role.
686 *
687 * This method is user when deleting a Role.
688 *
689 * @param role the Role
690 * @throws DataBackendException if there was an error accessing the data
691 * backend.
692 * @throws UnknownEntityException if the Role is not present.
693 */
694 void revokeAll(Role role)
695 throws DataBackendException, UnknownEntityException;
696
697 /*-----------------------------------------------------------------------
698 Retrieval & storage of SecurityObjects
699 -----------------------------------------------------------------------*/
700
701 /**
702 * Provides a reference to the Group object that represents the
703 * <a href="#global">global group</a>.
704 *
705 * @return A Group object that represents the global group.
706 */
707 Group getGlobalGroup();
708
709 /**
710 * Retrieve a Group object with specified name.
711 *
712 * @param name the name of the Group.
713 * @return an object representing the Group with specified name.
714 * @throws DataBackendException if there was an error accessing the data
715 * backend.
716 * @throws UnknownEntityException if the group does not exist.
717 */
718 Group getGroupByName(String name)
719 throws DataBackendException, UnknownEntityException;
720
721 /**
722 * Retrieve a Group object with specified Id.
723 *
724 * @param name the name of the Group.
725 *
726 * @return an object representing the Group with specified name.
727 *
728 * @exception UnknownEntityException if the permission does not
729 * exist in the database.
730 * @exception DataBackendException if there is a problem accessing the
731 * storage.
732 */
733 Group getGroupById(int id)
734 throws DataBackendException,
735 UnknownEntityException;
736
737 /**
738 * Retrieve a Role object with specified name.
739 *
740 * @param name the name of the Role.
741 * @return an object representing the Role with specified name.
742 * @throws DataBackendException if there was an error accessing the data
743 * backend.
744 * @throws UnknownEntityException if the role does not exist.
745 */
746 Role getRoleByName(String name)
747 throws DataBackendException, UnknownEntityException;
748
749 /**
750 * Retrieve a Role object with specified Id.
751 *
752 * @param name the name of the Role.
753 *
754 * @return an object representing the Role with specified name.
755 *
756 * @exception UnknownEntityException if the permission does not
757 * exist in the database.
758 * @exception DataBackendException if there is a problem accessing the
759 * storage.
760 */
761 Role getRoleById(int id)
762 throws DataBackendException,
763 UnknownEntityException;
764
765 /**
766 * Retrieve a Permission object with specified name.
767 *
768 * @param name the name of the Permission.
769 * @return an object representing the Permission with specified name.
770 * @throws DataBackendException if there was an error accessing the data
771 * backend.
772 * @throws UnknownEntityException if the permission does not exist.
773 */
774 Permission getPermissionByName(String name)
775 throws DataBackendException, UnknownEntityException;
776
777 /**
778 * Retrieve a Permission object with specified Id.
779 *
780 * @param name the name of the Permission.
781 *
782 * @return an object representing the Permission with specified name.
783 *
784 * @exception UnknownEntityException if the permission does not
785 * exist in the database.
786 * @exception DataBackendException if there is a problem accessing the
787 * storage.
788 */
789 Permission getPermissionById(int id)
790 throws DataBackendException,
791 UnknownEntityException;
792
793 /**
794 * Retrieve a set of Groups that meet the specified Criteria.
795 *
796 * @param criteria a Criteria of Group selection.
797 * @return a set of Groups that meet the specified Criteria.
798 * @throws DataBackendException if there was an error accessing the data
799 * backend.
800 */
801 GroupSet getGroups(Object criteria)
802 throws DataBackendException;
803
804 /**
805 * Retrieve a set of Roles that meet the specified Criteria.
806 *
807 * @param criteria a Criteria of Roles selection.
808 * @return a set of Roles that meet the specified Criteria.
809 * @throws DataBackendException if there was an error accessing the data
810 * backend.
811 */
812 RoleSet getRoles(Object criteria)
813 throws DataBackendException;
814
815 /**
816 * Retrieve a set of Permissions that meet the specified Criteria.
817 *
818 * @param criteria a Criteria of Permissions selection.
819 * @return a set of Permissions that meet the specified Criteria.
820 * @throws DataBackendException if there was an error accessing the data
821 * backend.
822 */
823 PermissionSet getPermissions(Object criteria)
824 throws DataBackendException;
825
826 /**
827 * Retrieves all groups defined in the system.
828 *
829 * @return the names of all groups defined in the system.
830 * @throws DataBackendException if there was an error accessing the data
831 * backend.
832 */
833 GroupSet getAllGroups()
834 throws DataBackendException;
835
836 /**
837 * Retrieves all roles defined in the system.
838 *
839 * @return the names of all roles defined in the system.
840 * @throws DataBackendException if there was an error accessing the data
841 * backend.
842 */
843 RoleSet getAllRoles()
844 throws DataBackendException;
845
846 /**
847 * Retrieves all permissions defined in the system.
848 *
849 * @return the names of all roles defined in the system.
850 * @throws DataBackendException if there was an error accessing the data
851 * backend.
852 */
853 PermissionSet getAllPermissions()
854 throws DataBackendException;
855
856 /**
857 * Stores Group's attributes. The Groups is required to exist in the system.
858 *
859 * @param group The Group to be stored.
860 * @throws DataBackendException if there was an error accessing the data
861 * backend.
862 * @throws UnknownEntityException if the group does not exist.
863 */
864 void saveGroup(Group group)
865 throws DataBackendException, UnknownEntityException;
866
867 /**
868 * Stores Role's attributes. The Roles is required to exist in the system.
869 *
870 * @param role The Role to be stored.
871 * @throws DataBackendException if there was an error accessing the data
872 * backend.
873 * @throws UnknownEntityException if the role does not exist.
874 */
875 void saveRole(Role role)
876 throws DataBackendException, UnknownEntityException;
877
878 /**
879 * Stores Permission's attributes. The Permission is required to exist in
880 * the system.
881 *
882 * @param permission The Permission to be stored.
883 * @throws DataBackendException if there was an error accessing the data
884 * backend.
885 * @throws UnknownEntityException if the permission does not exist.
886 */
887 void savePermission(Permission permission)
888 throws DataBackendException, UnknownEntityException;
889
890 /*-----------------------------------------------------------------------
891 Group/Role/Permission management
892 -----------------------------------------------------------------------*/
893
894 /**
895 * Creates a new group with specified attributes.
896 *
897 * @param group the object describing the group to be created.
898 * @return the new Group object.
899 * @throws DataBackendException if there was an error accessing the data
900 * backend.
901 * @throws EntityExistsException if the group already exists.
902 */
903 Group addGroup(Group group)
904 throws DataBackendException, EntityExistsException;
905
906 /**
907 * Creates a new role with specified attributes.
908 *
909 * @param role The object describing the role to be created.
910 * @return the new Role object.
911 * @throws DataBackendException if there was an error accessing the data
912 * backend.
913 * @throws EntityExistsException if the role already exists.
914 */
915 Role addRole(Role role)
916 throws DataBackendException, EntityExistsException;
917
918 /**
919 * Creates a new permission with specified attributes.
920 *
921 * @param permission The object describing the permission to be created.
922 * @return the new Permission object.
923 * @throws DataBackendException if there was an error accessing the data
924 * backend.
925 * @throws EntityExistsException if the permission already exists.
926 */
927 Permission addPermission(Permission permission)
928 throws DataBackendException, EntityExistsException;
929
930 /**
931 * Removes a Group from the system.
932 *
933 * @param group The object describing the group to be removed.
934 * @throws DataBackendException if there was an error accessing the data
935 * backend.
936 * @throws UnknownEntityException if the group does not exist.
937 */
938 void removeGroup(Group group)
939 throws DataBackendException, UnknownEntityException;
940
941 /**
942 * Removes a Role from the system.
943 *
944 * @param role The object describing the role to be removed.
945 * @throws DataBackendException if there was an error accessing the data
946 * backend.
947 * @throws UnknownEntityException if the role does not exist.
948 */
949 void removeRole(Role role)
950 throws DataBackendException, UnknownEntityException;
951
952 /**
953 * Removes a Permission from the system.
954 *
955 * @param permission The object describing the permission to be removed.
956 * @throws DataBackendException if there was an error accessing the data
957 * backend.
958 * @throws UnknownEntityException if the permission does not exist.
959 */
960 void removePermission(Permission permission)
961 throws DataBackendException, UnknownEntityException;
962
963 /**
964 * Renames an existing Group.
965 *
966 * @param group The object describing the group to be renamed.
967 * @param name the new name for the group.
968 * @throws DataBackendException if there was an error accessing the data
969 * backend.
970 * @throws UnknownEntityException if the group does not exist.
971 */
972 void renameGroup(Group group, String name)
973 throws DataBackendException, UnknownEntityException;
974
975 /**
976 * Renames an existing Role.
977 *
978 * @param role The object describing the role to be renamed.
979 * @param name the new name for the role.
980 * @throws DataBackendException if there was an error accessing the data
981 * backend.
982 * @throws UnknownEntityException if the role does not exist.
983 */
984 void renameRole(Role role, String name)
985 throws DataBackendException, UnknownEntityException;
986
987 /**
988 * Renames an existing Permission.
989 *
990 * @param permission The object describing the permission to be renamed.
991 * @param name the new name for the permission.
992 * @throws DataBackendException if there was an error accessing the data
993 * backend.
994 * @throws UnknownEntityException if the permission does not exist.
995 */
996 void renamePermission(Permission permission, String name)
997 throws DataBackendException, UnknownEntityException;
998 }