    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    }