View Javadoc

1   package org.apache.turbine.services.security;
2   
3   
4   /*
5    * Licensed to the Apache Software Foundation (ASF) under one
6    * or more contributor license agreements.  See the NOTICE file
7    * distributed with this work for additional information
8    * regarding copyright ownership.  The ASF licenses this file
9    * to you under the Apache License, Version 2.0 (the
10   * "License"); you may not use this file except in compliance
11   * with the License.  You may obtain a copy of the License at
12   *
13   *   http://www.apache.org/licenses/LICENSE-2.0
14   *
15   * Unless required by applicable law or agreed to in writing,
16   * software distributed under the License is distributed on an
17   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18   * KIND, either express or implied.  See the License for the
19   * specific language governing permissions and limitations
20   * under the License.
21   */
22  
23  
24  import java.util.List;
25  import java.util.Map;
26  
27  import org.apache.turbine.om.security.Group;
28  import org.apache.turbine.om.security.Permission;
29  import org.apache.turbine.om.security.Role;
30  import org.apache.turbine.om.security.TurbineGroup;
31  import org.apache.turbine.om.security.TurbinePermission;
32  import org.apache.turbine.om.security.TurbineRole;
33  import org.apache.turbine.om.security.TurbineUser;
34  import org.apache.turbine.om.security.User;
35  import org.apache.turbine.services.Service;
36  import org.apache.turbine.services.security.passive.PassiveUserManager;
37  import org.apache.turbine.util.security.AccessControlList;
38  import org.apache.turbine.util.security.DataBackendException;
39  import org.apache.turbine.util.security.EntityExistsException;
40  import org.apache.turbine.util.security.GroupSet;
41  import org.apache.turbine.util.security.PasswordMismatchException;
42  import org.apache.turbine.util.security.PermissionSet;
43  import org.apache.turbine.util.security.RoleSet;
44  import org.apache.turbine.util.security.TurbineAccessControlList;
45  import org.apache.turbine.util.security.UnknownEntityException;
46  
47  /**
48   * The Security Service manages Users, Groups Roles and Permissions in the
49   * system.
50   *
51   * The task performed by the security service include creation and removal of
52   * accounts, groups, roles, and permissions; assigning users roles in groups;
53   * assigning roles specific permissions and construction of objects
54   * representing these logical entities.
55   *
56   * <p> Because of pluggable nature of the Services, it is possible to create
57   * multiple implementations of SecurityService, for example employing database
58   * and directory server as the data backend.<br>
59   *
60   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
61   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
62   * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
63   * @version $Id: SecurityService.java 1096130 2011-04-23 10:37:19Z ludwig $
64   */
65  public interface SecurityService
66          extends Service
67  {
68      /** The name of the service */
69      String SERVICE_NAME = "SecurityService";
70  
71      /**
72       * the key within services's properties for user implementation
73       * classname (user.class)
74       */
75      String USER_CLASS_KEY = "user.class";
76  
77      /**
78       * the default implementation of User interface
79       * (org.apache.turbine.om.security.TurbineUser)
80       */
81      String USER_CLASS_DEFAULT
82              = TurbineUser.class.getName();
83  
84      /**
85       * The key within services' properties for the GROUP
86       * implementation classname (group.class)
87       */
88      String GROUP_CLASS_KEY = "group.class";
89  
90      /**
91       * The default implementation of the Group interface
92       * (org.apache.turbine.om.security.TurbineGroup)
93       */
94      String GROUP_CLASS_DEFAULT
95              = TurbineGroup.class.getName();
96  
97      /**
98       * The key within services' properties for the PERMISSION
99       * implementation classname (permission.class)
100      */
101     String PERMISSION_CLASS_KEY = "permission.class";
102 
103     /**
104      * The default implementation of the Permissions interface
105      * (org.apache.turbine.om.security.TurbinePermission)
106      */
107     String PERMISSION_CLASS_DEFAULT
108             = TurbinePermission.class.getName();
109 
110     /**
111      * The key within services' properties for the ROLE
112      * implementation classname (role.class)
113      */
114     String ROLE_CLASS_KEY = "role.class";
115 
116     /**
117      * The default implementation of the Role Interface
118      * (org.apache.turbine.om.security.TurbineRole)
119      */
120     String ROLE_CLASS_DEFAULT
121             = TurbineRole.class.getName();
122 
123     /**
124      * The key within services' properties for the
125      * ACL implementation classname (acl.class)
126      */
127     String ACL_CLASS_KEY = "acl.class";
128 
129     /**
130      * The default implementation of the Acl Interface
131      * (org.apache.turbine.util.security.TurbineAccessControlList)
132      */
133     String ACL_CLASS_DEFAULT
134             = TurbineAccessControlList.class.getName();
135 
136     /**
137      * the key within services's properties for user implementation
138      * classname (user.manager)
139      */
140     String USER_MANAGER_KEY = "user.manager";
141 
142     /**
143      * the default implementation of UserManager interface
144      * (org.apache.turbine.services.security.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 }