com.plumtree.remote.prc.collaboration.security
Interface IRole

public interface IRole

Interface that represents a project role that specifies which groups and users can access the objects in this project. Users, groups and communities can be added to and removed from a role. Note: Adding a non-existent user, group or community ID will succeed until the role has been updated and stored permanently via the store method, at which time the role instance will get refreshed. All other modifications also require the store method to be called.

See Security Examples.

Method Summary

void	addCommunityMember(int communityID, CommunityMemberType memberType) Adds a community member type to a role.
void	addMember(int memberID, MemberType memberType) Adds a member to a role.
AccessLevel	getAccessLevel(FunctionalArea objectType) Returns the access level for the given object type.
IProject	getBelongingProject() Returns an IProject object representing the project that this role belongs to.
java.lang.String	getDescription() Returns the object description for the role.
int	getID() Returns the object ID for the role.
int[]	getMemberIDs(MemberQueryType memberType) Returns the IDs of members who belong to this role based on the given member type.
java.lang.String	getName() Returns the object name for the role.
RoleType	getRoleType() Returns the type of role this object represents.
void	removeCommunityMember(int communityID, CommunityMemberType memberType) Removes a community member type from a role.
void	removeMember(int memberID, MemberType memberType) Removes a member from a role.
void	setAccessLevel(FunctionalArea objectType, AccessLevel accessLevel) Sets the access level for the given object type.
void	store() Refreshes the access levels and members contained in this role instance.

Method Detail

addCommunityMember

public void addCommunityMember(int communityID,
                               CommunityMemberType memberType)

Adds a community member type to a role. Adding a nonexistent ID will succeed until the role has been updated via the store method, at which time the role instance will get refreshed.

Parameters:

communityID - the community ID the user to be added belongs to; must be positive

memberType - the member type of the user in the community; cannot be null

Throws:

java.lang.IllegalArgumentException - if the community ID is not positive

addMember

public void addMember(int memberID,
                      MemberType memberType)

Adds a member to a role. Adding a nonexistent member ID will succeed until the role has been updated via the store method, at which time the role instance will get refreshed.
Note: Adding a single user to a role is NOT the same as adding a group with one or more users to a role. The ID of a user who is added with this method can be retrieved using getMemberIDs with MemberQueryType.ALL_USERS. However, for users belonging to a group that is then added to a role, IDs of individual users in the group will NOT be retrievable using getMemberIDs with MemberQueryType.All_USERS. Instead, MemberQueryType.All_GROUPS should be used to retrieve the group ID.

Parameters:

memberID - the ID of the member to be added to role; can be a portal user or a portal user group. Must be positive.

memberType - the type of member to be added; cannot be null

Throws:

java.lang.IllegalArgumentException - if the member ID is not positive

getAccessLevel

public AccessLevel getAccessLevel(FunctionalArea objectType)

Returns the access level for the given object type.

Parameters:

objectType - the object type; cannot be null

Returns:

the access level associated with the object type

getBelongingProject

public IProject getBelongingProject()
                             throws CollaborationException,
                                    java.rmi.RemoteException

Returns an IProject object representing the project that this role belongs to.

Returns:

the project that this object belongs to

Throws:

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

getDescription

public java.lang.String getDescription()

Returns the object description for the role.

Returns:

the object description for the role

getID

public int getID()

Returns the object ID for the role.

Returns:

the object ID for the role

getMemberIDs

public int[] getMemberIDs(MemberQueryType memberType)
                   throws CollaborationException,
                          java.rmi.RemoteException

Returns the IDs of members who belong to this role based on the given member type. This method can be used to retrieve users who are added to a role using addMember with MemberType.USER, or groups that are added to a role using addMember with MemberType.GROUP.
Note: Adding a single user to a role is NOT the same as adding a group with one or more users to a role. The ID of a user who is added as a user member type can be retrieved using this method with MemberQueryType.ALL_USER. However, for users belonging to a group that is then added to a role as a group member type, IDs of individual users in the group will NOT be retrievable using getMemberIDs with MemberQueryType.ALL_USER. Instead, MemberQueryType.All_GROUPS should be used to retrieve the group ID.

Parameters:

memberType - the type of members to retrieve from this role; cannot be null

Returns:

an int array of IDs describing users belong to this role based on the given member type

Throws:

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

getName

public java.lang.String getName()

Returns the object name for the role.

Returns:

the object name for the role

getRoleType

public RoleType getRoleType()

Returns the type of role this object represents.

Returns:

the type of role this object represents

removeCommunityMember

public void removeCommunityMember(int communityID,
                                  CommunityMemberType memberType)

Removes a community member type from a role. Note: Removing a nonexistent member will be ignored.

Parameters:

communityID - the community ID the member to be removed belongs to; must be positive

memberType - the member type of the user in the community; cannot be null

Throws:

java.lang.IllegalArgumentException - if the community ID is not positive

removeMember

public void removeMember(int memberID,
                         MemberType memberType)

Removes a member from a role. Note: Removing a nonexistent member id will be ignored.

Parameters:

memberID - the ID of the member to be removed from the role; can be a portal user, or a portal user group. Must be positive.

memberType - the type of member to be removed; cannot be null

Throws:

java.lang.IllegalArgumentException - if the member ID is not positive

setAccessLevel

public void setAccessLevel(FunctionalArea objectType,
                           AccessLevel accessLevel)
                    throws CollaborationException

Sets the access level for the given object type. Note: Modifying the access level will not be stored permanently or invalidated until the store method is called. This method cannot be called on a leader role, since the access level of a LEADER role cannot be modified. This method is for setting access level for individual functional areas within a project; to set the default project access level, use IProject.setAccessLevel method.

 //sample code - how to modify the access level for a functional area.
 //retrieve the member role of the project
 IRole memberRole = project.getRole(RoleType.MEMBER);
 
 //change the member role to have ADMIN access level for DOCUMENT functional area
 role.setAccessLevel(FunctionalArea.DOCUMENT, AccessLevel.ADMIN);
 
 //need to store the role to persist the access level change
 role.store();
 

Parameters:

objectType - the object type; cannot be null

accessLevel - the access level; cannot be null

Throws:

CollaborationException - if this role is a LEADER role

store

public void store()
           throws CollaborationException,
                  java.rmi.RemoteException

Refreshes the access levels and members contained in this role instance. Any modifications to IRole will not be stored permanently until this method is called.

Throws:

CollaborationException - if anu invalid IDs were added to the role with addMember prior to this call. Includes a detailed message denoting all the invalid IDs.

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call