OrganizationMembershipPolicy.java

/**
 * Copyright (c) 2000-present Liferay, Inc. All rights reserved.
 *
 * This library is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation; either version 2.1 of the License, or (at your option)
 * any later version.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 * details.
 */

package com.liferay.portal.kernel.security.membershippolicy;

import com.liferay.asset.kernel.model.AssetCategory;
import com.liferay.asset.kernel.model.AssetTag;
import com.liferay.portal.kernel.exception.PortalException;
import com.liferay.portal.kernel.model.Organization;
import com.liferay.portal.kernel.model.Role;
import com.liferay.portal.kernel.model.UserGroupRole;
import com.liferay.portal.kernel.security.permission.PermissionChecker;

import java.io.Serializable;

import java.util.List;
import java.util.Map;

/**
 * Provides the Organization Membership Policy interface, allowing customization
 * of user membership regarding organizations and organization roles.
 *
 * <p>
 * Organization Membership Policies define the organizations a user is allowed
 * to be a member of, the organizations the user must be a member of, the
 * organization roles the user is allowed to be assigned, and the organization
 * roles the user must be assigned.
 * </p>
 *
 * <p>
 * An implementation may include any number of rules and actions to enforce
 * those rules. The implementation may include rules and actions like the
 * following:
 * </p>
 *
 * <ul>
 * <li>
 * If a user is a member of the organization he will automatically be a member
 * of all its child organizations.
 * </li>
 * <li>
 * Only the members of the parent organization can become a member of this
 * organization.
 * </li>
 * <li>
 * If a user doesn't have the custom attribute A, he cannot be assigned to
 * organization B.
 * </li>
 * <li>
 * If the user is added to organization A, he will automatically be added to
 * organization B.
 * </li>
 * <li>
 * The user must have the Administrator Role in order to be added to
 * organization "Admin Organization".
 * </li>
 * <li>
 * All users with the custom attribute A will automatically have the
 * organization role B.
 * </li>
 * <li>
 * All the users with organization role A cannot have organization role B
 * (incompatible roles).
 * </li>
 * </ul>
 *
 * <p>
 * Liferay's core services invoke {@link #checkMembership(long[], long[],
 * long[])} to detect policy violations before adding the users to and removing
 * the users from the organizations. On passing the check, the service proceeds
 * with the changes and propagates appropriate related actions in the portal by
 * invoking {@link #propagateMembership(long[], long[], long[])}. On failing the
 * check, the service foregoes making the changes. For example, Liferay executes
 * this logic when adding and updating organizations, adding and removing users
 * with respect to organizations, and adding and removing organization roles
 * with respect to users.
 * </p>
 *
 * <p>
 * Liferay's UI calls the "is*" methods, such as {@link
 * #isMembershipAllowed(long, long)}, to determine appropriate options to
 * display to the user. For example, the UI calls {@link
 * #isMembershipAllowed(long, long)} to decide whether to enable the checkbox
 * for adding the user to the organization.
 * </p>
 *
 * <p>
 * Liferay's core services call {@link #isMembershipProtected(PermissionChecker,
 * long, long)} and {@link #isRoleProtected(PermissionChecker, long, long,
 * long)} to protect user organization memberships and organization role
 * assignments, appropriately.
 * </p>
 *
 * @author Roberto Díaz
 * @author Sergio González
 */
public interface OrganizationMembershipPolicy {

	/**
	 * Checks if the users can be added to and removed from the respective
	 * organizations.
	 *
	 * <p>
	 * Liferay's core services call this method before adding the users to and
	 * removing the users from the respective organizations. If this method
	 * throws an exception, the service foregoes making the changes.
	 * </p>
	 *
	 * @param userIds the primary keys of the users to be added and removed from
	 *        the organizations
	 * @param addOrganizationIds the primary keys of the organizations to which
	 *        the users are to be added (optionally <code>null</code>)
	 * @param removeOrganizationIds the primary keys of the organizations from
	 *        which the users are to be removed (optionally <code>null</code>)
	 */
	public void checkMembership(
			long[] userIds, long[] addOrganizationIds,
			long[] removeOrganizationIds)
		throws PortalException;

