com.ibm.itim.apps.identity
Class RoleMO

java.lang.Object
  com.ibm.itim.apps.identity.RoleMO

public class RoleMO
extends java.lang.Object

Managed object representing an organizational role, either static or dynamic. In general it should be noted that the value object for a static role is represented by the Role class, and the value object for a dynamic role is represented by the DynamicRole class.

See Also:

Role, DynamicRole

Constructor Summary

RoleMO(PlatformContext platform, javax.security.auth.Subject subject, DistinguishedName name)
Constructs the the managed object with a platform context, a subject, and the distinguished name of the object to manage.

Method Summary

Request	addMember(PersonMO member, java.util.Date scheduledTime) Adds a new member to the specified role.
Request	addMember(PersonMO member, java.util.Date scheduledTime, java.lang.String justification) Adds a new member to the specified role.
Request	addMember(PersonMO member, java.util.Set<RoleAssignmentObject> assignmentData, java.util.Date scheduledTime) This API adds a new member to the specified role.
Request	addMember(PersonMO member, java.util.Set<RoleAssignmentObject> assignmentData, java.util.Date scheduledTime, java.lang.String justification) This API adds a new member to the specified role.
java.util.Set<RoleAssignmentAttribute>	getAllAssignmentAttributes() Returns all assignment attributes for this role and its parent roles.
java.util.Set<RoleAssignmentAttribute>	getAssignmentAttributes() Returns role assignment attributes for this role.
OrganizationalContainerMO	getContainer() Returns the current parent container in the tree.
Role	getData() Returns a current snapshot of the data defining the provisioning object.
DistinguishedName	getDistinguishedName() Returns the distinguished name of the managed object
java.util.Collection<RoleMO>	getMemberRoles() Retrieves the immediate member roles of the role.
java.util.Collection	getMembers() Retrieves the members of the role.
void	getMembers(SearchResultsMO results) Retrieves the members of the role.
java.util.Collection<RoleMO>	getParentRoles() Returns all immediate parent roles of the role.
boolean	hasMembers(DistinguishedName roleDN) check whether current role has any member associated with it.
boolean	hasRoleMembers(DistinguishedName roleDN) Check whether the role has role members.
boolean	isAssignmentAttributeInUse(java.lang.String assignmentAttributeName) Returns true if there is any person with the assignment value for the specified assignment attribute.
boolean	isDynamicRole() check whether it's a dynamic role or an organizational role
Request	remove(java.util.Date scheduledTime) Removes the managed object from the provisioning platform.
Request	removeMember(PersonMO member, java.util.Date scheduledTime) Removes a member from the role.
Request	removeMember(PersonMO member, java.util.Date scheduledTime, java.lang.String justification) Removes a member from the role.
void	setAssignmentAttributes(java.util.Set<RoleAssignmentAttribute> assignmentAttributes) Sets assignment attributes to this role.
Request	update(Role r, java.util.Date scheduledTime) Updates the managed object.
Request	updateRoleHierarchy(java.util.List<RoleMO> rolesAdded, java.util.List<RoleMO> rolesDeleted, java.util.Date scheduledTime) Updates the role hierarchy of the managed object using asynchronous Identity Manager workflow.
java.util.Collection<IPolicyResult>	validateSeparationOfDuty(RoleMO memberRole) Validate separation of duty violation for the memberRole to be added to the role

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RoleMO

public RoleMO(PlatformContext platform,
              javax.security.auth.Subject subject,
              DistinguishedName name)

Constructs the the managed object with a platform context, a subject, and the distinguished name of the object to manage.

Parameters:

platform - PlatformContext holding platform connection information.

subject - Subject representing the authenticated caller.

name - DistinguishedName identifying the container.

Method Detail

getDistinguishedName

public DistinguishedName getDistinguishedName()

Returns the distinguished name of the managed object

Returns:

DistinguishedName of the managed object.

getData

public Role getData()
             throws java.rmi.RemoteException,
                    ApplicationException

Returns a current snapshot of the data defining the provisioning object.

Returns:

Role object holding attribute information.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve data.

