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.
      • 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.