org.apache.turbine.services.security

## Interface SecurityService

- All Superinterfaces:
    Initable, Service
  All Known Implementing Classes:
    DefaultSecurityService

      public interface SecurityService
      extends Service

  The Security Service manages Users, Groups Roles and Permissions in the system. The task performed by the security service include creation and removal of accounts, groups, roles, and permissions; assigning users roles in groups; assigning roles specific permissions and construction of objects representing these logical entities.

  Because of pluggable nature of the Services, it is possible to create multiple implementations of SecurityService, for example employing database and directory server as the data backend.

  Version:
    $Id: SecurityService.java 1821872 2018-01-22 14:35:04Z gk $
  Author:
    Rafal Krzewski, Henning P. Schmiedehausen, Marco Knüttel

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `SERVICE_NAME` The name of the service
    `static String` | `USER_MANAGER_DEFAULT` the default implementation of UserManager interface (org.apache.turbine.services.security.passive.PassiveUserManager)
    `static String` | `USER_MANAGER_KEY` the key within services's properties for user manager implementation classname (user.manager)
    `static String` | `USER_WRAPPER_DEFAULT` the default implementation of `User` interface (org.apache.turbine.om.security.DefaultUserImpl)
    `static String` | `USER_WRAPPER_KEY` the key within services's properties for user implementation classname (wrapper.class)

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `accountExists(String userName)` Check whether a specified user's account exists.
    `boolean` | `accountExists(User user)` Check whether a specified user's account exists.
    `<G extends org.apache.fulcrum.security.entity.Group> G` | `addGroup(G group)` Creates a new group with specified attributes.
    `<P extends org.apache.fulcrum.security.entity.Permission> P` | `addPermission(P permission)` Creates a new permission with specified attributes.
    `<R extends org.apache.fulcrum.security.entity.Role> R` | `addRole(R role)` Creates a new role with specified attributes.
    `void` | `addUser(User user, String password)` Creates new user account with specified attributes.
    `void` | `changePassword(User user, String oldPassword, String newPassword)` Change the password for an User.
    `void` | `forcePassword(User user, String password)` Forcibly sets new password for an User.
    `<A extends org.apache.fulcrum.security.acl.AccessControlList> A` | `getACL(User user)` Constructs an AccessControlList for a specific user.
    `org.apache.fulcrum.security.util.GroupSet` | `getAllGroups()` Retrieves all groups defined in the system.
    `org.apache.fulcrum.security.util.PermissionSet` | `getAllPermissions()` Retrieves all permissions defined in the system.
    `org.apache.fulcrum.security.util.RoleSet` | `getAllRoles()` Retrieves all roles defined in the system.
    `<U extends User> U` | `getAnonymousUser()` Constructs an User object to represent an anonymous user of the application.
    `<U extends User> U` | `getAuthenticatedUser(String username, String password)` Authenticates an user, and constructs an User object to represent him/her.
    `<G extends org.apache.fulcrum.security.entity.Group> G` | `getGlobalGroup()` Provides a reference to the Group object that represents the global group.
    `<G extends org.apache.fulcrum.security.entity.Group> G` | `getGroupById(int id)` Retrieve a Group object with specified Id.
    `<G extends org.apache.fulcrum.security.entity.Group> G` | `getGroupByName(String name)` Retrieve a Group object with specified name.
    `<G extends org.apache.fulcrum.security.entity.Group> G` | `getGroupInstance()` Construct a blank Group object.
    `<G extends org.apache.fulcrum.security.entity.Group> G` | `getGroupInstance(String groupName)` Construct a blank Group object.
    `<P extends org.apache.fulcrum.security.entity.Permission> P` | `getPermissionById(int id)` Retrieve a Permission object with specified Id.
    `<P extends org.apache.fulcrum.security.entity.Permission> P` | `getPermissionByName(String name)` Retrieve a Permission object with specified name.
    `<P extends org.apache.fulcrum.security.entity.Permission> P` | `getPermissionInstance()` Construct a blank Permission object.
    `<P extends org.apache.fulcrum.security.entity.Permission> P` | `getPermissionInstance(String permName)` Construct a blank Permission object.
    `org.apache.fulcrum.security.util.PermissionSet` | `getPermissions(org.apache.fulcrum.security.entity.Role role)` Retrieves all permissions associated with a role.
    `<R extends org.apache.fulcrum.security.entity.Role> R` | `getRoleById(int id)` Retrieve a Role object with specified Id.
    `<R extends org.apache.fulcrum.security.entity.Role> R` | `getRoleByName(String name)` Retrieve a Role object with specified name.
    `<R extends org.apache.fulcrum.security.entity.Role> R` | `getRoleInstance()` Construct a blank Role object.
    `<R extends org.apache.fulcrum.security.entity.Role> R` | `getRoleInstance(String roleName)` Construct a blank Role object.
    `<U extends User> U` | `getUser(String username)` Constructs an User object to represent a registered user of the application.
    `<U extends User> U` | `getUserInstance()` Construct a blank User object.
    `<U extends User> U` | `getUserInstance(String userName)` Construct a blank User object.
    `UserManager` | `getUserManager()` Returns the configured UserManager.
    `void` | `grant(org.apache.fulcrum.security.entity.Role role, org.apache.fulcrum.security.entity.Permission permission)` Grants a Role a Permission
    `void` | `grant(User user, org.apache.fulcrum.security.entity.Group group, org.apache.fulcrum.security.entity.Role role)` Grant an User a Role in a Group.
    `boolean` | `isAnonymousUser(User u)` Checks whether a passed user object matches the anonymous user pattern according to the configured user manager
    `void` | `removeGroup(org.apache.fulcrum.security.entity.Group group)` Removes a Group from the system.
    `void` | `removePermission(org.apache.fulcrum.security.entity.Permission permission)` Removes a Permission from the system.
    `void` | `removeRole(org.apache.fulcrum.security.entity.Role role)` Removes a Role from the system.
    `void` | `removeUser(User user)` Removes an user account from the system.
    `void` | `renameGroup(org.apache.fulcrum.security.entity.Group group, String name)` Renames an existing Group.
    `void` | `renamePermission(org.apache.fulcrum.security.entity.Permission permission, String name)` Renames an existing Permission.
    `void` | `renameRole(org.apache.fulcrum.security.entity.Role role, String name)` Renames an existing Role.
    `void` | `replaceRole(User user, org.apache.fulcrum.security.entity.Role role, org.apache.fulcrum.security.entity.Role newRole)` Replaces transactionally the first given role with the second role for the given user.
    `void` | `revoke(org.apache.fulcrum.security.entity.Role role, org.apache.fulcrum.security.entity.Permission permission)` Revokes a Permission from a Role.
    `void` | `revoke(User user, org.apache.fulcrum.security.entity.Group group, org.apache.fulcrum.security.entity.Role role)` Revoke a Role in a Group from an User.
    `void` | `revokeAll(org.apache.fulcrum.security.entity.Role role)` Revokes all permissions from a Role.
    `void` | `revokeAll(org.apache.fulcrum.security.entity.Role role, boolean cascadeDelete)` Revokes by default all permissions from a Role and if flag is set all groups and users for this role This method is used when deleting a Role.
    `void` | `revokeAll(User user)` Revokes all roles from an User.
    `void` | `saveOnSessionUnbind(User user)` Saves User data when the session is unbound.
    `void` | `saveUser(User user)` Saves User's data in the permanent storage.

    - ### Methods inherited from interface org.apache.turbine.services.Service

      `getConfiguration, getName, getProperties, setName, setServiceBroker`

    - ### Methods inherited from interface org.apache.turbine.services.Initable

      `getInit, init, init, setInitableBroker, shutdown`

