com.sas.hls.security.role
Interface RoleDefinitionService


public interface RoleDefinitionService

Service for defining and managing the life cycle of roles and assigned roles. To assign users and groups to a role (See RoleAssignmentService).

Role is a logical grouping of privileges. A Role comprises of a set of privileges that are required to perform actions by a user assigned to that role. A Role is associated with and scoped to a context where it is defined. Role context is an object that implements the RoleContext interface (See RoleContext). Examples of RoleContext are Organization, Project and Analysis objects.

Role created at a context is automatically assigned to the context. An existing Role can be inherited by additional role contexts that are descendants of the context they are defined at. The association between a Role and a Role context is represented in the API using AssignedRole (See AssignedRole.

Members (users and groups) of that context may be assigned to the roles associated with the context. This will grant them all the privileges of the role.


Method Summary
 boolean assignedRoleExists(RoleContext context, RoleDescriptor roleDescriptor)
          Check if the given role is assigned to the context
 AssignedRole assignRoleToContext(RoleContext context, RoleDescriptor role)
          Assign an existing role to a context that is a child of the context that the role was defined at so that the inherited role definition may be used at another context.
 Role createRole(RoleContext roleContext, String name, String description, Set<Privilege> privileges)
          Create a role and assign role to the specified context.
 void deleteRole(RoleDescriptor roleDescriptor)
          Delete a role and remove its assignment from the context it was defined at.
 Set<AssignedRole> getAllAssignedRoles(RoleDescriptor role)
          Get all assignments of this role to contexts in the system
 Set<RoleDescriptor> getAllRolesByPrivilege(Privilege privilege)
          Get all roles defined which include the specified privilege.
 AssignedRole getAssignedRole(RoleContext context, RoleDescriptor role)
          Get the specified role assigned to the context
 Set<AssignedRole> getAssignedRoles(RoleContext roleContext)
          Get all inherited and defined roles assigned to the context.
 Role getRole(RoleContext roleContext, String name)
          Get a role by specifying its context and name
 Role getRoleByIdentifier(String identifier)
          Get a role given its identifier.
 Set<RoleDescriptor> getRoleDescriptors(RoleContext roleContext)
          Get light-weight representations of all roles defined in a given context.
 Set<Role> getRoles(RoleContext roleContext)
          Get all the roles defined in a given context
 Set<Role> getRolesByDescriptors(Set<RoleDescriptor> roleDescriptors)
          Get a set of roles given their role descriptors
 Set<Role> getRolesByIdentifiers(Set<String> identifiers)
          Get a set of roles given their identifiers
 Set<RoleDescriptor> getRolesByPrivilege(RoleContext roleContext, Privilege privilege)
          Get all roles defined in a given context which include the specified privilege.
 boolean roleExists(RoleContext roleContext, String name)
          Check if a role exists in a context
 void unassignAssignedRole(RoleDescriptor roleDescriptor)
          Remove all assignments of this role to inherited contexts.
 void unassignAssignedRoleFromContext(AssignedRole assignedRole)
          Remove an inherited role from context.
 Role updateRole(Role role)
          Update the definition of the specified role.
 

Method Detail

createRole

Role createRole(RoleContext roleContext,
                String name,
                String description,
                Set<Privilege> privileges)
                throws RoleContextNotFoundException,
                       RoleExistsException
Create a role and assign role to the specified context. For a given context, role names must be unique.

Parameters:
roleContext - The context of the role
name - The name of the role
description - Description of the role
privileges - The privileges to be included in the role
Returns:
the newly created role
Throws:
RoleContextNotFoundException - The context specified was not found
RoleExistsException - A role already exists with this name and context.

updateRole

Role updateRole(Role role)
                throws RoleNotFoundException,
                       RoleExistsException
Update the definition of the specified role. The context of a role cannot be modified.

Parameters:
role - the role to update
Returns:
the updated role
Throws:
RoleNotFoundException - The role specified was not found.
RoleExistsException - When a new name specified in the update request already exists for the context

deleteRole

void deleteRole(RoleDescriptor roleDescriptor)
                throws RoleNotFoundException
Delete a role and remove its assignment from the context it was defined at.

Parameters:
roleDescriptor - the role to delete
Throws:
RoleNotFoundException - The specified role was not found.

roleExists

boolean roleExists(RoleContext roleContext,
                   String name)
Check if a role exists in a context

Parameters:
roleContext - the context to search
name - the name of the role in question
Returns:
boolean value indicating if such a role with the specified name is defined at the context

getRole

Role getRole(RoleContext roleContext,
             String name)
             throws RoleNotFoundException
Get a role by specifying its context and name

Parameters:
roleContext - the context of the desired role
name - the name of the desired role
Returns:
the desired role
Throws:
RoleNotFoundException - The specified role could not be found.

getRoleByIdentifier

Role getRoleByIdentifier(String identifier)
                         throws RoleNotFoundException
Get a role given its identifier.

Parameters:
identifier - the identifier of the desired role
Returns:
the desired role
Throws:
RoleNotFoundException - The specified role could not be found.

getRoles

Set<Role> getRoles(RoleContext roleContext)
Get all the roles defined in a given context

Parameters:
roleContext - the context of the desired roles
Returns:
the set of roles defined in that context

getRoleDescriptors

Set<RoleDescriptor> getRoleDescriptors(RoleContext roleContext)
Get light-weight representations of all roles defined in a given context.

Parameters:
roleContext - the context of the desired roles
Returns:
the set of roleDescriptors for all roles defined in that context

getRolesByDescriptors

Set<Role> getRolesByDescriptors(Set<RoleDescriptor> roleDescriptors)
Get a set of roles given their role descriptors

Parameters:
roleDescriptors - the roleDescriptors of the desired roles
Returns:
the set of roles found

getRolesByIdentifiers

Set<Role> getRolesByIdentifiers(Set<String> identifiers)
Get a set of roles given their identifiers

Parameters:
identifiers - the identifiers of the desired roles
Returns:
the set of roles found with the specified identifiers

getAllRolesByPrivilege

Set<RoleDescriptor> getAllRolesByPrivilege(Privilege privilege)
Get all roles defined which include the specified privilege.

Parameters:
privilege - The privilege in question
Returns:
The set of roleDescriptors for all roles defined which include that privilege.

getRolesByPrivilege

Set<RoleDescriptor> getRolesByPrivilege(RoleContext roleContext,
                                        Privilege privilege)
Get all roles defined in a given context which include the specified privilege.

Parameters:
roleContext - The context to search
privilege - The privilege in question
Returns:
The set of roleDescriptors for all roles defined in that context which include the specified privilege.

assignRoleToContext

AssignedRole assignRoleToContext(RoleContext context,
                                 RoleDescriptor role)
                                 throws RoleAssignmentExistsException,
                                        RoleContextNotFoundException,
                                        RoleNotFoundException,
                                        RoleAssignmentExistsException,
                                        InvalidRoleAssignmentContextException
Assign an existing role to a context that is a child of the context that the role was defined at so that the inherited role definition may be used at another context.

Parameters:
context -
role -
Returns:
the assignedRole
Throws:
RoleAssignmentExistsException - The specified role is already assigned to this context.
RoleNotFoundException - The specified role could not be found.
RoleContextNotFoundException - The context where you want to make this role available can not be found.
RoleAssignmentExistsException - The role you want to make available to a context is already available.
InvalidRoleAssignmentContextException - This role can not be made available to this context (is the context where the role is defined a child of this context?)

unassignAssignedRoleFromContext

void unassignAssignedRoleFromContext(AssignedRole assignedRole)
                                     throws RoleAssignmentNotFoundException,
                                            RoleContextNotFoundException,
                                            RoleNotFoundException,
                                            RoleAssignmentExistsException
Remove an inherited role from context.

Parameters:
assignedRole - the assigned role to delete
Throws:
RoleAssignmentNotFoundException - The specified role assignment was not found.
RoleNotFoundException - The specified role was not found.
RoleContextNotFoundException - The specified context was not found.
RoleAssignmentExistsException

unassignAssignedRole

void unassignAssignedRole(RoleDescriptor roleDescriptor)
                          throws RoleNotFoundException,
                                 RoleAssignmentNotFoundException,
                                 RoleContextNotFoundException
Remove all assignments of this role to inherited contexts. The assignment to the context it was created at is not affected and can only be removed when this role is deleted.

Parameters:
roleDescriptor -
Throws:
RoleContextNotFoundException - The specified context was not found.
RoleNotFoundException - The specified role was not found.
RoleAssignmentNotFoundException - The specified roleAssignment was not found.

getAllAssignedRoles

Set<AssignedRole> getAllAssignedRoles(RoleDescriptor role)
Get all assignments of this role to contexts in the system

Parameters:
role - The role to search for.
Returns:
the set of all assignedRoles for the specified role.

assignedRoleExists

boolean assignedRoleExists(RoleContext context,
                           RoleDescriptor roleDescriptor)
Check if the given role is assigned to the context

Parameters:
context - The specified context
roleDescriptor - The role to search for.
Returns:
boolean value indicating if the specified role is assigned to the context.

getAssignedRole

AssignedRole getAssignedRole(RoleContext context,
                             RoleDescriptor role)
                             throws RoleAssignmentNotFoundException
Get the specified role assigned to the context

Parameters:
context - The specified context.
role - The role to search for in the context.
Returns:
the assigned role.
Throws:
RoleAssignmentNotFoundException - The specified role is not defined in that context.

getAssignedRoles

Set<AssignedRole> getAssignedRoles(RoleContext roleContext)
Get all inherited and defined roles assigned to the context.

Parameters:
roleContext - the context to search for.
Returns:
the set of all assignedRoles that define that role.


Copyright (c) 2012, SAS Institute Inc., Cary, NC, USA