	/**
	 * Checks if the organization roles can be added to or removed from their
	 * users.
	 *
	 * <p>
	 * Liferay's core services call this method before adding the users to and
	 * removing the users from the respective organization roles. If this method
	 * throws an exception, the service foregoes making the changes.
	 * </p>
	 *
	 * @param addUserGroupRoles the user group roles to be added
	 * @param removeUserGroupRoles the user group roles to be removed
	 */
	public void checkRoles(
			List<UserGroupRole> addUserGroupRoles,
			List<UserGroupRole> removeUserGroupRoles)
		throws PortalException;

	/**
	 * Returns <code>true</code> if the user can be added to the organization.
	 * Liferay's UI calls this method.
	 *
	 * @param  userId the primary key of the user
	 * @param  organizationId the primary key of the organization
	 * @return <code>true</code> if the user can be added to the organization;
	 *         <code>false</code> otherwise
	 */
	public boolean isMembershipAllowed(long userId, long organizationId)
		throws PortalException;

	/**
	 * Returns <code>true</code> if the policy prevents the user from being
	 * removed from the organization by the user associated with the permission
	 * checker.
	 *
	 * @param  permissionChecker the permission checker referencing a user
	 * @param  userId the primary key of the user to check for protection
	 * @param  organizationId the primary key of the organization
	 * @return <code>true</code> if the policy prevents the user from being
	 *         removed from the organization by the user associated with the
	 *         permission checker; <code>false</code> otherwise
	 */
	public boolean isMembershipProtected(
			PermissionChecker permissionChecker, long userId,
			long organizationId)
		throws PortalException;

	/**
	 * Returns <code>true</code> if organization membership for the user is
	 * mandatory. Liferay's UI, for example, calls this method in deciding
	 * whether to enable the checkbox for removing the user from the
	 * organization.
	 *
	 * @param  userId the primary key of the user
	 * @param  organizationId the primary key of the organization
	 * @return <code>true</code> if organization membership for the user is
	 *         mandatory; <code>false</code> otherwise
	 */
	public boolean isMembershipRequired(long userId, long organizationId)
		throws PortalException;

	/**
	 * Returns <code>true</code> if the role can be added to the user on the
	 * organization. Liferay's UI calls this method.
	 *
	 * @param  userId the primary key of the user
	 * @param  organizationId the primary key of the organization
	 * @param  roleId the primary key of the role
	 * @return <code>true</code> if the role can be added to the user on the
	 *         organization; <code>false</code> otherwise
	 */
	public boolean isRoleAllowed(long userId, long organizationId, long roleId)
		throws PortalException;

	/**
	 * Returns <code>true</code> if the policy prevents the user from being
	 * removed from the role by the user associated with the permission checker.
	 *
	 * @param  permissionChecker the permission checker referencing a user
	 * @param  userId the primary key of the user to check for protection
	 * @param  organizationId the primary key of the organization
	 * @param  roleId the primary key of the role
	 * @return <code>true</code> if the policy prevents the user from being
	 *         removed from the role by the user associated with the permission
	 *         checker; <code>false</code> otherwise
	 */
	public boolean isRoleProtected(
			PermissionChecker permissionChecker, long userId,
			long organizationId, long roleId)
		throws PortalException;

	/**
	 * Returns <code>true</code> if the role is mandatory for the user on the
	 * organization. Liferay's UI calls this method.
	 *
	 * @param  userId the primary key of the user
	 * @param  organizationId the primary key of the organization
	 * @param  roleId the primary key of the role
	 * @return <code>true</code> if the role is mandatory for the user on the
	 *         organization; <code>false</code> otherwise
	 */
	public boolean isRoleRequired(long userId, long organizationId, long roleId)
		throws PortalException;

	/**
	 * Performs membership policy related actions after the users are added to
	 * and removed from the respective organizations. Liferay's core services
	 * call this method after adding and removing the users to and from the
	 * respective organizations.
	 *
	 * <p>
	 * The actions must ensure the integrity of each organization's membership
	 * policy. For example, some actions for implementations to consider
	 * performing are:
	 * </p>
	 *
	 * <ul>
	 * <li>
	 * Adding the users to the child organizations of each organization to which
	 * the users
	 * were added.
	 * </li>
	 * <li>
	 * Removing the users from the child organizations of each organization from
	 * which the users
	 * were removed.
	 * </li>
	 * </ul>
	 *
	 * @param userIds the primary key of the users to be added or removed
	 * @param addOrganizationIds the primary keys of the organizations to which
	 *        the users were added (optionally <code>null</code>)
	 * @param removeOrganizationIds the primary keys of the organizations from
	 *        which the users were removed (optionally <code>null</code>)
	 */
	public void propagateMembership(
			long[] userIds, long[] addOrganizationIds,
			long[] removeOrganizationIds)
		throws PortalException;

