Package com.sas.lsaf.security.role

## Interface RoleService

-     public interface RoleService

  Service for defining and managing the lifecycle of roles.

  A role is a logical grouping of privileges and members. A role is comprised of a set of privileges that are required to perform actions by a user or group assigned to that role. A role is associated with and scoped to a context where it is defined. All repository context types that are configured with the membership capability are available for role management features.

  A role created at a context using `createRole(String, String, String, Set, Set)` is considered a defined role and therefore the metadata, privileges and members can all be modified with this instance. An existing role can also be inherited by additional role contexts that are immediate descendants of the context. By creating the role using `addInheritedRole(String, String, Set)` the role is considered inherited at the context and therefore the metadata and privileges cannot be modified since the role is defined at a higher level and is only referenced at this lower level. The members assigned to the role at this context are the only items that can be modified. This inheritance model promotes the reuse of higher-level role definitions so security constraints can be managed in more global manner. A change in a higher-level role definition is automatically reflected in any lower inherited roles. The memberships for these roles are never shared; memberships within roles are always managed at the context the role was created. To determine if an existing role is defined or inherited please refer to `RoleDescriptor.isInherited()`.

  Members (users and groups) of the context may be assigned to the roles associated with the context. This will grant them all the privileges included in the role. Once a privilege is granted within the repository hierarchy, the member has that privilege at that point where it was granted as well as all descendant contexts.

  Since:
    2.1

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Role` | `addInheritedRole​(java.lang.String contextId, java.lang.String inheritedRoleId, java.util.Set<Principal> members)` | Adds an inherited role at the specified context.
    `Role` | `createRole​(java.lang.String contextId, java.lang.String name, java.lang.String description, java.util.Set<java.lang.String> scopedPrivilegeIds, java.util.Set<Principal> members)` | Creates a defined role at the specified context.
    `void` | `deleteRole​(java.lang.String roleId)` | Deletes the role as well as all inherited roles created from the role.
    `java.util.Set<RoleDescriptor>` | `getInheritedRoleDescriptorsByRole​(java.lang.String roleId)` | Gets all inherited roles across contexts that are associated with the specified role.
    `Role` | `getRoleById​(java.lang.String roleId)` | Get a role given its identifier.
    `Role` | `getRoleByName​(java.lang.String contextId, java.lang.String name)` | Gets a defined role by specifying its context and name.
    `RoleDescriptor` | `getRoleDescriptorById​(java.lang.String roleId)` | Gets a role descriptor given its identifier.
    `RoleDescriptor` | `getRoleDescriptorByName​(java.lang.String contextId, java.lang.String name)` | Gets a defined role descriptor by specifying its context and name.
    `java.util.Set<RoleDescriptor>` | `getRoleDescriptorsByContext​(java.lang.String contextId)` | Gets the lightweight representations of all roles that exist at the specified context.
    `java.util.Set<RoleDescriptor>` | `getRoleDescriptorsByContextAndPrincipal​(java.lang.String contextId, Principal member)` | Gets all of the roles at the specified context that the specified principal is a member of.
    `java.util.Set<RoleDescriptor>` | `getRoleDescriptorsByContextAndPrivilege​(java.lang.String contextId, java.lang.String scopedPrivilegeId)` | Gets all of the roles at a given context that include the specified privilege.
    `java.util.Set<Role>` | `getRolesByContext​(java.lang.String contextId)` | Gets all of the roles that exist at the specified context.
    `java.util.Set<Role>` | `getRolesByIds​(java.util.Set<java.lang.String> roleIds)` | Gets set of roles given their identifiers.
    `boolean` | `hasPrivilege​(java.lang.String contextId, java.lang.String scopedPrivilegeId, Principal member)` | Indicates whether the specified principal has the scoped privilege at the given context.
    `boolean` | `inheritedRoleExists​(java.lang.String contextId, java.lang.String roleId)` | Indicates whether an inherited role exists at the specified context with the specified parent role.
    `boolean` | `isPrincipalInRole​(java.lang.String roleId, Principal principal)` | Indicates whether the principal is a member of the specified role.
    `void` | `removePrincipalFromRoles​(java.lang.String contextId, Principal member)` | Removes the specified principal from all roles at the specified context.
    `void` | `removePrincipalsFromRoles​(java.lang.String contextId, java.util.Set<Principal> members)` | Removes the specified principals from all roles at the specified context.
    `boolean` | `roleExists​(java.lang.String contextId, java.lang.String name)` | Indicates whether a defined role exists at the specified context with the specified name.
    `Role` | `updateRole​(Role role)` | Updates the name, description, privileges or members of the specified role.

- - ### Method Detail

    - #### createRole

          Role createRole​(java.lang.String contextId,
                          java.lang.String name,
                          java.lang.String description,
                          java.util.Set<java.lang.String> scopedPrivilegeIds,
                          java.util.Set<Principal> members)
                   throws RoleExistsException,
                          PrivilegeNotFoundException,
                          InvalidRoleMemberException

      Creates a defined role at the specified context. For a given context, defined role names must be unique but this does not include inherited roles. Roles created in this manner allow name, description, privileges and members to be updated at any time.
      Parameters:
        `contextId` - the context where the role definition will be created.
        `name` - the name of the role.
        `description` - the description of the role.
        `scopedPrivilegeIds` - the scoped privileges to be included in the role.
        `members` - the principals to assign to this role.
      Returns:
        The newly created defined role.
      Throws:
        `RoleExistsException` - thrown when a role already exists with this name at the specified context.
        `PrivilegeNotFoundException` - thrown when a privilege provided is not defined or is not a scoped privilege.
        `InvalidRoleMemberException` - thrown if a principal being added is not a member of the context.

    - #### addInheritedRole

          Role addInheritedRole​(java.lang.String contextId,
                                java.lang.String inheritedRoleId,
                                java.util.Set<Principal> members)
                         throws RoleExistsException,
                                RoleNotFoundException,
                                InvalidRoleMemberException

      Adds an inherited role at the specified context. An inherited role is a role added to a child context from the parent context. A role can only be inherited once for a specific context. Roles created in this manner inherit the name, description and privileges assigned to this role but not the members. Inherited roles allow members to be updated at any time.
      Parameters:
        `contextId` - the context to assign the inherited role.
        `inheritedRoleId` - the role identifier of the parent context role definition.
        `members` - the principals to assign to this inherited role.
      Returns:
        the newly created inherited role.
      Throws:
        `RoleExistsException` - thrown if this role is already inherited at this context.
        `RoleNotFoundException` - thrown if the role specified does not exist or does not exist at the parent context.
        `InvalidRoleMemberException` - thrown if a principal being added is not a member of the context.

    - #### updateRole

          Role updateRole​(Role role)
                   throws RoleNotFoundException,
                          RoleExistsException,
                          RoleUpdateException,
                          PrivilegeNotFoundException,
                          InvalidRoleMemberException

      Updates the name, description, privileges or members of the specified role. The context of a role can never be modified on a role; any changes to the context will be ignored. If an inherited role is being updated only the membership can be changed. If the name, description or privileges of an inherited role are updated with this method a `RoleUpdateException` will be thrown.
      Parameters:
        `role` - the role to update.
      Returns:
        The updated role.
      Throws:
        `RoleNotFoundException` - thrown if the role specified does not exist.
        `RoleExistsException` - thrown when a new name specified in the update request already exists for the specified context.
        `RoleUpdateException` - thrown when the name, description or privileges are updated on an inherited role.
        `PrivilegeNotFoundException` - thrown when a privilege provided is not defined or is not a scoped privilege.
        `InvalidRoleMemberException` - thrown if a principal being added is not a member of the context.

    - #### deleteRole

          void deleteRole​(java.lang.String roleId)
                   throws RoleNotFoundException

      Deletes the role as well as all inherited roles created from the role. This method acts on both defined as well as inherited roles and in both cases will remove all inherited instances as well.
      Parameters:
        `roleId` - the identifier of the role to delete.
      Throws:
        `RoleNotFoundException` - thrown if the specified role does not exist.

    - #### roleExists

          boolean roleExists​(java.lang.String contextId,
                             java.lang.String name)

      Indicates whether a defined role exists at the specified context with the specified name. Only defined roles can be tested with this method since inherited roles can allow duplicate names if there are roles inherited from multiple contexts with the same name.
      Parameters:
        `contextId` - the context to test.
        `name` - the name of the role to test.
      Returns:
        `true` if a role with the specified name is defined at the context, `false` otherwise.

    - #### inheritedRoleExists

          boolean inheritedRoleExists​(java.lang.String contextId,
                                      java.lang.String roleId)

      Indicates whether an inherited role exists at the specified context with the specified parent role.
      Parameters:
        `contextId` - the context to search.
        `roleId` - the role identifier to search for.
      Returns:
        `true` if an inherited role exists at the specified context, `false` otherwise.

    - #### getRoleByName

          Role getRoleByName​(java.lang.String contextId,
                             java.lang.String name)
                      throws RoleNotFoundException

      Gets a defined role by specifying its context and name. This method will not return inherited roles since inherited role names can be duplicated.
      Parameters:
        `contextId` - the context to search.
        `name` - the name of the role to search for.
      Returns:
        The role if it exists.
      Throws:
        `RoleNotFoundException` - thrown if the specified role does not exist.

    - #### getRoleDescriptorByName

          RoleDescriptor getRoleDescriptorByName​(java.lang.String contextId,
                                                 java.lang.String name)
                                          throws RoleNotFoundException

      Gets a defined role descriptor by specifying its context and name. This method will not return inherited roles since inherited role names can be duplicated.
      Parameters:
        `contextId` - the context to search.
        `name` - the name of the role to search for.
      Returns:
        The role descriptor if it exists.
      Throws:
        `RoleNotFoundException` - thrown if the specified role does not exist.

    - #### getRoleById

          Role getRoleById​(java.lang.String roleId)
                    throws RoleNotFoundException

      Get a role given its identifier.
      Parameters:
        `roleId` - the identifier of the desired role.
      Returns:
        The role if it exists.
      Throws:
        `RoleNotFoundException` - thrown when the specified role does not exist.

    - #### getRoleDescriptorById

          RoleDescriptor getRoleDescriptorById​(java.lang.String roleId)
                                        throws RoleNotFoundException

      Gets a role descriptor given its identifier.
      Parameters:
        `roleId` - the identifier of the desired role descriptor.
      Returns:
        The role descriptor if it exists.
      Throws:
        `RoleNotFoundException` - thrown when the specified role does not exist.

    - #### getRolesByIds

          java.util.Set<Role> getRolesByIds​(java.util.Set<java.lang.String> roleIds)

      Gets set of roles given their identifiers. Only the roles found will be returned. If none are found then an empty set is returned.
      Parameters:
        `roleIds` - the identifiers of the roles to search for.
      Returns:
        The set of roles found with the specified identifiers.

    - #### getRolesByContext

          java.util.Set<Role> getRolesByContext​(java.lang.String contextId)

      Gets all of the roles that exist at the specified context. This includes roles that are defined as well as inherited roles.
      Parameters:
        `contextId` - the context to search..
      Returns:
        The set of roles that exist at the specified context.

    - #### getRoleDescriptorsByContext

          java.util.Set<RoleDescriptor> getRoleDescriptorsByContext​(java.lang.String contextId)

      Gets the lightweight representations of all roles that exist at the specified context.
      Parameters:
        `contextId` - the context to search.
      Returns:
        The set of role descriptors for all roles defined in that context.

    - #### removePrincipalFromRoles

          void removePrincipalFromRoles​(java.lang.String contextId,
                                        Principal member)

      Removes the specified principal from all roles at the specified context.
      Parameters:
        `contextId` - the context to search.
        `member` - the principal to remove from all roles at the specified context.

    - #### removePrincipalsFromRoles

          void removePrincipalsFromRoles​(java.lang.String contextId,
                                         java.util.Set<Principal> members)

      Removes the specified principals from all roles at the specified context.
      Parameters:
        `contextId` - the context to search.
        `members` - the set of principals to remove from all roles at the specified context.

    - #### isPrincipalInRole

          boolean isPrincipalInRole​(java.lang.String roleId,
                                    Principal principal)

      Indicates whether the principal is a member of the specified role.
      Parameters:
        `roleId` - the role identifier to search.
        `principal` - the principal to search for.
      Returns:
        `true` if the principal is a member of the specified role at the specified context, `false` otherwise.

    - #### getRoleDescriptorsByContextAndPrincipal

          java.util.Set<RoleDescriptor> getRoleDescriptorsByContextAndPrincipal​(java.lang.String contextId,
                                                                                Principal member)

      Gets all of the roles at the specified context that the specified principal is a member of.
      Parameters:
        `contextId` - the context to search.
        `member` - the principal to search for.
      Returns:
        The set of role descriptors at the specified context that the principal is a member of.

    - #### getRoleDescriptorsByContextAndPrivilege

          java.util.Set<RoleDescriptor> getRoleDescriptorsByContextAndPrivilege​(java.lang.String contextId,
                                                                                java.lang.String scopedPrivilegeId)
                                                                         throws PrivilegeNotFoundException

      Gets all of the roles at a given context that include the specified privilege. If none are found then an empty set is returned.
      Parameters:
        `contextId` - the context to search.
        `scopedPrivilegeId` - the scoped privilege in question.
      Returns:
        The set of role descriptors for all roles in that context that includes the specified scoped privilege.
      Throws:
        `PrivilegeNotFoundException` - thrown when the privilege provided is not defined or is not a scoped privilege.

    - #### getInheritedRoleDescriptorsByRole

          java.util.Set<RoleDescriptor> getInheritedRoleDescriptorsByRole​(java.lang.String roleId)
                                                                   throws RoleNotFoundException

      Gets all inherited roles across contexts that are associated with the specified role.
      Parameters:
        `roleId` - the role identifier to search for.
      Returns:
        The set of all inherited roles for that role in the system. If no inherited roles exist an empty set will be returned.
      Throws:
        `RoleNotFoundException` - thrown when the specified role does not exist.

    - #### hasPrivilege

          boolean hasPrivilege​(java.lang.String contextId,
                               java.lang.String scopedPrivilegeId,
                               Principal member)

      Indicates whether the specified principal has the scoped privilege at the given context. If a global privilege is provided, a `PrivilegeNotFoundException` will be thrown as those are not context-based privileges. Will return `true` if the member has been granted the privilege at a higher context.
      Parameters:
        `contextId` - the context to search.
        `scopedPrivilegeId` - the scoped privilege to search for.
        `member` - the principal to check.
      Returns:
        `true` if the specified principal has the scoped privilege assigned to them at the specified context or above, `false` otherwise.