View Javadoc

    1   package org.apache.turbine.services.security;
    2
    3
    4   /*
    5    * Licensed to the Apache Software Foundation (ASF) under one
    6    * or more contributor license agreements.  See the NOTICE file
    7    * distributed with this work for additional information
    8    * regarding copyright ownership.  The ASF licenses this file
    9    * to you under the Apache License, Version 2.0 (the
    10   * "License"); you may not use this file except in compliance
    11   * with the License.  You may obtain a copy of the License at
    12   *
    13   *   http://www.apache.org/licenses/LICENSE-2.0
    14   *
    15   * Unless required by applicable law or agreed to in writing,
    16   * software distributed under the License is distributed on an
    17   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    18   * KIND, either express or implied.  See the License for the
    19   * specific language governing permissions and limitations
    20   * under the License.
    21   */
    22
    23
    24  import java.util.List;
    25  import java.util.Map;
    26
    27  import org.apache.turbine.om.security.Group;
    28  import org.apache.turbine.om.security.Permission;
    29  import org.apache.turbine.om.security.Role;
    30  import org.apache.turbine.om.security.TurbineGroup;
    31  import org.apache.turbine.om.security.TurbinePermission;
    32  import org.apache.turbine.om.security.TurbineRole;
    33  import org.apache.turbine.om.security.TurbineUser;
    34  import org.apache.turbine.om.security.User;
    35  import org.apache.turbine.services.Service;
    36  import org.apache.turbine.services.security.passive.PassiveUserManager;
    37  import org.apache.turbine.util.security.AccessControlList;
    38  import org.apache.turbine.util.security.DataBackendException;
    39  import org.apache.turbine.util.security.EntityExistsException;
    40  import org.apache.turbine.util.security.GroupSet;
    41  import org.apache.turbine.util.security.PasswordMismatchException;
    42  import org.apache.turbine.util.security.PermissionSet;
    43  import org.apache.turbine.util.security.RoleSet;
    44  import org.apache.turbine.util.security.TurbineAccessControlList;
    45  import org.apache.turbine.util.security.UnknownEntityException;
    46
    47  /**
    48   * The Security Service manages Users, Groups Roles and Permissions in the
    49   * system.
    50   *
    51   * The task performed by the security service include creation and removal of
    52   * accounts, groups, roles, and permissions; assigning users roles in groups;
    53   * assigning roles specific permissions and construction of objects
    54   * representing these logical entities.
    55   *
    56   * <p> Because of pluggable nature of the Services, it is possible to create
    57   * multiple implementations of SecurityService, for example employing database
    58   * and directory server as the data backend.<br>
    59   *
    60   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
    61   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    62   * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
    63   * @version $Id: SecurityService.java 1096130 2011-04-23 10:37:19Z ludwig $
    64   */
    65  public interface SecurityService
    66          extends Service
    67  {
    68      /** The name of the service */
    69      String SERVICE_NAME = "SecurityService";
    70
    71      /**
    72       * the key within services's properties for user implementation
    73       * classname (user.class)
    74       */
    75      String USER_CLASS_KEY = "user.class";
    76
    77      /**
    78       * the default implementation of User interface
    79       * (org.apache.turbine.om.security.TurbineUser)
    80       */
    81      String USER_CLASS_DEFAULT
    82              = TurbineUser.class.getName();
    83
    84      /**
    85       * The key within services' properties for the GROUP
    86       * implementation classname (group.class)
    87       */
    88      String GROUP_CLASS_KEY = "group.class";
    89
    90      /**
    91       * The default implementation of the Group interface
    92       * (org.apache.turbine.om.security.TurbineGroup)
    93       */
    94      String GROUP_CLASS_DEFAULT
    95              = TurbineGroup.class.getName();
    96
    97      /**
    98       * The key within services' properties for the PERMISSION
    99       * implementation classname (permission.class)
    100      */
    101     String PERMISSION_CLASS_KEY = "permission.class";
    102
    103     /**
    104      * The default implementation of the Permissions interface
    105      * (org.apache.turbine.om.security.TurbinePermission)
    106      */
    107     String PERMISSION_CLASS_DEFAULT
    108             = TurbinePermission.class.getName();
    109
    110     /**
    111      * The key within services' properties for the ROLE
    112      * implementation classname (role.class)
    113      */
    114     String ROLE_CLASS_KEY = "role.class";
    115
    116     /**
    117      * The default implementation of the Role Interface
    118      * (org.apache.turbine.om.security.TurbineRole)
    119      */
    120     String ROLE_CLASS_DEFAULT
    121             = TurbineRole.class.getName();
    122
    123     /**
    124      * The key within services' properties for the
    125      * ACL implementation classname (acl.class)
    126      */
    127     String ACL_CLASS_KEY = "acl.class";
    128
    129     /**
    130      * The default implementation of the Acl Interface
    131      * (org.apache.turbine.util.security.TurbineAccessControlList)
    132      */
    133     String ACL_CLASS_DEFAULT
    134             = TurbineAccessControlList.class.getName();
    135
    136     /**
    137      * the key within services's properties for user implementation
    138      * classname (user.manager)
    139      */
    140     String USER_MANAGER_KEY = "user.manager";
    141
    142     /**
    143      * the default implementation of UserManager interface
    144      * (org.apache.turbine.services.security.passive.PassiveUserManager)
    145      */
    146     String USER_MANAGER_DEFAULT
    147             = PassiveUserManager.class.getName();
    148
    149     /**
    150      * the key within services's properties for secure passwords flag
    151      * (secure.passwords)
    152      */
    153     String SECURE_PASSWORDS_KEY = "secure.passwords";
    154
    155     /** the value of secure passwords flag (false) */
    156     String SECURE_PASSWORDS_DEFAULT = "false";
    157
    158     /**
    159      * the key within services's properties for secure passwords algorithm
    160      * (secure.passwords.algorithm)
    161      */
    162     String SECURE_PASSWORDS_ALGORITHM_KEY
    163             = "secure.passwords.algorithm";
    164
    165     /** the default algorithm for password encryption (SHA) */
    166     String SECURE_PASSWORDS_ALGORITHM_DEFAULT = "SHA";
    167
    168     /*-----------------------------------------------------------------------
    169       Management of User objects
    170       -----------------------------------------------------------------------*/
    171
    172     /**
    173      * Returns the Class object for the implementation of User interface
    174      * used by the system.
    175      *
    176      * @return the implementation of User interface used by the system.
    177      * @throws UnknownEntityException if the system's implementation of User
    178      *         interface could not be determined.
    179      */
    180     Class getUserClass()
    181             throws UnknownEntityException;
    182
    183     /**
    184      * Construct a blank User object.
    185      *
    186      * This method calls getUserClass, and then creates a new object using
    187      * the default constructor.
    188      *
    189      * @return an object implementing User interface.
    190      * @throws UnknownEntityException if the object could not be instantiated.
    191      */
    192     User getUserInstance()
    193             throws UnknownEntityException;
    194
    195     /**
    196      * Construct a blank User object.
    197      *
    198      * This method calls getUserClass, and then creates a new object using
    199      * the default constructor.
    200      *
    201      * @param userName The name of the user.
    202      *
    203      * @return an object implementing User interface.
    204      * @throws UnknownEntityException if the object could not be instantiated.
    205      */
    206     User getUserInstance(String userName)
    207             throws UnknownEntityException;
    208
    209     /**
    210      * Returns the Class object for the implementation of Group interface
    211      * used by the system.
    212      *
    213      * @return the implementation of Group interface used by the system.
    214      * @throws UnknownEntityException if the system's implementation of Group
    215      *         interface could not be determined.
    216      */
    217     Class getGroupClass()
    218             throws UnknownEntityException;
    219
    220     /**
    221      * Construct a blank Group object.
    222      *
    223      * This method calls getGroupClass, and then creates a new object using
    224      * the default constructor.
    225      *
    226      * @return an object implementing Group interface.
    227      * @throws UnknownEntityException if the object could not be instantiated.
    228      */
    229     Group getGroupInstance()
    230             throws UnknownEntityException;
    231
    232     /**
    233      * Construct a blank Group object.
    234      *
    235      * This method calls getGroupClass, and then creates a new object using
    236      * the default constructor.
    237      *
    238      * @param groupName The name of the Group
    239      *
    240      * @return an object implementing Group interface.
    241      * @throws UnknownEntityException if the object could not be instantiated.
    242      */
    243     Group getGroupInstance(String groupName)
    244             throws UnknownEntityException;
    245
    246     /**
    247      * Returns the Class object for the implementation of Permission interface
    248      * used by the system.
    249      *
    250      * @return the implementation of Permission interface used by the system.
    251      * @throws UnknownEntityException if the system's implementation of Permission
    252      *         interface could not be determined.
    253      */
    254     Class getPermissionClass()
    255             throws UnknownEntityException;
    256
    257     /**
    258      * Construct a blank Permission object.
    259      *
    260      * This method calls getPermissionClass, and then creates a new object using
    261      * the default constructor.
    262      *
    263      * @return an object implementing Permission interface.
    264      * @throws UnknownEntityException if the object could not be instantiated.
    265      */
    266     Permission getPermissionInstance()
    267             throws UnknownEntityException;
    268
    269     /**
    270      * Construct a blank Permission object.
    271      *
    272      * This method calls getPermissionClass, and then creates a new object using
    273      * the default constructor.
    274      *
    275      * @param permName The name of the Permission
    276      *
    277      * @return an object implementing Permission interface.
    278      * @throws UnknownEntityException if the object could not be instantiated.
    279      */
    280     Permission getPermissionInstance(String permName)
    281             throws UnknownEntityException;
    282
    283     /**
    284      * Returns the Class object for the implementation of Role interface
    285      * used by the system.
    286      *
    287      * @return the implementation of Role interface used by the system.
    288      * @throws UnknownEntityException if the system's implementation of Role
    289      *         interface could not be determined.
    290      */
    291     Class getRoleClass()
    292             throws UnknownEntityException;
    293
    294     /**
    295      * Construct a blank Role object.
    296      *
    297      * This method calls getRoleClass, and then creates a new object using
    298      * the default constructor.
    299      *
    300      * @return an object implementing Role interface.
    301      * @throws UnknownEntityException if the object could not be instantiated.
    302      */
    303     Role getRoleInstance()
    304             throws UnknownEntityException;
    305
    306     /**
    307      * Construct a blank Role object.
    308      *
    309      * This method calls getRoleClass, and then creates a new object using
    310      * the default constructor.
    311      *
    312      * @param roleName The name of the Role
    313      *
    314      * @return an object implementing Role interface.
    315      * @throws UnknownEntityException if the object could not be instantiated.
    316      */
    317     Role getRoleInstance(String roleName)
    318             throws UnknownEntityException;
    319
    320     /**
    321      * Returns the Class object for the implementation of AccessControlList interface
    322      * used by the system.
    323      *
    324      * @return the implementation of AccessControlList interface used by the system.
    325      * @throws UnknownEntityException if the system's implementation of AccessControlList
    326      *         interface could not be determined.
    327      */
    328     Class getAclClass()
    329             throws UnknownEntityException;
    330
    331     /**
    332      * Construct a new ACL object.
    333      *
    334      * This constructs a new ACL object from the configured class and
    335      * initializes it with the supplied roles and permissions.
    336      *
    337      * @param roles The roles that this ACL should contain
    338      * @param permissions The permissions for this ACL
    339      *
    340      * @return an object implementing ACL interface.
    341      * @throws UnknownEntityException if the object could not be instantiated.
    342      */
    343     AccessControlList getAclInstance(Map roles, Map permissions)
    344             throws UnknownEntityException;
    345
    346     /**
    347      * Returns the configured UserManager.
    348      *
    349      * @return An UserManager object
    350      */
    351     UserManager getUserManager();
    352
    353     /**
    354      * Configure a new user Manager.
    355      *
    356      * @param userManager An UserManager object
    357      */
    358     void setUserManager(UserManager userManager);
    359
    360     /**
    361      * Check whether a specified user's account exists.
    362      *
    363      * The login name is used for looking up the account.
    364      *
    365      * @param userName The user to be checked.
    366      * @return true if the specified account exists
    367      * @throws DataBackendException if there was an error accessing the data
    368      *         backend.
    369      */
    370     boolean accountExists(String userName)
    371             throws DataBackendException;
    372
    373     /**
    374      * Check whether a specified user's account exists.
    375      * An User object is used for looking up the account.
    376      *
    377      * @param user The user object to be checked.
    378      * @return true if the specified account exists
    379      * @throws DataBackendException if there was an error accessing the data
    380      *         backend.
    381      */
    382     boolean accountExists(User user)
    383             throws DataBackendException;
    384
    385     /**
    386      * Authenticates an user, and constructs an User object to represent
    387      * him/her.
    388      *
    389      * @param username The user name.
    390      * @param password The user password.
    391      * @return An authenticated Turbine User.
    392      * @throws DataBackendException if there was an error accessing the data
    393      *         backend.
    394      * @throws UnknownEntityException if user account is not present.
    395      * @throws PasswordMismatchException if the supplied password was incorrect.
    396      */
    397     User getAuthenticatedUser(String username, String password)
    398             throws DataBackendException, UnknownEntityException,
    399             PasswordMismatchException;
    400
    401     /**
    402      * Constructs an User object to represent a registered user of the
    403      * application.
    404      *
    405      * @param username The user name.
    406      * @return A Turbine User.
    407      * @throws DataBackendException if there was an error accessing the data
    408      *         backend.
    409      * @throws UnknownEntityException if user account is not present.
    410      */
    411     User getUser(String username)
    412             throws DataBackendException, UnknownEntityException;
    413
    414     /**
    415      * Retrieve a set of users that meet the specified criteria.
    416      *
    417      * As the keys for the criteria, you should use the constants that
    418      * are defined in {@link User} interface, plus the names
    419      * of the custom attributes you added to your user representation
    420      * in the data storage. Use verbatim names of the attributes -
    421      * without table name prefix in case of Torque implementation.
    422      *
    423      * @param criteria The criteria of selection.
    424      * @return a List of users meeting the criteria.
    425      * @throws DataBackendException if there is a problem accessing the
    426      *         storage.
    427      */
    428     List getUserList(Object criteria)
    429             throws DataBackendException;
    430
    431     /**
    432      * Constructs an User object to represent an anonymous user of the
    433      * application.
    434      *
    435      * @return An anonymous Turbine User.
    436      * @throws UnknownEntityException if the anonymous User object couldn't be
    437      *         constructed.
    438      */
    439     User getAnonymousUser()
    440             throws UnknownEntityException;
    441
    442     /**
    443      * Checks whether a passed user object matches the anonymous user pattern
    444      * according to the configured user manager
    445      *
    446      * @param An user object
    447      *
    448      * @return True if this is an anonymous user
    449      *
    450      */
    451     boolean isAnonymousUser(User u);
    452
    453     /**
    454      * Saves User's data in the permanent storage. The user account is required
    455      * to exist in the storage.
    456      *
    457      * @param user the user object to save
    458      * @throws UnknownEntityException if the user's account does not
    459      *         exist in the database.
    460      * @throws DataBackendException if there is a problem accessing the storage.
    461      */
    462     void saveUser(User user)
    463             throws UnknownEntityException, DataBackendException;
    464
    465     /**
    466      * Saves User data when the session is unbound. The user account is required
    467      * to exist in the storage.
    468      *
    469      * LastLogin, AccessCounter, persistent pull tools, and any data stored
    470      * in the permData hashtable that is not mapped to a column will be saved.
    471      *
    472      * @exception UnknownEntityException if the user's account does not
    473      *            exist in the database.
    474      * @exception DataBackendException if there is a problem accessing the
    475      *            storage.
    476      */
    477     void saveOnSessionUnbind(User user)
    478             throws UnknownEntityException, DataBackendException;
    479
    480     /*-----------------------------------------------------------------------
    481       Account management
    482       -----------------------------------------------------------------------*/
    483
    484     /**
    485      * Creates new user account with specified attributes.
    486      *
    487      * @param user the object describing account to be created.
    488      * @param password The password to use.
    489      * @throws DataBackendException if there was an error accessing the data
    490      *         backend.
    491      * @throws EntityExistsException if the user account already exists.
    492      */
    493     void addUser(User user, String password)
    494             throws DataBackendException, EntityExistsException;
    495
    496     /**
    497      * Removes an user account from the system.
    498      *
    499      * @param user the object describing the account to be removed.
    500      * @throws DataBackendException if there was an error accessing the data
    501      *         backend.
    502      * @throws UnknownEntityException if the user account is not present.
    503      */
    504     void removeUser(User user)
    505             throws DataBackendException, UnknownEntityException;
    506
    507     /*-----------------------------------------------------------------------
    508       Management of passwords
    509       -----------------------------------------------------------------------*/
    510
    511     /**
    512      * This method provides client-side encryption mechanism for passwords.
    513      *
    514      * This is an utility method that is used by other classes to maintain
    515      * a consistent approach to encrypting password. The behavior of the
    516      * method can be configured in service's properties.
    517      *
    518      * @param password the password to process
    519      * @return processed password
    520      */
    521     String encryptPassword(String password);
    522
    523     /**
    524      * This method provides client-side encryption mechanism for passwords.
    525      *
    526      * This is an utility method that is used by other classes to maintain
    527      * a consistent approach to encrypting password. The behavior of the
    528      * method can be configured in service's properties.
    529      *
    530      * Algorithms that must supply a salt for encryption
    531      * can use this method to provide it.
    532      *
    533      * @param password the password to process
    534      * @param salt Salt parameter for some crypto algorithms
    535      *
    536      * @return processed password
    537      */
    538     String encryptPassword(String password, String salt);
    539
    540     /**
    541      * Checks if a supplied password matches the encrypted password
    542      * when using the current encryption algorithm
    543      *
    544      * @param checkpw      The clear text password supplied by the user
    545      * @param encpw        The current, encrypted password
    546      *
    547      * @return true if the password matches, else false
    548      *
    549      */
    550     boolean checkPassword(String checkpw, String encpw);
    551
    552     /**
    553      * Change the password for an User.
    554      *
    555      * @param user an User to change password for.
    556      * @param oldPassword the current password supplied by the user.
    557      * @param newPassword the current password requested by the user.
    558      * @exception PasswordMismatchException if the supplied password was
    559      *            incorrect.
    560      * @exception UnknownEntityException if the user's record does not
    561      *            exist in the database.
    562      * @exception DataBackendException if there is a problem accessing the
    563      *            storage.
    564      */
    565     void changePassword(User user, String oldPassword,
    566                         String newPassword)
    567             throws PasswordMismatchException, UnknownEntityException,
    568             DataBackendException;
    569
    570     /**
    571      * Forcibly sets new password for an User.
    572      *
    573      * This is supposed by the administrator to change the forgotten or
    574      * compromised passwords. Certain implementatations of this feature
    575      * would require administrative level access to the authenticating
    576      * server / program.
    577      *
    578      * @param user an User to change password for.
    579      * @param password the new password.
    580      * @exception UnknownEntityException if the user's record does not
    581      *            exist in the database.
    582      * @exception DataBackendException if there is a problem accessing the
    583      *            storage.
    584      */
    585     void forcePassword(User user, String password)
    586             throws UnknownEntityException, DataBackendException;
    587
    588     /*-----------------------------------------------------------------------
    589       Retrieval of security information
    590       -----------------------------------------------------------------------*/
    591
    592     /**
    593      * Constructs an AccessControlList for a specific user.
    594      *
    595      * @param user the user for whom the AccessControlList are to be retrieved
    596      * @return A new AccessControlList object.
    597      * @throws DataBackendException if there was an error accessing the data backend.
    598      * @throws UnknownEntityException if user account is not present.
    599      */
    600     AccessControlList getACL(User user)
    601             throws DataBackendException, UnknownEntityException;
    602
    603     /**
    604      * Retrieves all permissions associated with a role.
    605      *
    606      * @param role the role name, for which the permissions are to be retrieved.
    607      * @return the permissions associated with the role
    608      * @throws DataBackendException if there was an error accessing the data
    609      *         backend.
    610      * @throws UnknownEntityException if the role is not present.
    611      */
    612     PermissionSet getPermissions(Role role)
    613             throws DataBackendException, UnknownEntityException;
    614
    615     /*-----------------------------------------------------------------------
    616       Manipulation of security information
    617       -----------------------------------------------------------------------*/
    618
    619     /**
    620      * Grant an User a Role in a Group.
    621      *
    622      * @param user the user.
    623      * @param group the group.
    624      * @param role the role.
    625      * @throws DataBackendException if there was an error accessing the data
    626      *         backend.
    627      * @throws UnknownEntityException if user account, group or role is not
    628      *         present.
    629      */
    630     void grant(User user, Group group, Role role)
    631             throws DataBackendException, UnknownEntityException;
    632
    633     /**
    634      * Revoke a Role in a Group from an User.
    635      *
    636      * @param user the user.
    637      * @param group the group.
    638      * @param role the role.
    639      * @throws DataBackendException if there was an error accessing the data
    640      *         backend.
    641      * @throws UnknownEntityException if user account, group or role is not
    642      *         present.
    643      */
    644     void revoke(User user, Group group, Role role)
    645             throws DataBackendException, UnknownEntityException;
    646
    647     /**
    648      * Revokes all roles from an User.
    649      *
    650      * This method is used when deleting an account.
    651      *
    652      * @param user the User.
    653      * @throws DataBackendException if there was an error accessing the data
    654      *         backend.
    655      * @throws UnknownEntityException if the account is not present.
    656      */
    657     void revokeAll(User user)
    658             throws DataBackendException, UnknownEntityException;
    659
    660     /**
    661      * Grants a Role a Permission
    662      *
    663      * @param role the Role.
    664      * @param permission the Permission.
    665      * @throws DataBackendException if there was an error accessing the data
    666      *         backend.
    667      * @throws UnknownEntityException if role or permission is not present.
    668      */
    669     void grant(Role role, Permission permission)
    670             throws DataBackendException, UnknownEntityException;
    671
    672     /**
    673      * Revokes a Permission from a Role.
    674      *
    675      * @param role the Role.
    676      * @param permission the Permission.
    677      * @throws DataBackendException if there was an error accessing the data
    678      *         backend.
    679      * @throws UnknownEntityException if role or permission is not present.
    680      */
    681     void revoke(Role role, Permission permission)
    682             throws DataBackendException, UnknownEntityException;
    683
    684     /**
    685      * Revokes all permissions from a Role.
    686      *
    687      * This method is user when deleting a Role.
    688      *
    689      * @param role the Role
    690      * @throws DataBackendException if there was an error accessing the data
    691      *         backend.
    692      * @throws  UnknownEntityException if the Role is not present.
    693      */
    694     void revokeAll(Role role)
    695             throws DataBackendException, UnknownEntityException;
    696
    697     /*-----------------------------------------------------------------------
    698       Retrieval & storage of SecurityObjects
    699       -----------------------------------------------------------------------*/
    700
    701     /**
    702      * Provides a reference to the Group object that represents the
    703      * <a href="#global">global group</a>.
    704      *
    705      * @return A Group object that represents the global group.
    706      */
    707     Group getGlobalGroup();
    708
    709     /**
    710      * Retrieve a Group object with specified name.
    711      *
    712      * @param name the name of the Group.
    713      * @return an object representing the Group with specified name.
    714      * @throws DataBackendException if there was an error accessing the data
    715      *         backend.
    716      * @throws UnknownEntityException if the group does not exist.
    717      */
    718     Group getGroupByName(String name)
    719             throws DataBackendException, UnknownEntityException;
    720
    721     /**
    722      * Retrieve a Group object with specified Id.
    723      *
    724      * @param name the name of the Group.
    725      *
    726      * @return an object representing the Group with specified name.
    727      *
    728      * @exception UnknownEntityException if the permission does not
    729      *            exist in the database.
    730      * @exception DataBackendException if there is a problem accessing the
    731      *            storage.
    732      */
    733     Group getGroupById(int id)
    734             throws DataBackendException,
    735                    UnknownEntityException;
    736
    737     /**
    738      * Retrieve a Role object with specified name.
    739      *
    740      * @param name the name of the Role.
    741      * @return an object representing the Role with specified name.
    742      * @throws DataBackendException if there was an error accessing the data
    743      *         backend.
    744      * @throws UnknownEntityException if the role does not exist.
    745      */
    746     Role getRoleByName(String name)
    747             throws DataBackendException, UnknownEntityException;
    748
    749     /**
    750      * Retrieve a Role object with specified Id.
    751      *
    752      * @param name the name of the Role.
    753      *
    754      * @return an object representing the Role with specified name.
    755      *
    756      * @exception UnknownEntityException if the permission does not
    757      *            exist in the database.
    758      * @exception DataBackendException if there is a problem accessing the
    759      *            storage.
    760      */
    761     Role getRoleById(int id)
    762             throws DataBackendException,
    763                    UnknownEntityException;
    764
    765     /**
    766      * Retrieve a Permission object with specified name.
    767      *
    768      * @param name the name of the Permission.
    769      * @return an object representing the Permission with specified name.
    770      * @throws DataBackendException if there was an error accessing the data
    771      *         backend.
    772      * @throws UnknownEntityException if the permission does not exist.
    773      */
    774     Permission getPermissionByName(String name)
    775             throws DataBackendException, UnknownEntityException;
    776
    777     /**
    778      * Retrieve a Permission object with specified Id.
    779      *
    780      * @param name the name of the Permission.
    781      *
    782      * @return an object representing the Permission with specified name.
    783      *
    784      * @exception UnknownEntityException if the permission does not
    785      *            exist in the database.
    786      * @exception DataBackendException if there is a problem accessing the
    787      *            storage.
    788      */
    789     Permission getPermissionById(int id)
    790             throws DataBackendException,
    791                    UnknownEntityException;
    792
    793     /**
    794      * Retrieve a set of Groups that meet the specified Criteria.
    795      *
    796      * @param criteria a Criteria of Group selection.
    797      * @return a set of Groups that meet the specified Criteria.
    798      * @throws DataBackendException if there was an error accessing the data
    799      *         backend.
    800      */
    801     GroupSet getGroups(Object criteria)
    802             throws DataBackendException;
    803
    804     /**
    805      * Retrieve a set of Roles that meet the specified Criteria.
    806      *
    807      * @param criteria a Criteria of Roles selection.
    808      * @return a set of Roles that meet the specified Criteria.
    809      * @throws DataBackendException if there was an error accessing the data
    810      *         backend.
    811      */
    812     RoleSet getRoles(Object criteria)
    813             throws DataBackendException;
    814
    815     /**
    816      * Retrieve a set of Permissions that meet the specified Criteria.
    817      *
    818      * @param criteria a Criteria of Permissions selection.
    819      * @return a set of Permissions that meet the specified Criteria.
    820      * @throws DataBackendException if there was an error accessing the data
    821      *         backend.
    822      */
    823     PermissionSet getPermissions(Object criteria)
    824             throws DataBackendException;
    825
    826     /**
    827      * Retrieves all groups defined in the system.
    828      *
    829      * @return the names of all groups defined in the system.
    830      * @throws DataBackendException if there was an error accessing the data
    831      *         backend.
    832      */
    833     GroupSet getAllGroups()
    834             throws DataBackendException;
    835
    836     /**
    837      * Retrieves all roles defined in the system.
    838      *
    839      * @return the names of all roles defined in the system.
    840      * @throws DataBackendException if there was an error accessing the data
    841      *         backend.
    842      */
    843     RoleSet getAllRoles()
    844             throws DataBackendException;
    845
    846     /**
    847      * Retrieves all permissions defined in the system.
    848      *
    849      * @return the names of all roles defined in the system.
    850      * @throws DataBackendException if there was an error accessing the data
    851      *         backend.
    852      */
    853     PermissionSet getAllPermissions()
    854             throws DataBackendException;
    855
    856     /**
    857      * Stores Group's attributes. The Groups is required to exist in the system.
    858      *
    859      * @param group The Group to be stored.
    860      * @throws DataBackendException if there was an error accessing the data
    861      *         backend.
    862      * @throws UnknownEntityException if the group does not exist.
    863      */
    864     void saveGroup(Group group)
    865             throws DataBackendException, UnknownEntityException;
    866
    867     /**
    868      * Stores Role's attributes. The Roles is required to exist in the system.
    869      *
    870      * @param role The Role to be stored.
    871      * @throws DataBackendException if there was an error accessing the data
    872      *         backend.
    873      * @throws UnknownEntityException if the role does not exist.
    874      */
    875     void saveRole(Role role)
    876             throws DataBackendException, UnknownEntityException;
    877
    878     /**
    879      * Stores Permission's attributes. The Permission is required to exist in
    880      * the system.
    881      *
    882      * @param permission The Permission to be stored.
    883      * @throws DataBackendException if there was an error accessing the data
    884      *         backend.
    885      * @throws UnknownEntityException if the permission does not exist.
    886      */
    887     void savePermission(Permission permission)
    888             throws DataBackendException, UnknownEntityException;
    889
    890     /*-----------------------------------------------------------------------
    891       Group/Role/Permission management
    892       -----------------------------------------------------------------------*/
    893
    894     /**
    895      * Creates a new group with specified attributes.
    896      *
    897      * @param group the object describing the group to be created.
    898      * @return the new Group object.
    899      * @throws DataBackendException if there was an error accessing the data
    900      *         backend.
    901      * @throws EntityExistsException if the group already exists.
    902      */
    903     Group addGroup(Group group)
    904             throws DataBackendException, EntityExistsException;
    905
    906     /**
    907      * Creates a new role with specified attributes.
    908      *
    909      * @param role The object describing the role to be created.
    910      * @return the new Role object.
    911      * @throws DataBackendException if there was an error accessing the data
    912      *         backend.
    913      * @throws EntityExistsException if the role already exists.
    914      */
    915     Role addRole(Role role)
    916             throws DataBackendException, EntityExistsException;
    917
    918     /**
    919      * Creates a new permission with specified attributes.
    920      *
    921      * @param permission The object describing the permission to be created.
    922      * @return the new Permission object.
    923      * @throws DataBackendException if there was an error accessing the data
    924      *         backend.
    925      * @throws EntityExistsException if the permission already exists.
    926      */
    927     Permission addPermission(Permission permission)
    928             throws DataBackendException, EntityExistsException;
    929
    930     /**
    931      * Removes a Group from the system.
    932      *
    933      * @param group The object describing the group to be removed.
    934      * @throws DataBackendException if there was an error accessing the data
    935      *         backend.
    936      * @throws UnknownEntityException if the group does not exist.
    937      */
    938     void removeGroup(Group group)
    939             throws DataBackendException, UnknownEntityException;
    940
    941     /**
    942      * Removes a Role from the system.
    943      *
    944      * @param role The object describing the role to be removed.
    945      * @throws DataBackendException if there was an error accessing the data
    946      *         backend.
    947      * @throws UnknownEntityException if the role does not exist.
    948      */
    949     void removeRole(Role role)
    950             throws DataBackendException, UnknownEntityException;
    951
    952     /**
    953      * Removes a Permission from the system.
    954      *
    955      * @param permission The object describing the permission to be removed.
    956      * @throws DataBackendException if there was an error accessing the data
    957      *         backend.
    958      * @throws UnknownEntityException if the permission does not exist.
    959      */
    960     void removePermission(Permission permission)
    961             throws DataBackendException, UnknownEntityException;
    962
    963     /**
    964      * Renames an existing Group.
    965      *
    966      * @param group The object describing the group to be renamed.
    967      * @param name the new name for the group.
    968      * @throws DataBackendException if there was an error accessing the data
    969      *         backend.
    970      * @throws UnknownEntityException if the group does not exist.
    971      */
    972     void renameGroup(Group group, String name)
    973             throws DataBackendException, UnknownEntityException;
    974
    975     /**
    976      * Renames an existing Role.
    977      *
    978      * @param role The object describing the role to be renamed.
    979      * @param name the new name for the role.
    980      * @throws DataBackendException if there was an error accessing the data
    981      *         backend.
    982      * @throws UnknownEntityException if the role does not exist.
    983      */
    984     void renameRole(Role role, String name)
    985             throws DataBackendException, UnknownEntityException;
    986
    987     /**
    988      * Renames an existing Permission.
    989      *
    990      * @param permission The object describing the permission to be renamed.
    991      * @param name the new name for the permission.
    992      * @throws DataBackendException if there was an error accessing the data
    993      *         backend.
    994      * @throws UnknownEntityException if the permission does not exist.
    995      */
    996     void renamePermission(Permission permission, String name)
    997             throws DataBackendException, UnknownEntityException;
    998 }