com.liferay.portal.security.membershippolicy
Interface RoleMembershipPolicy

All Known Implementing Classes:

BaseRoleMembershipPolicy, DummyRoleMembershipPolicy

public interface RoleMembershipPolicy

Provides the Role Membership Policy interface, allowing customization of user membership regarding roles.

Role Membership Policies define the roles a user is allowed to be assigned, and the roles the user must be assigned.

An implementation may include any number of rules and actions to enforce those rules. The implementation may include rules and actions like the following:

• If a user doesn't have the custom attribute A, he cannot be assigned to role B.
• If the user is added to role A, he will automatically be added to role B.
• All users with the custom attribute A will automatically have the role B.
• All the users with role A cannot have role B (incompatible roles).

Liferay's core services invoke checkRoles(long[], long[], long[]) to detect policy violations before adding the users to and removing the users from the roles. On passing the check, the service proceeds with the changes and propagates appropriate related actions in the portal by invoking propagateRoles(long[], long[], long[]). On failing the check, the service foregoes making the changes. For example, Liferay executes this logic when adding and updating roles, and adding and removing roles with respect to users.

Liferay's UI calls the "is*" methods, such as isRoleAllowed(long, long), to determine appropriate options to display to the user. For example, the UI calls isRoleAllowed(long, long) to decide whether to enable the checkbox for adding the role to the user.

Method Summary

void	checkRoles(long[] userIds, long[] addRoleIds, long[] removeRoleIds) Checks if the roles can be added to or removed from their users.
boolean	isRoleAllowed(long userId, long roleId) Returns true if the role can be added to the user.
boolean	isRoleRequired(long userId, long roleId) Returns true if the role is mandatory for the user.
void	propagateRoles(long[] userIds, long[] addRoleIds, long[] removeRoleIds) Performs membership policy related actions after the respective roles are added to and removed from the affected users.
void	verifyPolicy() Checks the integrity of the membership policy of each of the portal's roles and performs operations necessary for the compliance of each role.
void	verifyPolicy(Role role) Checks the integrity of the membership policy of the role and performs operations necessary for the compliance of the role.
void	verifyPolicy(Role role, Role oldRole, Map<String,Serializable> oldExpandoAttributes) Checks the integrity of the membership policy of the role, with respect to the role's new attribute values and expando attributes, and performs operations necessary for the role's compliance.

Method Detail

checkRoles

void checkRoles(long[] userIds,
                long[] addRoleIds,
                long[] removeRoleIds)
                throws PortalException,
                       SystemException

Checks if the roles can be added to or removed from their users.

Liferay's core services call this method before adding the users to and removing the users from the respective roles. If this method throws an exception, the service foregoes making the changes.

Parameters:

userIds - the primary keys of the users to be added and removed from the roles

addRoleIds - the primary keys of the roles to be added (optionally null)

removeRoleIds - the primary keys of the roles to be removed (optionally null)

Throws:

PortalException - if any one role violated the policy or if a portal exception occurred

SystemException - if a system exception occurred

isRoleAllowed

boolean isRoleAllowed(long userId,
                      long roleId)
                      throws PortalException,
                             SystemException

Returns true if the role can be added to the user. Liferay's UI calls this method.

Parameters:

userId - the primary key of the user

roleId - the primary key of the role

Returns:

true if the role can be added to the user; false otherwise

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

isRoleRequired

boolean isRoleRequired(long userId,
                       long roleId)
                       throws PortalException,
                              SystemException

Returns true if the role is mandatory for the user. Liferay's UI, for example, calls this method in deciding whether the checkbox to select a role will be enable.

Parameters:

userId - the primary key of the user

roleId - the primary key of the role

Returns:

true if the role is mandatory for the user; false otherwise

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

propagateRoles

void propagateRoles(long[] userIds,
                    long[] addRoleIds,
                    long[] removeRoleIds)
                    throws PortalException,
                           SystemException

Performs membership policy related actions after the respective roles are added to and removed from the affected users. Liferay's core services call this method after the roles are added to and removed from the users.

The actions must ensure the membership policy of each role. For example, some actions for implementations to consider performing are:

• If the role A is added to a user, role B should be added too.
• If the role A is removed from a user, role B should be removed too.

Parameters:

userIds - the primary keys of the users

addRoleIds - the primary keys of the added roles

removeRoleIds - the primary keys of the removed roles

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

verifyPolicy

void verifyPolicy()
                  throws PortalException,
                         SystemException

Checks the integrity of the membership policy of each of the portal's roles and performs operations necessary for the compliance of each role. This method can be triggered manually from the Control Panel. If the membership.policy.auto.verify portal property is true this method is triggered when starting Liferay and every time a membership policy hook is deployed.

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

verifyPolicy

void verifyPolicy(Role role)
                  throws PortalException,
                         SystemException

Checks the integrity of the membership policy of the role and performs operations necessary for the compliance of the role.

Parameters:

role - the role to verify

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

verifyPolicy

void verifyPolicy(Role role,
                  Role oldRole,
                  Map<String,Serializable> oldExpandoAttributes)
                  throws PortalException,
                         SystemException

Checks the integrity of the membership policy of the role, with respect to the role's new attribute values and expando attributes, and performs operations necessary for the role's compliance. Liferay calls this method when adding and updating roles.

Parameters:

role - the added or updated role to verify

oldRole - the old role

oldExpandoAttributes - the old expando attributes

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred