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

public interface IRole

IRole 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 that adding a non-existent user, group or community ID will succeed until the role has been updated and stored permanently via the store method, whereby the role instance will get refreshed. All other modifications will also require the store method to be called.

See Security Examples.

Method Summary

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

Method Detail

addCommunityMember

public void addCommunityMember(int communityID,
                               CommunityMemberType memberType)

Adds a community member to a role. Note that adding a nonexistent member id will succeed until the role has been updated via the store method, whereby the role instance will get refreshed.

Parameters:

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

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

Throws:

java.lang.IllegalArgumentException - if 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, whereby the role instance will get refreshed.
Note that 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 - id of member to be added to role, can be a portal user, or a portal user group; must be positive

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

Throws:

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

getAccessLevel

public AccessLevel getAccessLevel(FunctionalArea objectType)

Returns the access level for a 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 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 is a communication problem during the execution of the remote method call.

getDescription

public java.lang.String getDescription()

Returns the object description.

Returns:

string object description

getID

public int getID()

Returns the object ID.

Returns:

int object ID

getMemberIDs

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

Returns the ids of members be long 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 that 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 - type of members to retrieve from this role; cannot be null

Returns:

an int id array 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 is a communication problem during the execution of the remote method call

getName

public java.lang.String getName()

Returns the object name.

Returns:

string object name

getRoleType

public RoleType getRoleType()

Returns the type of role this object represents.

Returns:

type of role this object represents.

removeCommunityMember

public void removeCommunityMember(int communityID,
                                  CommunityMemberType memberType)

Removes a community member from a role. Note that removing a nonexistent member id will get ignored.

Parameters:

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

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

Throws:

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

removeMember

public void removeMember(int memberID,
                         MemberType memberType)

Removes a member from a role. Note that removing a nonexistent member id will get ignored.

Parameters:

memberID - id of member to be removed to role, can be a portal user, or a portal user group; must be positive

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

Throws:

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

setAccessLevel

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

Sets access level for a given object type. Note that modifying the access level will not be stored permanently nor be invalidated until 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 area within a project; to set the default project access level, please use IProject.setAccessLevel method.

 //Below sample code shows 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

Refresh 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 any invalid IDs are being added to the role with addMember method prior to this call, with a detailed message denoting all the invalid ids.

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