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 usingaddInheritedRole(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 toRoleDescriptor.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 aRoleUpdateException
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, aPrivilegeNotFoundException
will be thrown as those are not context-based privileges. Will returntrue
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.
-
-