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&uuml;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    }