001 /** 002 * Copyright (c) 2000-present Liferay, Inc. All rights reserved. 003 * 004 * This library is free software; you can redistribute it and/or modify it under 005 * the terms of the GNU Lesser General Public License as published by the Free 006 * Software Foundation; either version 2.1 of the License, or (at your option) 007 * any later version. 008 * 009 * This library is distributed in the hope that it will be useful, but WITHOUT 010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 011 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 012 * details. 013 */ 014 015 package com.liferay.portal.security.membershippolicy; 016 017 import com.liferay.portal.kernel.exception.PortalException; 018 import com.liferay.portal.model.Role; 019 020 import java.io.Serializable; 021 022 import java.util.Map; 023 024 /** 025 * Provides the Role Membership Policy interface, allowing customization of user 026 * membership regarding roles. 027 * 028 * <p> 029 * Role Membership Policies define the roles a user is allowed to be assigned, 030 * and the roles the user must be assigned. 031 * </p> 032 * 033 * <p> 034 * An implementation may include any number of rules and actions to enforce 035 * those rules. The implementation may include rules and actions like the 036 * following: 037 * </p> 038 * 039 * <ul> 040 * <li> 041 * If a user doesn't have the custom attribute A, he cannot be assigned to role 042 * B. 043 * </li> 044 * <li> 045 * If the user is added to role A, he will automatically be added to role B. 046 * </li> 047 * <li> 048 * All users with the custom attribute A will automatically have the role B. 049 * </li> 050 * <li> 051 * All the users with role A cannot have role B (incompatible roles). 052 * </li> 053 * </ul> 054 * 055 * <p> 056 * Liferay's core services invoke {@link #checkRoles(long[], long[], long[])} to 057 * detect policy violations before adding the users to and removing the users 058 * from the roles. On passing the check, the service proceeds with the changes 059 * and propagates appropriate related actions in the portal by invoking {@link 060 * #propagateRoles(long[], long[], long[])}. On failing the check, the service 061 * foregoes making the changes. For example, Liferay executes this logic when 062 * adding and updating roles, and adding and removing roles with respect to 063 * users. 064 * </p> 065 * 066 * <p> 067 * Liferay's UI calls the "is*" methods, such as {@link #isRoleAllowed(long, 068 * long)}, to determine appropriate options to display to the user. For example, 069 * the UI calls {@link #isRoleAllowed(long, long)} to decide whether to enable 070 * the checkbox for adding the role to the user. 071 * </p> 072 * 073 * @author Roberto D??az 074 * @author Sergio Gonz??lez 075 */ 076 public interface RoleMembershipPolicy { 077 078 /** 079 * Checks if the roles can be added to or removed from their users. 080 * 081 * <p> 082 * Liferay's core services call this method before adding the users to and 083 * removing the users from the respective roles. If this method throws an 084 * exception, the service foregoes making the changes. 085 * </p> 086 * 087 * @param userIds the primary keys of the users to be added and removed from 088 * the roles 089 * @param addRoleIds the primary keys of the roles to be added (optionally 090 * <code>null</code>) 091 * @param removeRoleIds the primary keys of the roles to be removed 092 * (optionally <code>null</code>) 093 */ 094 public void checkRoles( 095 long[] userIds, long[] addRoleIds, long[] removeRoleIds) 096 throws PortalException; 097 098 /** 099 * Returns <code>true</code> if the role can be added to the user. Liferay's 100 * UI calls this method. 101 * 102 * @param userId the primary key of the user 103 * @param roleId the primary key of the role 104 * @return <code>true</code> if the role can be added to the user; 105 * <code>false</code> otherwise 106 */ 107 public boolean isRoleAllowed(long userId, long roleId) 108 throws PortalException; 109 110 /** 111 * Returns <code>true</code> if the role is mandatory for the user. 112 * Liferay's UI, for example, calls this method in deciding whether the 113 * checkbox to select a role will be enable. 114 * 115 * @param userId the primary key of the user 116 * @param roleId the primary key of the role 117 * @return <code>true</code> if the role is mandatory for the user; 118 * <code>false</code> otherwise 119 */ 120 public boolean isRoleRequired(long userId, long roleId) 121 throws PortalException; 122 123 /** 124 * Performs membership policy related actions after the respective roles are 125 * added to and removed from the affected users. Liferay's core services 126 * call this method after the roles are added to and removed from the users. 127 * 128 * <p> 129 * The actions must ensure the membership policy of each role. For example, 130 * some actions for implementations to consider performing are: 131 * </p> 132 * 133 * <ul> 134 * <li> 135 * If the role A is added to a user, role B should be added too. 136 * </li> 137 * <li> 138 * If the role A is removed from a user, role B should be removed too. 139 * </li> 140 * </ul> 141 * 142 * @param userIds the primary keys of the users 143 * @param addRoleIds the primary keys of the added roles 144 * @param removeRoleIds the primary keys of the removed roles 145 */ 146 public void propagateRoles( 147 long[] userIds, long[] addRoleIds, long[] removeRoleIds) 148 throws PortalException; 149 150 /** 151 * Checks the integrity of the membership policy of each of the portal's 152 * roles and performs operations necessary for the compliance of each role. 153 * This method can be triggered manually from the Control Panel. If the 154 * <code>membership.policy.auto.verify</code> portal property is 155 * <code>true</code> this method is triggered when starting Liferay and 156 * every time a membership policy hook is deployed. 157 */ 158 public void verifyPolicy() throws PortalException; 159 160 /** 161 * Checks the integrity of the membership policy of the role and performs 162 * operations necessary for the compliance of the role. 163 * 164 * @param role the role to verify 165 */ 166 public void verifyPolicy(Role role) throws PortalException; 167 168 /** 169 * Checks the integrity of the membership policy of the role, with respect 170 * to the role's new attribute values and expando attributes, and performs 171 * operations necessary for the role's compliance. Liferay calls this method 172 * when adding and updating roles. 173 * 174 * @param role the added or updated role to verify 175 * @param oldRole the old role 176 * @param oldExpandoAttributes the old expando attributes 177 */ 178 public void verifyPolicy( 179 Role role, Role oldRole, 180 Map<String, Serializable> oldExpandoAttributes) 181 throws PortalException; 182 183 }