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 088 * from 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 * @throws PortalException if any one role violated the policy or if a 094 * portal exception occurred 095 */ 096 public void checkRoles( 097 long[] userIds, long[] addRoleIds, long[] removeRoleIds) 098 throws PortalException; 099 100 /** 101 * Returns <code>true</code> if the role can be added to the user. Liferay's 102 * UI calls this method. 103 * 104 * @param userId the primary key of the user 105 * @param roleId the primary key of the role 106 * @return <code>true</code> if the role can be added to the user; 107 * <code>false</code> otherwise 108 * @throws PortalException if a portal exception occurred 109 */ 110 public boolean isRoleAllowed(long userId, long roleId) 111 throws PortalException; 112 113 /** 114 * Returns <code>true</code> if the role is mandatory for the user. 115 * Liferay's UI, for example, calls this method in deciding whether the 116 * checkbox to select a role will be enable. 117 * 118 * @param userId the primary key of the user 119 * @param roleId the primary key of the role 120 * @return <code>true</code> if the role is mandatory for the user; 121 * <code>false</code> otherwise 122 * @throws PortalException if a portal exception occurred 123 */ 124 public boolean isRoleRequired(long userId, long roleId) 125 throws PortalException; 126 127 /** 128 * Performs membership policy related actions after the respective roles are 129 * added to and removed from the affected users. Liferay's core services 130 * call this method after the roles are added to and removed from the users. 131 * 132 * <p> 133 * The actions must ensure the membership policy of each role. For example, 134 * some actions for implementations to consider performing are: 135 * </p> 136 * 137 * <ul> 138 * <li> 139 * If the role A is added to a user, role B should be added too. 140 * </li> 141 * <li> 142 * If the role A is removed from a user, role B should be removed too. 143 * </li> 144 * </ul> 145 * 146 * @param userIds the primary keys of the users 147 * @param addRoleIds the primary keys of the added roles 148 * @param removeRoleIds the primary keys of the removed roles 149 * @throws PortalException if a portal exception occurred 150 */ 151 public void propagateRoles( 152 long[] userIds, long[] addRoleIds, long[] removeRoleIds) 153 throws PortalException; 154 155 /** 156 * Checks the integrity of the membership policy of each of the portal's 157 * roles and performs operations necessary for the compliance of each role. 158 * This method can be triggered manually from the Control Panel. If the 159 * <code>membership.policy.auto.verify</code> portal property is 160 * <code>true</code> this method is triggered when starting Liferay and 161 * every time a membership policy hook is deployed. 162 * 163 * @throws PortalException if a portal exception occurred 164 */ 165 public void verifyPolicy() throws PortalException; 166 167 /** 168 * Checks the integrity of the membership policy of the role and performs 169 * operations necessary for the compliance of the role. 170 * 171 * @param role the role to verify 172 * @throws PortalException if a portal exception occurred 173 */ 174 public void verifyPolicy(Role role) throws PortalException; 175 176 /** 177 * Checks the integrity of the membership policy of the role, with respect 178 * to the role's new attribute values and expando attributes, and performs 179 * operations necessary for the role's compliance. Liferay calls this method 180 * when adding and updating roles. 181 * 182 * @param role the added or updated role to verify 183 * @param oldRole the old role 184 * @param oldExpandoAttributes the old expando attributes 185 * @throws PortalException if a portal exception occurred 186 */ 187 public void verifyPolicy( 188 Role role, Role oldRole, 189 Map<String, Serializable> oldExpandoAttributes) 190 throws PortalException; 191 192 }