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