- - ### Field Detail

    - #### SERVICE_NAME

          static final String SERVICE_NAME

      The name of the service
      See Also:
        Constant Field Values

    - #### USER_MANAGER_KEY

          static final String USER_MANAGER_KEY

      the key within services's properties for user manager implementation classname (user.manager)
      See Also:
        Constant Field Values

    - #### USER_MANAGER_DEFAULT

          static final String USER_MANAGER_DEFAULT

      the default implementation of UserManager interface (org.apache.turbine.services.security.passive.PassiveUserManager)

    - #### USER_WRAPPER_KEY

          static final String USER_WRAPPER_KEY

      the key within services's properties for user implementation classname (wrapper.class)
      See Also:
        Constant Field Values

    - #### USER_WRAPPER_DEFAULT

          static final String USER_WRAPPER_DEFAULT

      the default implementation of `User` interface (org.apache.turbine.om.security.DefaultUserImpl)

  - ### Method Detail

    - #### getUserInstance

          <U extends User> U getUserInstance()
                                         throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank User object.
      Returns:
        an object implementing User interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getUserInstance

          <U extends User> U getUserInstance(String userName)
                                         throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank User object.
      Parameters:
        `userName` - The name of the user.
      Returns:
        an object implementing User interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getGroupInstance

          <G extends org.apache.fulcrum.security.entity.Group> G getGroupInstance()
                                                                              throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank Group object.
      Returns:
        an object implementing Group interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getGroupInstance

          <G extends org.apache.fulcrum.security.entity.Group> G getGroupInstance(String groupName)
                                                                              throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank Group object.
      Parameters:
        `groupName` - The name of the Group
      Returns:
        an object implementing Group interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getPermissionInstance

          <P extends org.apache.fulcrum.security.entity.Permission> P getPermissionInstance()
                                                                                        throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank Permission object.
      Returns:
        an object implementing Permission interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getPermissionInstance

          <P extends org.apache.fulcrum.security.entity.Permission> P getPermissionInstance(String permName)
                                                                                        throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank Permission object.
      Parameters:
        `permName` - The name of the Permission
      Returns:
        an object implementing Permission interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getRoleInstance

          <R extends org.apache.fulcrum.security.entity.Role> R getRoleInstance()
                                                                            throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank Role object.
      Returns:
        an object implementing Role interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getRoleInstance

          <R extends org.apache.fulcrum.security.entity.Role> R getRoleInstance(String roleName)
                                                                            throws org.apache.fulcrum.security.util.UnknownEntityException

      Construct a blank Role object.
      Parameters:
        `roleName` - The name of the Role
      Returns:
        an object implementing Role interface.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the object could not be instantiated.

    - #### getUserManager

          UserManager getUserManager()

      Returns the configured UserManager.
      Returns:
        An UserManager object

    - #### accountExists

          boolean accountExists(String userName)
                                throws org.apache.fulcrum.security.util.DataBackendException

      Check whether a specified user's account exists. The login name is used for looking up the account.
      Parameters:
        `userName` - The user to be checked.
      Returns:
        true if the specified account exists
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.

    - #### accountExists

          boolean accountExists(User user)
                                throws org.apache.fulcrum.security.util.DataBackendException

      Check whether a specified user's account exists. An User object is used for looking up the account.
      Parameters:
        `user` - The user object to be checked.
      Returns:
        true if the specified account exists
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.

    - #### getAuthenticatedUser

          <U extends User> U getAuthenticatedUser(String username,
                                                String password)
                                              throws org.apache.fulcrum.security.util.DataBackendException,
                                                     org.apache.fulcrum.security.util.UnknownEntityException,
                                                     org.apache.fulcrum.security.util.PasswordMismatchException

      Authenticates an user, and constructs an User object to represent him/her.
      Parameters:
        `username` - The user name.
        `password` - The user password.
      Returns:
        An authenticated Turbine User.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if user account is not present.
        `org.apache.fulcrum.security.util.PasswordMismatchException` - if the supplied password was incorrect.

    - #### getUser

          <U extends User> U getUser(String username)
                                 throws org.apache.fulcrum.security.util.DataBackendException,
                                        org.apache.fulcrum.security.util.UnknownEntityException

      Constructs an User object to represent a registered user of the application.
      Parameters:
        `username` - The user name.
      Returns:
        A Turbine User.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if user account is not present.

    - #### getAnonymousUser

          <U extends User> U getAnonymousUser()
                                          throws org.apache.fulcrum.security.util.UnknownEntityException

      Constructs an User object to represent an anonymous user of the application.
      Returns:
        An anonymous Turbine User.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the anonymous User object couldn't be constructed.

    - #### isAnonymousUser

          boolean isAnonymousUser(User u)

      Checks whether a passed user object matches the anonymous user pattern according to the configured user manager
      Parameters:
        `u` - a user object
      Returns:
        True if this is an anonymous user

    - #### saveUser

          void saveUser(User user)
                        throws org.apache.fulcrum.security.util.UnknownEntityException,
                               org.apache.fulcrum.security.util.DataBackendException

      Saves User's data in the permanent storage. The user account is required to exist in the storage.
      Parameters:
        `user` - the user object to save
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the user's account does not exist in the database.
        `org.apache.fulcrum.security.util.DataBackendException` - if there is a problem accessing the storage.

    - #### saveOnSessionUnbind

          void saveOnSessionUnbind(User user)
                                   throws org.apache.fulcrum.security.util.UnknownEntityException,
                                          org.apache.fulcrum.security.util.DataBackendException

      Saves User data when the session is unbound. The user account is required to exist in the storage. LastLogin, AccessCounter, persistent pull tools, and any data stored in the permData hashtable that is not mapped to a column will be saved.
      Parameters:
        `user` - the user object
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the user's account does not exist in the database.
        `org.apache.fulcrum.security.util.DataBackendException` - if there is a problem accessing the storage.

    - #### addUser

          void addUser(User user,
                     String password)
                       throws org.apache.fulcrum.security.util.DataBackendException,
                              org.apache.fulcrum.security.util.EntityExistsException,
                              org.apache.fulcrum.security.util.UnknownEntityException

      Creates new user account with specified attributes.
      Parameters:
        `user` - the object describing account to be created.
        `password` - The password to use.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.EntityExistsException` - if the user account already exists.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the provided user does not exist (is null)

    - #### removeUser

          void removeUser(User user)
                          throws org.apache.fulcrum.security.util.DataBackendException,
                                 org.apache.fulcrum.security.util.UnknownEntityException

      Removes an user account from the system.
      Parameters:
        `user` - the object describing the account to be removed.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the user account is not present.

    - #### changePassword

          void changePassword(User user,
                            String oldPassword,
                            String newPassword)
                              throws org.apache.fulcrum.security.util.PasswordMismatchException,
                                     org.apache.fulcrum.security.util.UnknownEntityException,
                                     org.apache.fulcrum.security.util.DataBackendException

      Change the password for an User.
      Parameters:
        `user` - an User to change password for.
        `oldPassword` - the current password supplied by the user.
        `newPassword` - the current password requested by the user.
      Throws:
        `org.apache.fulcrum.security.util.PasswordMismatchException` - if the supplied password was incorrect.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the user's record does not exist in the database.
        `org.apache.fulcrum.security.util.DataBackendException` - if there is a problem accessing the storage.

    - #### forcePassword

          void forcePassword(User user,
                           String password)
                             throws org.apache.fulcrum.security.util.UnknownEntityException,
                                    org.apache.fulcrum.security.util.DataBackendException

      Forcibly sets new password for an User. This is supposed by the administrator to change the forgotten or compromised passwords. Certain implementatations of this feature would require administrative level access to the authenticating server / program.
      Parameters:
        `user` - an User to change password for.
        `password` - the new password.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the user's record does not exist in the database.
        `org.apache.fulcrum.security.util.DataBackendException` - if there is a problem accessing the storage.

    - #### getACL

          <A extends org.apache.fulcrum.security.acl.AccessControlList> A getACL(User user)
                                                                             throws org.apache.fulcrum.security.util.DataBackendException,
                                                                                    org.apache.fulcrum.security.util.UnknownEntityException

      Constructs an AccessControlList for a specific user.
      Parameters:
        `user` - the user for whom the AccessControlList are to be retrieved
      Returns:
        A new AccessControlList object.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if user account is not present.

    - #### getPermissions

          org.apache.fulcrum.security.util.PermissionSet getPermissions(org.apache.fulcrum.security.entity.Role role)
                                                                        throws org.apache.fulcrum.security.util.DataBackendException,
                                                                               org.apache.fulcrum.security.util.UnknownEntityException

      Retrieves all permissions associated with a role.
      Parameters:
        `role` - the role name, for which the permissions are to be retrieved.
      Returns:
        the permissions associated with the role
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the role is not present.

    - #### grant

          void grant(User user,
                   org.apache.fulcrum.security.entity.Group group,
                   org.apache.fulcrum.security.entity.Role role)
                     throws org.apache.fulcrum.security.util.DataBackendException,
                            org.apache.fulcrum.security.util.UnknownEntityException

      Grant an User a Role in a Group.
      Parameters:
        `user` - the user.
        `group` - the group.
        `role` - the role.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if user account, group or role is not present.

    - #### revoke

          void revoke(User user,
                    org.apache.fulcrum.security.entity.Group group,
                    org.apache.fulcrum.security.entity.Role role)
                      throws org.apache.fulcrum.security.util.DataBackendException,
                             org.apache.fulcrum.security.util.UnknownEntityException

      Revoke a Role in a Group from an User.
      Parameters:
        `user` - the user.
        `group` - the group.
        `role` - the role.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if user account, group or role is not present.

    - #### revokeAll

          void revokeAll(User user)
                         throws org.apache.fulcrum.security.util.DataBackendException,
                                org.apache.fulcrum.security.util.UnknownEntityException

      Revokes all roles from an User. This method is used when deleting an account.
      Parameters:
        `user` - the User.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the account is not present.

    - #### grant

          void grant(org.apache.fulcrum.security.entity.Role role,
                   org.apache.fulcrum.security.entity.Permission permission)
                     throws org.apache.fulcrum.security.util.DataBackendException,
                            org.apache.fulcrum.security.util.UnknownEntityException

      Grants a Role a Permission
      Parameters:
        `role` - the Role.
        `permission` - the Permission.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if role or permission is not present.

    - #### revoke

          void revoke(org.apache.fulcrum.security.entity.Role role,
                    org.apache.fulcrum.security.entity.Permission permission)
                      throws org.apache.fulcrum.security.util.DataBackendException,
                             org.apache.fulcrum.security.util.UnknownEntityException

      Revokes a Permission from a Role.
      Parameters:
        `role` - the Role.
        `permission` - the Permission.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if role or permission is not present.

    - #### revokeAll

          void revokeAll(org.apache.fulcrum.security.entity.Role role)
                         throws org.apache.fulcrum.security.util.DataBackendException,
                                org.apache.fulcrum.security.util.UnknownEntityException

      Revokes all permissions from a Role. This method is user when deleting a Role.
      Parameters:
        `role` - the Role
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the Role is not present.

    - #### revokeAll

          void revokeAll(org.apache.fulcrum.security.entity.Role role,
                       boolean cascadeDelete)
                         throws org.apache.fulcrum.security.util.DataBackendException,
                                org.apache.fulcrum.security.util.UnknownEntityException

      Revokes by default all permissions from a Role and if flag is set all groups and users for this role This method is used when deleting a Role.
      Parameters:
        `role` - the Role
        `cascadeDelete` - if `true` removes all groups and user for this role.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the Role is not present.

    - #### getGlobalGroup

          <G extends org.apache.fulcrum.security.entity.Group> G getGlobalGroup()

      Provides a reference to the Group object that represents the global group.
      Returns:
        A Group object that represents the global group.

    - #### getGroupByName

          <G extends org.apache.fulcrum.security.entity.Group> G getGroupByName(String name)
                                                                            throws org.apache.fulcrum.security.util.DataBackendException,
                                                                                   org.apache.fulcrum.security.util.UnknownEntityException

      Retrieve a Group object with specified name.
      Parameters:
        `name` - the name of the Group.
      Returns:
        an object representing the Group with specified name.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the group does not exist.

    - #### getGroupById

          <G extends org.apache.fulcrum.security.entity.Group> G getGroupById(int id)
                                                                          throws org.apache.fulcrum.security.util.DataBackendException,
                                                                                 org.apache.fulcrum.security.util.UnknownEntityException

      Retrieve a Group object with specified Id.
      Parameters:
        `id` - the id of the Group.
      Returns:
        an object representing the Group with specified name.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the permission does not exist in the database.
        `org.apache.fulcrum.security.util.DataBackendException` - if there is a problem accessing the storage.

    - #### getRoleByName

          <R extends org.apache.fulcrum.security.entity.Role> R getRoleByName(String name)
                                                                          throws org.apache.fulcrum.security.util.DataBackendException,
                                                                                 org.apache.fulcrum.security.util.UnknownEntityException

      Retrieve a Role object with specified name.
      Parameters:
        `name` - the name of the Role.
      Returns:
        an object representing the Role with specified name.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the role does not exist.

    - #### getRoleById

          <R extends org.apache.fulcrum.security.entity.Role> R getRoleById(int id)
                                                                        throws org.apache.fulcrum.security.util.DataBackendException,
                                                                               org.apache.fulcrum.security.util.UnknownEntityException

      Retrieve a Role object with specified Id.
      Parameters:
        `id` - the id of the Role.
      Returns:
        an object representing the Role with specified name.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the permission does not exist in the database.
        `org.apache.fulcrum.security.util.DataBackendException` - if there is a problem accessing the storage.

    - #### getPermissionByName

          <P extends org.apache.fulcrum.security.entity.Permission> P getPermissionByName(String name)
                                                                                      throws org.apache.fulcrum.security.util.DataBackendException,
                                                                                             org.apache.fulcrum.security.util.UnknownEntityException

      Retrieve a Permission object with specified name.
      Parameters:
        `name` - the name of the Permission.
      Returns:
        an object representing the Permission with specified name.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the permission does not exist.

    - #### getPermissionById

          <P extends org.apache.fulcrum.security.entity.Permission> P getPermissionById(int id)
                                                                                    throws org.apache.fulcrum.security.util.DataBackendException,
                                                                                           org.apache.fulcrum.security.util.UnknownEntityException

      Retrieve a Permission object with specified Id.
      Parameters:
        `id` - the id of the Permission.
      Returns:
        an object representing the Permission with specified name.
      Throws:
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the permission does not exist in the database.
        `org.apache.fulcrum.security.util.DataBackendException` - if there is a problem accessing the storage.

    - #### getAllGroups

          org.apache.fulcrum.security.util.GroupSet getAllGroups()
                                                                 throws org.apache.fulcrum.security.util.DataBackendException

      Retrieves all groups defined in the system.
      Returns:
        the names of all groups defined in the system.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.

    - #### getAllRoles

          org.apache.fulcrum.security.util.RoleSet getAllRoles()
                                                               throws org.apache.fulcrum.security.util.DataBackendException

      Retrieves all roles defined in the system.
      Returns:
        the names of all roles defined in the system.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.

    - #### getAllPermissions

          org.apache.fulcrum.security.util.PermissionSet getAllPermissions()
                                                                           throws org.apache.fulcrum.security.util.DataBackendException

      Retrieves all permissions defined in the system.
      Returns:
        the names of all roles defined in the system.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.

    - #### addGroup

          <G extends org.apache.fulcrum.security.entity.Group> G addGroup(G group)
                                                                      throws org.apache.fulcrum.security.util.DataBackendException,
                                                                             org.apache.fulcrum.security.util.EntityExistsException

      Creates a new group with specified attributes.
      Parameters:
        `group` - the object describing the group to be created.
      Returns:
        the new Group object.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.EntityExistsException` - if the group already exists.

    - #### addRole

          <R extends org.apache.fulcrum.security.entity.Role> R addRole(R role)
                                                                    throws org.apache.fulcrum.security.util.DataBackendException,
                                                                           org.apache.fulcrum.security.util.EntityExistsException

      Creates a new role with specified attributes.
      Parameters:
        `role` - The object describing the role to be created.
      Returns:
        the new Role object.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.EntityExistsException` - if the role already exists.

    - #### addPermission

          <P extends org.apache.fulcrum.security.entity.Permission> P addPermission(P permission)
                                                                                throws org.apache.fulcrum.security.util.DataBackendException,
                                                                                       org.apache.fulcrum.security.util.EntityExistsException

      Creates a new permission with specified attributes.
      Parameters:
        `permission` - The object describing the permission to be created.
      Returns:
        the new Permission object.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.EntityExistsException` - if the permission already exists.

    - #### removeGroup

          void removeGroup(org.apache.fulcrum.security.entity.Group group)
                           throws org.apache.fulcrum.security.util.DataBackendException,
                                  org.apache.fulcrum.security.util.UnknownEntityException

      Removes a Group from the system.
      Parameters:
        `group` - The object describing the group to be removed.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the group does not exist.

    - #### removeRole

          void removeRole(org.apache.fulcrum.security.entity.Role role)
                          throws org.apache.fulcrum.security.util.DataBackendException,
                                 org.apache.fulcrum.security.util.UnknownEntityException

      Removes a Role from the system.
      Parameters:
        `role` - The object describing the role to be removed.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the role does not exist.

    - #### removePermission

          void removePermission(org.apache.fulcrum.security.entity.Permission permission)
                                throws org.apache.fulcrum.security.util.DataBackendException,
                                       org.apache.fulcrum.security.util.UnknownEntityException

      Removes a Permission from the system.
      Parameters:
        `permission` - The object describing the permission to be removed.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the permission does not exist.

    - #### renameGroup

          void renameGroup(org.apache.fulcrum.security.entity.Group group,
                         String name)
                           throws org.apache.fulcrum.security.util.DataBackendException,
                                  org.apache.fulcrum.security.util.UnknownEntityException

      Renames an existing Group.
      Parameters:
        `group` - The object describing the group to be renamed.
        `name` - the new name for the group.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the group does not exist.

    - #### renameRole

          void renameRole(org.apache.fulcrum.security.entity.Role role,
                        String name)
                          throws org.apache.fulcrum.security.util.DataBackendException,
                                 org.apache.fulcrum.security.util.UnknownEntityException

      Renames an existing Role.
      Parameters:
        `role` - The object describing the role to be renamed.
        `name` - the new name for the role.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the role does not exist.

    - #### renamePermission

          void renamePermission(org.apache.fulcrum.security.entity.Permission permission,
                              String name)
                                throws org.apache.fulcrum.security.util.DataBackendException,
                                       org.apache.fulcrum.security.util.UnknownEntityException

      Renames an existing Permission.
      Parameters:
        `permission` - The object describing the permission to be renamed.
        `name` - the new name for the permission.
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException` - if there was an error accessing the data backend.
        `org.apache.fulcrum.security.util.UnknownEntityException` - if the permission does not exist.

    - #### replaceRole

          void replaceRole(User user,
                         org.apache.fulcrum.security.entity.Role role,
                         org.apache.fulcrum.security.entity.Role newRole)
                           throws org.apache.fulcrum.security.util.DataBackendException,
                                  org.apache.fulcrum.security.util.UnknownEntityException

      Replaces transactionally the first given role with the second role for the given user.
      Parameters:
        `user` - the user.
        `role` - the old role
        `newRole` - the new role
      Throws:
        `org.apache.fulcrum.security.util.DataBackendException`
        `org.apache.fulcrum.security.util.UnknownEntityException`

Copyright © 2000–2018 The Apache Software Foundation. All rights reserved.