getContainer

public OrganizationalContainerMO getContainer()
                                       throws java.rmi.RemoteException,
                                              ApplicationException

Returns the current parent container in the tree.

Returns:

OrganizationalContainerMO representing the parent container.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve parent.

remove

public Request remove(java.util.Date scheduledTime)
               throws AuthorizationException,
                      ApplicationException,
                      java.rmi.RemoteException

Removes the managed object from the provisioning platform. The removal of the role will not be allowed if a provisioning policy references it. For static roles only, the removal will not be allowed if there are existing members in the role.

Parameters:

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date and time of the client machine is not a safe technique to use, since the date and time of the client machine may not be the same as the date and time of the ITIM server machine. This parameter is only applicable for dynamic roles. If the RoleMO represents a static role, this parameter is ignored and may be null.

Returns:

Request object representing the operation's status. NULL when it is an organizational role removal. Organizational role removal is a synchronous operation.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to remove the role.

ApplicationException - Thrown if unable to remove the role. This may possibly be caused by a provisioning policy still referencing the role, or by the presence of members if the role is static.

update

public Request update(Role r,
                      java.util.Date scheduledTime)
               throws java.rmi.RemoteException,
                      AuthorizationException,
                      SchemaViolationException,
                      ApplicationException

Updates the managed object. A Role value object is provided with the changes to make.

Parameters:

r - Role value object with changes to make. Set the eraccessdescription attribute to create a role accesss description in the Identity Service Center access catalog. If the eraccessdescription attribute is not provided, the role's description value will be copied to eraccessdescription attribute and synchronized to the access catalog.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date and time of the client machine is not a safe technique to use, since the date and time of the client machine may not be the same as the date and time of the ITIM server machine. This parameter is applicable only for dynamic roles. If the RoleMO represents a static role, this parameter is ignored and may be null.

Returns:

Request object representing the operation's status. NULL when it's a static role modification. Static role modification is a synchronous operation.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to change the role. Note, even if only one of the attributes being changed is not writable for the client, the entire request will fail and this exception will be thrown.

SchemaViolationException - Thrown if any of the attributes in the given Role are invalid or not part of the schema.

ApplicationException - Thrown if unable to update the role. This may possibly be caused by the role being removed by another client previous to this call.

getMembers

public java.util.Collection getMembers()
                                throws java.rmi.RemoteException,
                                       ApplicationException

Retrieves the members of the role. The collection returned will only contain PersonMO the client is authorized to view (search for) and PersonMO that the client has permission for reading the Role attribute. No AuthorizationException will be thrown, only a reduced list will be returned.

Returns:

Collection of PersonMO's representing the role's members.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve members of the role. This may possibly be caused by the role being removed by another client previous to this call.

getMemberRoles

public java.util.Collection<RoleMO> getMemberRoles()
                                            throws java.rmi.RemoteException,
                                                   ApplicationException

Retrieves the immediate member roles of the role. The collection of immediate member roles will be returned if and only if the client is authorized to read the member role attribute of the parent role. No AuthorizationException will be thrown, only a reduced list will be returned.

Returns:

Collection of RoleMO that are the immediate member roles.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve child roles of the role. This may possibly be caused by the role being removed by another client previous to this call.

getMembers

public void getMembers(SearchResultsMO results)
                throws java.rmi.RemoteException,
                       ApplicationException

Retrieves the members of the role. Note, only members the client is authorized to search and members the client is authorized role assignment knowledge of will be returned. No AuthorizationException will be thrown, only a reduced list will be returned.

Parameters:

results - SearchResultsMO to hold the results of the search. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve members of the role. This may possibly be caused by the role being removed by another client previous to this call.

addMember

public Request addMember(PersonMO member,
                         java.util.Date scheduledTime)
                  throws java.rmi.RemoteException,
                         AuthorizationException,
                         ApplicationException

Adds a new member to the specified role. This method only applies to static roles and must not be invoked on a dynamic role. The UnsupportedOperationException is thrown if this method is called for the dynamic role.

Parameters:

