View Javadoc

1   package org.apache.turbine.services.security;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.util.List;
23  import java.util.Map;
24  
25  import org.apache.torque.util.Criteria;
26  
27  import org.apache.turbine.om.security.Group;
28  import org.apache.turbine.om.security.Permission;
29  import org.apache.turbine.om.security.Role;
30  import org.apache.turbine.om.security.TurbineGroup;
31  import org.apache.turbine.om.security.TurbinePermission;
32  import org.apache.turbine.om.security.TurbineRole;
33  import org.apache.turbine.om.security.TurbineUser;
34  import org.apache.turbine.om.security.User;
35  import org.apache.turbine.services.Service;
36  import org.apache.turbine.services.security.db.DBUserManager;
37  import org.apache.turbine.util.security.AccessControlList;
38  import org.apache.turbine.util.security.DataBackendException;
39  import org.apache.turbine.util.security.EntityExistsException;
40  import org.apache.turbine.util.security.GroupSet;
41  import org.apache.turbine.util.security.PasswordMismatchException;
42  import org.apache.turbine.util.security.PermissionSet;
43  import org.apache.turbine.util.security.RoleSet;
44  import org.apache.turbine.util.security.TurbineAccessControlList;
45  import org.apache.turbine.util.security.UnknownEntityException;
46  
47  /***
48   * The Security Service manages Users, Groups Roles and Permissions in the
49   * system.
50   *
51   * The task performed by the security service include creation and removal of
52   * accounts, groups, roles, and permissions; assigning users roles in groups;
53   * assigning roles specific permissions and construction of objects
54   * representing these logical entities.
55   *
56   * <p> Because of pluggable nature of the Services, it is possible to create
57   * multiple implementations of SecurityService, for example employing database
58   * and directory server as the data backend.<br>
59   *
60   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
61   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
62   * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
63   * @version $Id: SecurityService.java 534527 2007-05-02 16:10:59Z tv $
64   */
65  public interface SecurityService
66          extends Service
67  {
68      /*** The name of the service */
69      String SERVICE_NAME = "SecurityService";
70  
71      /***
72       * the key within services's properties for user implementation
73       * classname (user.class)
74       */
75      String USER_CLASS_KEY = "user.class";
76  
77      /***
78       * the default implementation of User interface
79       * (org.apache.turbine.om.security.TurbineUser)
80       */
81      String USER_CLASS_DEFAULT
82              = TurbineUser.class.getName();
83  
84      /***
85       * The key within services' properties for the GROUP
86       * implementation classname (group.class)
87       */
88      String GROUP_CLASS_KEY = "group.class";
89  
90      /***
91       * The default implementation of the Group interface
92       * (org.apache.turbine.om.security.TurbineGroup)
93       */
94      String GROUP_CLASS_DEFAULT
95              = TurbineGroup.class.getName();
96  
97      /***
98       * The key within services' properties for the PERMISSION
99       * implementation classname (permission.class)
100      */
101     String PERMISSION_CLASS_KEY = "permission.class";
102 
103     /***
104      * The default implementation of the Permissions interface
105      * (org.apache.turbine.om.security.TurbinePermission)
106      */
107     String PERMISSION_CLASS_DEFAULT
108             = TurbinePermission.class.getName();
109 
110     /***
111      * The key within services' properties for the ROLE
112      * implementation classname (role.class)
113      */
114     String ROLE_CLASS_KEY = "role.class";
115 
116     /***
117      * The default implementation of the Role Interface
118      * (org.apache.turbine.om.security.TurbineRole)
119      */
120     String ROLE_CLASS_DEFAULT
121             = TurbineRole.class.getName();
122 
123     /***
124      * The key within services' properties for the
125      * ACL implementation classname (acl.class)
126      */
127     String ACL_CLASS_KEY = "acl.class";
128 
129     /***
130      * The default implementation of the Acl Interface
131      * (org.apache.turbine.util.security.TurbineAccessControlList)
132      */
133     String ACL_CLASS_DEFAULT
134             = TurbineAccessControlList.class.getName();
135 
136     /***
137      * the key within services's properties for user implementation
138      * classname (user.manager)
139      */
140     String USER_MANAGER_KEY = "user.manager";
141 
142     /***
143      * the default implementation of UserManager interface
144      * (org.apache.turbine.services.security.DBUserManager)
145      */
146     String USER_MANAGER_DEFAULT
147             = DBUserManager.class.getName();
148 
149     /***
150      * the key within services's properties for secure passwords flag
151      * (secure.passwords)
152      */
153     String SECURE_PASSWORDS_KEY = "secure.passwords";
154 
155     /*** the value of secure passwords flag (false) */
156     String SECURE_PASSWORDS_DEFAULT = "false";
157 
158     /***
159      * the key within services's properties for secure passwords algorithm
160      * (secure.passwords.algorithm)
161      */
162     String SECURE_PASSWORDS_ALGORITHM_KEY
163             = "secure.passwords.algorithm";
164 
165     /*** the default algorithm for password encryption (SHA) */
166     String SECURE_PASSWORDS_ALGORITHM_DEFAULT = "SHA";
167 
168     /*-----------------------------------------------------------------------
169       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 DB implementation.
422      *
423      * @param criteria The criteria of selection.
424      * @return a List of users meeting the criteria.
425      * @throws DataBackendException if there is a problem accessing the
426      *         storage.
427      * @deprecated Use <a href="#retrieveList">retrieveList</a> instead.
428      */
429     User[] getUsers(Criteria criteria)
430             throws DataBackendException;
431 
432     /***
433      * Retrieve a set of users that meet the specified criteria.
434      *
435      * As the keys for the criteria, you should use the constants that
436      * are defined in {@link User} interface, plus the names
437      * of the custom attributes you added to your user representation
438      * in the data storage. Use verbatim names of the attributes -
439      * without table name prefix in case of Torque implementation.
440      *
441      * @param criteria The criteria of selection.
442      * @return a List of users meeting the criteria.
443      * @throws DataBackendException if there is a problem accessing the
444      *         storage.
445      */
446     List getUserList(Criteria criteria)
447             throws DataBackendException;
448 
449     /***
450      * Constructs an User object to represent an anonymous user of the
451      * application.
452      *
453      * @return An anonymous Turbine User.
454      * @throws UnknownEntityException if the anonymous User object couldn't be
455      *         constructed.
456      */
457     User getAnonymousUser()
458             throws UnknownEntityException;
459 
460     /***
461      * Checks whether a passed user object matches the anonymous user pattern
462      * according to the configured user manager
463      *
464      * @param An user object
465      *
466      * @return True if this is an anonymous user
467      *
468      */
469     boolean isAnonymousUser(User u);
470 
471     /***
472      * Saves User's data in the permanent storage. The user account is required
473      * to exist in the storage.
474      *
475      * @param user the user object to save
476      * @throws UnknownEntityException if the user's account does not
477      *         exist in the database.
478      * @throws DataBackendException if there is a problem accessing the storage.
479      */
480     void saveUser(User user)
481             throws UnknownEntityException, DataBackendException;
482 
483     /***
484      * Saves User data when the session is unbound. The user account is required
485      * to exist in the storage.
486      *
487      * LastLogin, AccessCounter, persistent pull tools, and any data stored
488      * in the permData hashtable that is not mapped to a column will be saved.
489      *
490      * @exception UnknownEntityException if the user's account does not
491      *            exist in the database.
492      * @exception DataBackendException if there is a problem accessing the
493      *            storage.
494      */
495     void saveOnSessionUnbind(User user)
496             throws UnknownEntityException, DataBackendException;
497 
498     /*-----------------------------------------------------------------------
499       Account management
500       -----------------------------------------------------------------------*/
501 
502     /***
503      * Creates new user account with specified attributes.
504      *
505      * @param user the object describing account to be created.
506      * @param password The password to use.
507      * @throws DataBackendException if there was an error accessing the data
508      *         backend.
509      * @throws EntityExistsException if the user account already exists.
510      */
511     void addUser(User user, String password)
512             throws DataBackendException, EntityExistsException;
513 
514     /***
515      * Removes an user account from the system.
516      *
517      * @param user the object describing the account to be removed.
518      * @throws DataBackendException if there was an error accessing the data
519      *         backend.
520      * @throws UnknownEntityException if the user account is not present.
521      */
522     void removeUser(User user)
523             throws DataBackendException, UnknownEntityException;
524 
525     /*-----------------------------------------------------------------------
526       Management of passwords
527       -----------------------------------------------------------------------*/
528 
529     /***
530      * This method provides client-side encryption mechanism for passwords.
531      *
532      * This is an utility method that is used by other classes to maintain
533      * a consistent approach to encrypting password. The behavior of the
534      * method can be configured in service's properties.
535      *
536      * @param password the password to process
537      * @return processed password
538      */
539     String encryptPassword(String password);
540 
541     /***
542      * This method provides client-side encryption mechanism for passwords.
543      *
544      * This is an utility method that is used by other classes to maintain
545      * a consistent approach to encrypting password. The behavior of the
546      * method can be configured in service's properties.
547      *
548      * Algorithms that must supply a salt for encryption
549      * can use this method to provide it.
550      *
551      * @param password the password to process
552      * @param salt Salt parameter for some crypto algorithms
553      *
554      * @return processed password
555      */
556     String encryptPassword(String password, String salt);
557 
558     /***
559      * Checks if a supplied password matches the encrypted password
560      * when using the current encryption algorithm
561      *
562      * @param checkpw      The clear text password supplied by the user
563      * @param encpw        The current, encrypted password
564      *
565      * @return true if the password matches, else false
566      *
567      */
568     boolean checkPassword(String checkpw, String encpw);
569 
570     /***
571      * Change the password for an User.
572      *
573      * @param user an User to change password for.
574      * @param oldPassword the current password supplied by the user.
575      * @param newPassword the current password requested by the user.
576      * @exception PasswordMismatchException if the supplied password was
577      *            incorrect.
578      * @exception UnknownEntityException if the user's record does not
579      *            exist in the database.
580      * @exception DataBackendException if there is a problem accessing the
581      *            storage.
582      */
583     void changePassword(User user, String oldPassword,
584                         String newPassword)
585             throws PasswordMismatchException, UnknownEntityException,
586             DataBackendException;
587 
588     /***
589      * Forcibly sets new password for an User.
590      *
591      * This is supposed by the administrator to change the forgotten or
592      * compromised passwords. Certain implementatations of this feature
593      * would require administrative level access to the authenticating
594      * server / program.
595      *
596      * @param user an User to change password for.
597      * @param password the new password.
598      * @exception UnknownEntityException if the user's record does not
599      *            exist in the database.
600      * @exception DataBackendException if there is a problem accessing the
601      *            storage.
602      */
603     void forcePassword(User user, String password)
604             throws UnknownEntityException, DataBackendException;
605 
606     /*-----------------------------------------------------------------------
607       Retrieval of security information
608       -----------------------------------------------------------------------*/
609 
610     /***
611      * Constructs an AccessControlList for a specific user.
612      *
613      * @param user the user for whom the AccessControlList are to be retrieved
614      * @return A new AccessControlList object.
615      * @throws DataBackendException if there was an error accessing the data backend.
616      * @throws UnknownEntityException if user account is not present.
617      */
618     AccessControlList getACL(User user)
619             throws DataBackendException, UnknownEntityException;
620 
621     /***
622      * Retrieves all permissions associated with a role.
623      *
624      * @param role the role name, for which the permissions are to be retrieved.
625      * @return the permissions associated with the role
626      * @throws DataBackendException if there was an error accessing the data
627      *         backend.
628      * @throws UnknownEntityException if the role is not present.
629      */
630     PermissionSet getPermissions(Role role)
631             throws DataBackendException, UnknownEntityException;
632 
633     /*-----------------------------------------------------------------------
634       Manipulation of security information
635       -----------------------------------------------------------------------*/
636 
637     /***
638      * Grant an User a Role in a Group.
639      *
640      * @param user the user.
641      * @param group the group.
642      * @param role the role.
643      * @throws DataBackendException if there was an error accessing the data
644      *         backend.
645      * @throws UnknownEntityException if user account, group or role is not
646      *         present.
647      */
648     void grant(User user, Group group, Role role)
649             throws DataBackendException, UnknownEntityException;
650 
651     /***
652      * Revoke a Role in a Group from an User.
653      *
654      * @param user the user.
655      * @param group the group.
656      * @param role the role.
657      * @throws DataBackendException if there was an error accessing the data
658      *         backend.
659      * @throws UnknownEntityException if user account, group or role is not
660      *         present.
661      */
662     void revoke(User user, Group group, Role role)
663             throws DataBackendException, UnknownEntityException;
664 
665     /***
666      * Revokes all roles from an User.
667      *
668      * This method is used when deleting an account.
669      *
670      * @param user the User.
671      * @throws DataBackendException if there was an error accessing the data
672      *         backend.
673      * @throws UnknownEntityException if the account is not present.
674      */
675     void revokeAll(User user)
676             throws DataBackendException, UnknownEntityException;
677 
678     /***
679      * Grants a Role a Permission
680      *
681      * @param role the Role.
682      * @param permission the Permission.
683      * @throws DataBackendException if there was an error accessing the data
684      *         backend.
685      * @throws UnknownEntityException if role or permission is not present.
686      */
687     void grant(Role role, Permission permission)
688             throws DataBackendException, UnknownEntityException;
689 
690     /***
691      * Revokes a Permission from a Role.
692      *
693      * @param role the Role.
694      * @param permission the Permission.
695      * @throws DataBackendException if there was an error accessing the data
696      *         backend.
697      * @throws UnknownEntityException if role or permission is not present.
698      */
699     void revoke(Role role, Permission permission)
700             throws DataBackendException, UnknownEntityException;
701 
702     /***
703      * Revokes all permissions from a Role.
704      *
705      * This method is user when deleting a Role.
706      *
707      * @param role the Role
708      * @throws DataBackendException if there was an error accessing the data
709      *         backend.
710      * @throws  UnknownEntityException if the Role is not present.
711      */
712     void revokeAll(Role role)
713             throws DataBackendException, UnknownEntityException;
714 
715     /*-----------------------------------------------------------------------
716       Retrieval & storage of SecurityObjects
717       -----------------------------------------------------------------------*/
718 
719     /***
720      * Provides a reference to the Group object that represents the
721      * <a href="#global">global group</a>.
722      *
723      * @return A Group object that represents the global group.
724      */
725     Group getGlobalGroup();
726 
727     /***
728      * @deprecated Use getGroupInstance(String name) instead.
729      */
730     Group getNewGroup(String groupName);
731 
732     /***
733      * @deprecated Use getRoleInstance(String name) instead.
734      */
735     Role getNewRole(String roleName);
736 
737     /***
738      * @deprecated Use getPermissionInstance(String name) instead.
739      */
740     Permission getNewPermission(String permissionName);
741 
742     /***
743      * Retrieve a Group object with specified name.
744      *
745      * @param name the name of the Group.
746      * @return an object representing the Group with specified name.
747      * @throws DataBackendException if there was an error accessing the data
748      *         backend.
749      * @throws UnknownEntityException if the group does not exist.
750      * @deprecated Use <a href="#getGroupByName">getGroupByName</a> instead.
751      */
752     Group getGroup(String name)
753             throws DataBackendException, UnknownEntityException;
754 
755     /***
756      * Retrieve a Group object with specified name.
757      *
758      * @param name the name of the Group.
759      * @return an object representing the Group with specified name.
760      * @throws DataBackendException if there was an error accessing the data
761      *         backend.
762      * @throws UnknownEntityException if the group does not exist.
763      */
764     Group getGroupByName(String name)
765             throws DataBackendException, UnknownEntityException;
766 
767     /***
768      * Retrieve a Group object with specified Id.
769      *
770      * @param name the name of the Group.
771      *
772      * @return an object representing the Group with specified name.
773      *
774      * @exception UnknownEntityException if the permission does not
775      *            exist in the database.
776      * @exception DataBackendException if there is a problem accessing the
777      *            storage.
778      */
779     Group getGroupById(int id)
780             throws DataBackendException,
781                    UnknownEntityException;
782 
783     /***
784      * Retrieve a Role object with specified name.
785      *
786      * @param name the name of the Role.
787      * @return an object representing the Role with specified name.
788      * @throws DataBackendException if there was an error accessing the data
789      *         backend.
790      * @throws UnknownEntityException if the role does not exist.
791      * @deprecated Use <a href="#getRoleByName">getRoleByName</a> instead.
792      */
793     Role getRole(String name)
794             throws DataBackendException, UnknownEntityException;
795 
796     /***
797      * Retrieve a Role object with specified name.
798      *
799      * @param name the name of the Role.
800      * @return an object representing the Role with specified name.
801      * @throws DataBackendException if there was an error accessing the data
802      *         backend.
803      * @throws UnknownEntityException if the role does not exist.
804      */
805     Role getRoleByName(String name)
806             throws DataBackendException, UnknownEntityException;
807 
808     /***
809      * Retrieve a Role object with specified Id.
810      *
811      * @param name the name of the Role.
812      *
813      * @return an object representing the Role with specified name.
814      *
815      * @exception UnknownEntityException if the permission does not
816      *            exist in the database.
817      * @exception DataBackendException if there is a problem accessing the
818      *            storage.
819      */
820     Role getRoleById(int id)
821             throws DataBackendException,
822                    UnknownEntityException;
823 
824     /***
825      * Retrieve a Permission object with specified name.
826      *
827      * @param name the name of the Permission.
828      * @return an object representing the Permission with specified name.
829      * @throws DataBackendException if there was an error accessing the data
830      *         backend.
831      * @throws UnknownEntityException if the permission does not exist.
832      * @deprecated Use <a href="#getPermissionByName">getPermissionByName</a> instead.
833      */
834     Permission getPermission(String name)
835             throws DataBackendException, UnknownEntityException;
836 
837     /***
838      * Retrieve a Permission object with specified name.
839      *
840      * @param name the name of the Permission.
841      * @return an object representing the Permission with specified name.
842      * @throws DataBackendException if there was an error accessing the data
843      *         backend.
844      * @throws UnknownEntityException if the permission does not exist.
845      */
846     Permission getPermissionByName(String name)
847             throws DataBackendException, UnknownEntityException;
848 
849     /***
850      * Retrieve a Permission object with specified Id.
851      *
852      * @param name the name of the Permission.
853      *
854      * @return an object representing the Permission with specified name.
855      *
856      * @exception UnknownEntityException if the permission does not
857      *            exist in the database.
858      * @exception DataBackendException if there is a problem accessing the
859      *            storage.
860      */
861     Permission getPermissionById(int id)
862             throws DataBackendException,
863                    UnknownEntityException;
864 
865     /***
866      * Retrieve a set of Groups that meet the specified Criteria.
867      *
868      * @param criteria a Criteria of Group selection.
869      * @return a set of Groups that meet the specified Criteria.
870      * @throws DataBackendException if there was an error accessing the data
871      *         backend.
872      */
873     GroupSet getGroups(Criteria criteria)
874             throws DataBackendException;
875 
876     /***
877      * Retrieve a set of Roles that meet the specified Criteria.
878      *
879      * @param criteria a Criteria of Roles selection.
880      * @return a set of Roles that meet the specified Criteria.
881      * @throws DataBackendException if there was an error accessing the data
882      *         backend.
883      */
884     RoleSet getRoles(Criteria criteria)
885             throws DataBackendException;
886 
887     /***
888      * Retrieve a set of Permissions that meet the specified Criteria.
889      *
890      * @param criteria a Criteria of Permissions selection.
891      * @return a set of Permissions that meet the specified Criteria.
892      * @throws DataBackendException if there was an error accessing the data
893      *         backend.
894      */
895     PermissionSet getPermissions(Criteria criteria)
896             throws DataBackendException;
897 
898     /***
899      * Retrieves all groups defined in the system.
900      *
901      * @return the names of all groups defined in the system.
902      * @throws DataBackendException if there was an error accessing the data
903      *         backend.
904      */
905     GroupSet getAllGroups()
906             throws DataBackendException;
907 
908     /***
909      * Retrieves all roles defined in the system.
910      *
911      * @return the names of all roles defined in the system.
912      * @throws DataBackendException if there was an error accessing the data
913      *         backend.
914      */
915     RoleSet getAllRoles()
916             throws DataBackendException;
917 
918     /***
919      * Retrieves all permissions defined in the system.
920      *
921      * @return the names of all roles defined in the system.
922      * @throws DataBackendException if there was an error accessing the data
923      *         backend.
924      */
925     PermissionSet getAllPermissions()
926             throws DataBackendException;
927 
928     /***
929      * Stores Group's attributes. The Groups is required to exist in the system.
930      *
931      * @param group The Group to be stored.
932      * @throws DataBackendException if there was an error accessing the data
933      *         backend.
934      * @throws UnknownEntityException if the group does not exist.
935      */
936     void saveGroup(Group group)
937             throws DataBackendException, UnknownEntityException;
938 
939     /***
940      * Stores Role's attributes. The Roles is required to exist in the system.
941      *
942      * @param role The Role to be stored.
943      * @throws DataBackendException if there was an error accessing the data
944      *         backend.
945      * @throws UnknownEntityException if the role does not exist.
946      */
947     void saveRole(Role role)
948             throws DataBackendException, UnknownEntityException;
949 
950     /***
951      * Stores Permission's attributes. The Permission is required to exist in
952      * the system.
953      *
954      * @param permission The Permission to be stored.
955      * @throws DataBackendException if there was an error accessing the data
956      *         backend.
957      * @throws UnknownEntityException if the permission does not exist.
958      */
959     void savePermission(Permission permission)
960             throws DataBackendException, UnknownEntityException;
961 
962     /*-----------------------------------------------------------------------
963       Group/Role/Permission management
964       -----------------------------------------------------------------------*/
965 
966     /***
967      * Creates a new group with specified attributes.
968      *
969      * @param group the object describing the group to be created.
970      * @return the new Group object.
971      * @throws DataBackendException if there was an error accessing the data
972      *         backend.
973      * @throws EntityExistsException if the group already exists.
974      */
975     Group addGroup(Group group)
976             throws DataBackendException, EntityExistsException;
977 
978     /***
979      * Creates a new role with specified attributes.
980      *
981      * @param role The object describing the role to be created.
982      * @return the new Role object.
983      * @throws DataBackendException if there was an error accessing the data
984      *         backend.
985      * @throws EntityExistsException if the role already exists.
986      */
987     Role addRole(Role role)
988             throws DataBackendException, EntityExistsException;
989 
990     /***
991      * Creates a new permission with specified attributes.
992      *
993      * @param permission The object describing the permission to be created.
994      * @return the new Permission object.
995      * @throws DataBackendException if there was an error accessing the data
996      *         backend.
997      * @throws EntityExistsException if the permission already exists.
998      */
999     Permission addPermission(Permission permission)
1000             throws DataBackendException, EntityExistsException;
1001 
1002     /***
1003      * Removes a Group from the system.
1004      *
1005      * @param group The object describing the group to be removed.
1006      * @throws DataBackendException if there was an error accessing the data
1007      *         backend.
1008      * @throws UnknownEntityException if the group does not exist.
1009      */
1010     void removeGroup(Group group)
1011             throws DataBackendException, UnknownEntityException;
1012 
1013     /***
1014      * Removes a Role from the system.
1015      *
1016      * @param role The object describing the role to be removed.
1017      * @throws DataBackendException if there was an error accessing the data
1018      *         backend.
1019      * @throws UnknownEntityException if the role does not exist.
1020      */
1021     void removeRole(Role role)
1022             throws DataBackendException, UnknownEntityException;
1023 
1024     /***
1025      * Removes a Permission from the system.
1026      *
1027      * @param permission The object describing the permission to be removed.
1028      * @throws DataBackendException if there was an error accessing the data
1029      *         backend.
1030      * @throws UnknownEntityException if the permission does not exist.
1031      */
1032     void removePermission(Permission permission)
1033             throws DataBackendException, UnknownEntityException;
1034 
1035     /***
1036      * Renames an existing Group.
1037      *
1038      * @param group The object describing the group to be renamed.
1039      * @param name the new name for the group.
1040      * @throws DataBackendException if there was an error accessing the data
1041      *         backend.
1042      * @throws UnknownEntityException if the group does not exist.
1043      */
1044     void renameGroup(Group group, String name)
1045             throws DataBackendException, UnknownEntityException;
1046 
1047     /***
1048      * Renames an existing Role.
1049      *
1050      * @param role The object describing the role to be renamed.
1051      * @param name the new name for the role.
1052      * @throws DataBackendException if there was an error accessing the data
1053      *         backend.
1054      * @throws UnknownEntityException if the role does not exist.
1055      */
1056     void renameRole(Role role, String name)
1057             throws DataBackendException, UnknownEntityException;
1058 
1059     /***
1060      * Renames an existing Permission.
1061      *
1062      * @param permission The object describing the permission to be renamed.
1063      * @param name the new name for the permission.
1064      * @throws DataBackendException if there was an error accessing the data
1065      *         backend.
1066      * @throws UnknownEntityException if the permission does not exist.
1067      */
1068     void renamePermission(Permission permission, String name)
1069             throws DataBackendException, UnknownEntityException;
1070 }