com.liferay.portal.security.membershippolicy
Interface UserGroupMembershipPolicy

All Known Implementing Classes:

BaseUserGroupMembershipPolicy, DummyUserGroupMembershipPolicy

public interface UserGroupMembershipPolicy

Provides the User Group Membership Policy interface, allowing customization of user membership regarding user groups.

User Group Membership Policies define the user groups a user is allowed to be a member of and the user groups the user must be a member of.

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 user group B.
• If the user is added to user group A, he will automatically be added to user group B.
• The user must have the Administrator Role in order to be added to user group "Admin User Group".

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

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

Method Summary

void	checkMembership(long[] userIds, long[] addUserGroupIds, long[] removeUserGroupIds) Checks if the users can be added to and removed from the respective user groups.
boolean	isMembershipAllowed(long userId, long userGroupId) Returns true if the user can be added to the user group.
boolean	isMembershipRequired(long userId, long userGroupId) Returns true if user group membership for the user is mandatory.
void	propagateMembership(long[] userIds, long[] addUserGroupIds, long[] removeUserGroupIds) Performs membership policy related actions after the users are added to and removed from the respective user groups.
void	verifyPolicy() Checks the integrity of the membership policy of each of the portal's user groups and performs operations necessary for the compliance of each user group.
void	verifyPolicy(UserGroup userGroup) Checks the integrity of the membership policy of the user group and performs operations necessary for the user group's compliance.
void	verifyPolicy(UserGroup userGroup, UserGroup oldUserGroup, Map<String,Serializable> oldExpandoAttributes) Checks the integrity of the membership policy of the user group, with respect to the user group's new attribute values and expando attributes, and performs operations necessary for the compliance of the user group.

Method Detail

checkMembership

void checkMembership(long[] userIds,
                     long[] addUserGroupIds,
                     long[] removeUserGroupIds)
                     throws PortalException,
                            SystemException

Checks if the users can be added to and removed from the respective user groups.

Liferay's core services call this method before adding the users to and removing the users from the respective user groups. 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 user groups

addUserGroupIds - the primary keys of the user groups to which the users are to be added (optionally null)

removeUserGroupIds - the primary keys of the user groups from which the users are to be removed (optionally null)

Throws:

PortalException - if any one user could not be added to a user group, if any one user could not be removed from a user group, or if a portal exception occurred

SystemException - if a system exception occurred

isMembershipAllowed

boolean isMembershipAllowed(long userId,
                            long userGroupId)
                            throws PortalException,
                                   SystemException

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

Parameters:

userId - the primary key of the user

userGroupId - the primary key of the user group

Returns:

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

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

isMembershipRequired

boolean isMembershipRequired(long userId,
                             long userGroupId)
                             throws PortalException,
                                    SystemException

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

Parameters:

userId - the primary key of the user

userGroupId - the primary key of the user group

Returns:

true if user group membership for the user is mandatory; false otherwise

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

propagateMembership

void propagateMembership(long[] userIds,
                         long[] addUserGroupIds,
                         long[] removeUserGroupIds)
                         throws PortalException,
                                SystemException

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

The actions must ensure the integrity of each user group's membership policy. For example, some actions for implementations to consider performing are:

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

Parameters:

userIds - the primary key of the users to be added or removed

addUserGroupIds - the primary keys of the user groups to which the users were added (optionally null)

removeUserGroupIds - the primary keys of the user groups from which the users were removed (optionally null)

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 user groups and performs operations necessary for the compliance of each user group. 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(UserGroup userGroup)
                  throws PortalException,
                         SystemException

Checks the integrity of the membership policy of the user group and performs operations necessary for the user group's compliance.

Parameters:

userGroup - the user group to verify

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred

verifyPolicy

void verifyPolicy(UserGroup userGroup,
                  UserGroup oldUserGroup,
                  Map<String,Serializable> oldExpandoAttributes)
                  throws PortalException,
                         SystemException

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

The actions must ensure the integrity of the user group's membership policy based on what has changed in the user group's attribute values and expando attributes.

For example, if the membership policy is that user groups with the expando attribute A should only allow administrators, then this method could enforce that policy using the following logic:

• If the oldExpandoAttributes include the expando attribute A and the new expando attributes include it too, then no action needs to be performed regarding the policy. Note, the new expando attributes can be obtained by calling assetTagLocalService.getTags(Group.class.getName(), group.getGroupId());.
• If the oldExpandoAttributes include the expando attribute A and the new expando attributes don't include it, then no action needs to be performed regarding the policy, as non-administrator users need not be removed.
• However, if the oldExpandoAttributes don't include the expando attribute A and the new expando attributes include it, any user group user that does not have the Administrator role must be removed from the user group.

Parameters:

userGroup - the added or updated user group to verify

oldUserGroup - the old user group

oldExpandoAttributes - the old expando attributes

Throws:

PortalException - if a portal exception occurred

SystemException - if a system exception occurred