member - PersonMO represents the new member.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date and time of the client machine is not a safe technique to use, since the date and time of the client machine may not be the same as the date and time of the ITIM server machine.

Returns:

Request object representing the operation's status.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to change the role or change the role assignment of the user.

ApplicationException - Thrown if unable to update the role membership. This may possibly be caused by the role or member being removed by another client previous to this call.

java.lang.UnsupportedOperationException - Thrown if this method is called on a dynamic role.

addMember

public Request addMember(PersonMO member,
                         java.util.Date scheduledTime,
                         java.lang.String justification)
                  throws java.rmi.RemoteException,
                         AuthorizationException,
                         ApplicationException

Adds a new member to the specified role. This method only applies to static roles and should not be invoked on a dynamic role.

Parameters:

member - PersonMO representing the new member.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

justification - The justification provided by the requester while adding a new member to the specified role.

Returns:

Request object representing the operation's status.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to change the role or change the role assignment of the user.

ApplicationException - Thrown if unable to update the role membership. This may possibly be caused by the role or member being removed by another client previous to this call.

addMember

public Request addMember(PersonMO member,
                         java.util.Set<RoleAssignmentObject> assignmentData,
                         java.util.Date scheduledTime)
                  throws java.rmi.RemoteException,
                         AuthorizationException,
                         ApplicationException

This API adds a new member to the specified role. It also sets role assignment attribute values for the role and for all parent roles including all ascendant roles. This method only applies to static roles and must not be invoked on a dynamic role. The UnsupportedOperationException is thrown if this method is called for the dynamic role.

Parameters:

member - PersonMO represents the new member.

assignmentData - The set of RoleAssignmentObject that has the assignment value changes for the role and all of the parent roles.

scheduledTime - The scheduled starting time of the process. If null, the process starts immediately. Note: If this method is invoked remotely, passing this parameter as the current date and time of the client machine might cause problems because the date and time of the client machine might not match the date and time of the Identity Manager server machine.

Returns:

Request object representing the status of the operation.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with the platform.

AuthorizationException - Thrown if the client is unauthorized to change the role or change the role assignment of the user.

ApplicationException - Thrown if unable to update the role membership. This can occur if the role or member was removed by another client prior to this call.

java.lang.UnsupportedOperationException - Thrown if this method is called on a dynamic role.

Since:

6.0

addMember

public Request addMember(PersonMO member,
                         java.util.Set<RoleAssignmentObject> assignmentData,
                         java.util.Date scheduledTime,
                         java.lang.String justification)
                  throws java.rmi.RemoteException,
                         AuthorizationException,
                         ApplicationException

This API adds a new member to the specified role. It also sets role assignment attribute values for the role and for all parent roles including all ascendant roles. This method only applies to static roles and must not be invoked on a dynamic role. The UnsupportedOperationException is thrown if this method is called for the dynamic role.

Parameters:

member - PersonMO represents the new member.

assignmentData - The set of RoleAssignmentObject that has the assignment value changes for the role and all of the parent roles.

scheduledTime - The scheduled starting time of the process. If null, the process starts immediately. Note: If this method is invoked remotely, passing this parameter as the current date and time of the client machine might cause problems because the date and time of the client machine might not match the date and time of the Identity Manager server machine.

justification - The justification provided by the requester while adding a new member to the specified role.

Returns:

Request object representing the status of the operation.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with the platform.

AuthorizationException - Thrown if the client is unauthorized to change the role or change the role assignment of the user.

ApplicationException - Thrown if unable to update the role membership. This can occur if the role or member was removed by another client prior to this call.

java.lang.UnsupportedOperationException - Thrown if this method is called on a dynamic role.

Since:

6.0

updateRoleHierarchy

public Request updateRoleHierarchy(java.util.List<RoleMO> rolesAdded,
                                   java.util.List<RoleMO> rolesDeleted,
                                   java.util.Date scheduledTime)
                            throws java.rmi.RemoteException,
                                   AuthorizationException,
                                   ApplicationException

Updates the role hierarchy of the managed object using asynchronous Identity Manager workflow. Users affected by the role hierarchy change will be re-evaluated, and the provisioning policies affected by the role hierarchy changes will be re-enforced.

Parameters:

rolesAdded - The role members to be added.

rolesDeleted - The role members to be removed.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. If this method is invoked remotely, passing this parameter as the current date and time of the client machine is not recommended because the date and time of the client machine might not be the same as the date and time of the Identity Manager server machine.

Returns:

The request object representing the status of the request.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with the platform.

AuthorizationException - Thrown if the client is unauthorized to update the role hierarchy of this managed object.

ApplicationException - Thrown if the request cannot be submitted.

removeMember

public Request removeMember(PersonMO member,
                            java.util.Date scheduledTime)
                     throws java.rmi.RemoteException,
                            AuthorizationException,
                            ApplicationException

Removes a member from the role. This method only applies to static roles and should not be invoked on a dynamic role.

Parameters:

member - PersonMO representing the member to remove.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date and time of the client machine is not a safe technique to use, since the date and time of the client machine may not be the same as the date and time of the ITIM server machine.

Returns:

Request object representing the operation's status.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to change the role or change the role assignment of the user.

ApplicationException - Thrown if unable to update the role membership. This may possibly be caused by the role or member being removed by another client previous to this call.

removeMember

public Request removeMember(PersonMO member,
                            java.util.Date scheduledTime,
                            java.lang.String justification)
                     throws java.rmi.RemoteException,
                            AuthorizationException,
                            ApplicationException

Removes a member from the role. This method only applies to static roles and should not be invoked on a dynamic role.

Parameters:

member - PersonMO representing the member to remove.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

justification - The justification provided by the requester while removing a member from the role.

Returns:

Request object representing the operation's status.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to change the role or change the role assignment of the user.

ApplicationException - Thrown if unable to update the role membership. This may possibly be caused by the role or member being removed by another client previous to this call.

isDynamicRole

public boolean isDynamicRole()
                      throws java.rmi.RemoteException,
                             ApplicationException

check whether it's a dynamic role or an organizational role

Throws:

java.rmi.RemoteException - Thrown if a communications related error occurs.

ApplicationException - Thrown if there is a naming exception or create exception.

hasMembers

public boolean hasMembers(DistinguishedName roleDN)
                   throws java.rmi.RemoteException,
                          ApplicationException

check whether current role has any member associated with it.

Parameters:

roleDN - The distinguished name of the role.

Returns:

true if current role has any member associated with it; false otherwise.

Throws:

java.rmi.RemoteException - Thrown if a communications related error occurs.

ApplicationException - Thrown if there is a naming exception or create exception.

hasRoleMembers

public boolean hasRoleMembers(DistinguishedName roleDN)
                       throws java.rmi.RemoteException,
                              ApplicationException

Check whether the role has role members.

Parameters:

roleDN - The distinguished name of the role.

Returns:

true if current role has any role member associated with it; false otherwise.

Throws:

java.rmi.RemoteException - Thrown if a communications related error occurs.

ApplicationException - Thrown if there is a naming exception or create exception.

validateSeparationOfDuty

public java.util.Collection<IPolicyResult> validateSeparationOfDuty(RoleMO memberRole)
                                                             throws java.rmi.RemoteException,
                                                                    ApplicationException

Validate separation of duty violation for the memberRole to be added to the role

Parameters:

memberRole - RoleMO representing the member role to be checked against separation of duty violation for this role.

Returns:

Collection a list IPolicyResult objects if the parent child relation will violate Separation of Duty Policy. Empty list means no violation.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to change the role or modify the member role attribute of the parent role.

ApplicationException - Thrown if unable to update the role membership. This may possibly be caused by the parent role being removed by another client previous to this call.

getParentRoles

public java.util.Collection<RoleMO> getParentRoles()
                                            throws ApplicationException,
                                                   java.rmi.RemoteException

Returns all immediate parent roles of the role. The collection of immediate parent roles will be returned if and only if the client is authorized to read the member role attribute of the role.

Returns:

Collection of RoleMO objects that are immediate parents of the role. The empty collection is returned if the user is not authorized to read the member role or there is no parent role.