	/**
	 * Performs membership policy related actions after the respective
	 * organization 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.
	 *
	 * <p>
	 * The actions must ensure the membership policy of each organization role.
	 * For example, some actions for implementations to consider performing are:
	 * </p>
	 *
	 * <ul>
	 * <li>
	 * If the role A is added to a user, role B should be added too.
	 * </li>
	 * <li>
	 * If the role A is removed from a user, role B should be removed too.
	 * </li>
	 * </ul>
	 *
	 * @param addUserGroupRoles the user group roles added
	 * @param removeUserGroupRoles the user group roles removed
	 */
	public void propagateRoles(
			List<UserGroupRole> addUserGroupRoles,
			List<UserGroupRole> removeUserGroupRoles)
		throws PortalException;

	/**
	 * Checks the integrity of the membership policy of each of the portal's
	 * organizations and performs operations necessary for the compliance of
	 * each organization and organization role. This method can be triggered
	 * manually from the Control Panel. If the
	 * <code>membership.policy.auto.verify</code> portal property is
	 * <code>true</code> this method is triggered when starting Liferay and
	 * every time a membership policy hook is deployed.
	 */
	public void verifyPolicy() throws PortalException;

	/**
	 * Checks the integrity of the membership policy of the organization and
	 * performs operations necessary for the organization's compliance.
	 *
	 * @param organization the organization to verify
	 */
	public void verifyPolicy(Organization organization) throws PortalException;

	/**
	 * Checks the integrity of the membership policy of the organization, with
	 * respect to the organization's new attribute values, categories, tags, and
	 * expando attributes, and performs operations necessary for the compliance
	 * of the organization and its organization roles. Liferay calls this method
	 * when adding and updating organizations.
	 *
	 * <p>
	 * The actions must ensure the integrity of the organization's membership
	 * policy based on what has changed in the organization's attribute values,
	 * categories, tags, and expando attributes.
	 * </p>
	 *
	 * <p>
	 * For example, if the membership policy is that organizations with the
	 * "admnistrator" tag should only allow administrators as users, then this
	 * method could enforce that policy using the following logic:
	 * </p>
	 *
	 * <ul>
	 * <li>
	 * If the old tags include the "administrator" tag and the new tags include
	 * it too, then no action needs to be performed regarding the
	 * policy. Note, the new tags can be obtained by calling
	 * <code>assetTagLocalService.getTags(Group.class.getName(),
	 * group.getGroupId());</code>.
	 * </li>
	 * <li>
	 * If the old tags include the "administrator" tag and the new tags don't
	 * include it,
	 * then no action needs to be performed regarding the
	 * policy, as non-administrator users need not be removed.
	 * </li>
	 * <li>
	 * However, if the old tags don't include the "administrator" tag, but the
	 * new tags include it, any organization user that does not have the
	 * Administrator role must be removed from the organization.
	 * </li>
	 * </ul>
	 *
	 * @param organization the added or updated organization to verify
	 * @param oldOrganization the old organization
	 * @param oldAssetCategories the old categories
	 * @param oldAssetTags the old tags
	 * @param oldExpandoAttributes the old expando attributes
	 */
	public void verifyPolicy(
			Organization organization, Organization oldOrganization,
			List<AssetCategory> oldAssetCategories, List<AssetTag> oldAssetTags,
			Map<String, Serializable> oldExpandoAttributes)
		throws PortalException;

	/**
	 * Checks the integrity of the membership policy of the organization role
	 * and performs operations necessary for the role's compliance.
	 *
	 * @param role the role to verify
	 */
	public void verifyPolicy(Role role) throws PortalException;

	/**
	 * Checks the integrity of the membership policy of the organization role,
	 * with respect to its expando attributes, and performs operations necessary
	 * for the role's compliance. Liferay calls this method when adding and
	 * updating organization roles.
	 *
	 * @param role the added or updated role to verify
	 * @param oldRole the old role
	 * @param oldExpandoAttributes the old expando attributes
	 */
	public void verifyPolicy(
			Role role, Role oldRole,
			Map<String, Serializable> oldExpandoAttributes)
		throws PortalException;

}