Throws:

ApplicationException - Thrown if unable to get the parent roles. This can occur if the role is removed by another client prior to this call.

java.rmi.RemoteException - Thrown if unable to communicate with platform.

getAllAssignmentAttributes

public java.util.Set<RoleAssignmentAttribute> getAllAssignmentAttributes()
                                                                  throws ApplicationException,
                                                                         java.rmi.RemoteException

Returns all assignment attributes for this role and its parent roles. This method only applies to static roles and must not be invoked on a dynamic role. The UnsupportedOperationException is thrown if this method is called for the dynamic role.

Returns:

The set of RoleAssignmentAttribute object that represents role assignment attributes. The empty set is returned if there is no assignment attribute.

Throws:

ApplicationException - Thrown if unable to get the assignment attributes. This can occur if the role is removed by another client prior to this call.

java.rmi.RemoteException - Thrown if unable to communicate with platform.

java.lang.UnsupportedOperationException - Thrown if this method is called on a dynamic role.

Since:

6.0

getAssignmentAttributes

public java.util.Set<RoleAssignmentAttribute> getAssignmentAttributes()
                                                               throws ApplicationException,
                                                                      java.rmi.RemoteException

Returns role assignment attributes for this role. This method does not resolve the role hierarchy. This method only applies to static roles and must not be invoked on a dynamic role. The UnsupportedOperationException is thrown if this method is called for the dynamic role.

Returns:

The set of RoleAssignmentAttribute objects that represents role assignment attributes. The empty set is returned if there is no assignment attribute defined for this role. The name of assignment attribute, the distinguished name and the name of the role are stored in RoleAssignmentAttribute.

Throws:

ApplicationException - Thrown if unable to get the role. This can occur if the role is removed by another client prior to this call.

java.rmi.RemoteException - Thrown if unable to communicate with platform.

java.lang.UnsupportedOperationException - Thrown if this method is called on a dynamic role.

Since:

6.0

See Also:

RoleAssignmentAttribute

setAssignmentAttributes

public void setAssignmentAttributes(java.util.Set<RoleAssignmentAttribute> assignmentAttributes)
                             throws AuthorizationException,
                                    ApplicationException,
                                    java.rmi.RemoteException

Sets assignment attributes to this role. This method only applies to static roles and must not be invoked on a dynamic role. The UnsupportedOperationException is thrown if this method is called for the dynamic role.

Parameters:

assignmentAttributes - The set of RoleAssignmentAttribute object that represents role assignment attributes. Only the name of RoleAssignmentAttribute is used for this method. The current assignment attributes are replaced with the new assignment attributes that is passed to this method. Use the empty set to remove all the current assignment attributes. The null value is not allowed.

Throws:

AuthorizationException - Thrown if unable to set the assignment attributes. This can occur if the user is not authorized to modify the role or does not have the write permission for assignment attribute.

ApplicationException - Thrown if unable to get the role. This can occur if the role is removed by another client prior to this call.

java.rmi.RemoteException - Thrown if unable to communicate with platform.

java.lang.UnsupportedOperationException - Thrown if this method is called on a dynamic role.

Since:

6.0

See Also:

RoleAssignmentAttribute

isAssignmentAttributeInUse

public boolean isAssignmentAttributeInUse(java.lang.String assignmentAttributeName)
                                   throws ApplicationException,
                                          java.rmi.RemoteException

Returns true if there is any person with the assignment value for the specified assignment attribute. This method only applies to static roles and must not be invoked on a dynamic role. The UnsupportedOperationException is thrown if this method is called for the dynamic role.

Parameters:

assignmentAttributeName - The assignment attribute name.

Returns:

Returns true if any person has a value for the specified assignment attribute. Returns false otherwise.

Throws:

ApplicationException - Thrown if unable to determine whether there is a person with the assignment attribute value. This can occur if the role is removed by another client prior to this call.

java.rmi.RemoteException - Thrown if unable to communicate with platform.

java.lang.UnsupportedOperationException - Thrown if this method is called on a dynamic role.

Since:

6.0