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.Organization; 019 import com.liferay.portal.model.Role; 020 import com.liferay.portal.model.UserGroupRole; 021 import com.liferay.portal.security.permission.PermissionChecker; 022 import com.liferay.portlet.asset.model.AssetCategory; 023 import com.liferay.portlet.asset.model.AssetTag; 024 025 import java.io.Serializable; 026 027 import java.util.List; 028 import java.util.Map; 029 030 /** 031 * Provides the Organization Membership Policy interface, allowing customization 032 * of user membership regarding organizations and organization roles. 033 * 034 * <p> 035 * Organization Membership Policies define the organizations a user is allowed 036 * to be a member of, the organizations the user must be a member of, the 037 * organization roles the user is allowed to be assigned, and the organization 038 * roles the user must be assigned. 039 * </p> 040 * 041 * <p> 042 * An implementation may include any number of rules and actions to enforce 043 * those rules. The implementation may include rules and actions like the 044 * following: 045 * </p> 046 * 047 * <ul> 048 * <li> 049 * If a user is a member of the organization he will automatically be a member 050 * of all its child organizations. 051 * </li> 052 * <li> 053 * Only the members of the parent organization can become a member of this 054 * organization. 055 * </li> 056 * <li> 057 * If a user doesn't have the custom attribute A, he cannot be assigned to 058 * organization B. 059 * </li> 060 * <li> 061 * If the user is added to organization A, he will automatically be added to 062 * organization B. 063 * </li> 064 * <li> 065 * The user must have the Administrator Role in order to be added to 066 * organization "Admin Organization". 067 * </li> 068 * <li> 069 * All users with the custom attribute A will automatically have the 070 * organization role B. 071 * </li> 072 * <li> 073 * All the users with organization role A cannot have organization role B 074 * (incompatible roles). 075 * </li> 076 * </ul> 077 * 078 * <p> 079 * Liferay's core services invoke {@link #checkMembership(long[], long[], 080 * long[])} to detect policy violations before adding the users to and removing 081 * the users from the organizations. On passing the check, the service proceeds 082 * with the changes and propagates appropriate related actions in the portal by 083 * invoking {@link #propagateMembership(long[], long[], long[])}. On failing the 084 * check, the service foregoes making the changes. For example, Liferay executes 085 * this logic when adding and updating organizations, adding and removing users 086 * with respect to organizations, and adding and removing organization roles 087 * with respect to users. 088 * </p> 089 * 090 * <p> 091 * Liferay's UI calls the "is*" methods, such as {@link 092 * #isMembershipAllowed(long, long)}, to determine appropriate options to 093 * display to the user. For example, the UI calls {@link 094 * #isMembershipAllowed(long, long)} to decide whether to enable the checkbox 095 * for adding the user to the organization. 096 * </p> 097 * 098 * <p> 099 * Liferay's core services call {@link #isMembershipProtected(PermissionChecker, 100 * long, long)} and {@link #isRoleProtected(PermissionChecker, long, long, 101 * long)} to protect user organization memberships and organization role 102 * assignments, appropriately. 103 * </p> 104 * 105 * @author Roberto D??az 106 * @author Sergio Gonz??lez 107 */ 108 public interface OrganizationMembershipPolicy { 109 110 /** 111 * Checks if the users can be added to and removed from the respective 112 * organizations. 113 * 114 * <p> 115 * Liferay's core services call this method before adding the users to and 116 * removing the users from the respective organizations. If this method 117 * throws an exception, the service foregoes making the changes. 118 * </p> 119 * 120 * @param userIds the primary keys of the users to be added and removed from 121 * the organizations 122 * @param addOrganizationIds the primary keys of the organizations to which 123 * the users are to be added (optionally <code>null</code>) 124 * @param removeOrganizationIds the primary keys of the organizations from 125 * which the users are to be removed (optionally <code>null</code>) 126 */ 127 public void checkMembership( 128 long[] userIds, long[] addOrganizationIds, 129 long[] removeOrganizationIds) 130 throws PortalException; 131 132 /** 133 * Checks if the organization roles can be added to or removed from their 134 * users. 135 * 136 * <p> 137 * Liferay's core services call this method before adding the users to and 138 * removing the users from the respective organization roles. If this method 139 * throws an exception, the service foregoes making the changes. 140 * </p> 141 * 142 * @param addUserGroupRoles the user group roles to be added 143 * @param removeUserGroupRoles the user group roles to be removed 144 */ 145 public void checkRoles( 146 List<UserGroupRole> addUserGroupRoles, 147 List<UserGroupRole> removeUserGroupRoles) 148 throws PortalException; 149 150 /** 151 * Returns <code>true</code> if the user can be added to the organization. 152 * Liferay's UI calls this method. 153 * 154 * @param userId the primary key of the user 155 * @param organizationId the primary key of the organization 156 * @return <code>true</code> if the user can be added to the organization; 157 * <code>false</code> otherwise 158 */ 159 public boolean isMembershipAllowed(long userId, long organizationId) 160 throws PortalException; 161 162 /** 163 * Returns <code>true</code> if the policy prevents the user from being 164 * removed from the organization by the user associated with the permission 165 * checker. 166 * 167 * @param permissionChecker the permission checker referencing a user 168 * @param userId the primary key of the user to check for protection 169 * @param organizationId the primary key of the organization 170 * @return <code>true</code> if the policy prevents the user from being 171 * removed from the organization by the user associated with the 172 * permission checker; <code>false</code> otherwise 173 */ 174 public boolean isMembershipProtected( 175 PermissionChecker permissionChecker, long userId, 176 long organizationId) 177 throws PortalException; 178 179 /** 180 * Returns <code>true</code> if organization membership for the user is 181 * mandatory. Liferay's UI, for example, calls this method in deciding 182 * whether to enable the checkbox for removing the user from the 183 * organization. 184 * 185 * @param userId the primary key of the user 186 * @param organizationId the primary key of the organization 187 * @return <code>true</code> if organization membership for the user is 188 * mandatory; <code>false</code> otherwise 189 */ 190 public boolean isMembershipRequired(long userId, long organizationId) 191 throws PortalException; 192 193 /** 194 * Returns <code>true</code> if the role can be added to the user on the 195 * organization. Liferay's UI calls this method. 196 * 197 * @param userId the primary key of the user 198 * @param organizationId the primary key of the organization 199 * @param roleId the primary key of the role 200 * @return <code>true</code> if the role can be added to the user on the 201 * organization; <code>false</code> otherwise 202 */ 203 public boolean isRoleAllowed(long userId, long organizationId, long roleId) 204 throws PortalException; 205 206 /** 207 * Returns <code>true</code> if the policy prevents the user from being 208 * removed from the role by the user associated with the permission checker. 209 * 210 * @param permissionChecker the permission checker referencing a user 211 * @param userId the primary key of the user to check for protection 212 * @param organizationId the primary key of the organization 213 * @param roleId the primary key of the role 214 * @return <code>true</code> if the policy prevents the user from being 215 * removed from the role by the user associated with the permission 216 * checker; <code>false</code> otherwise 217 */ 218 public boolean isRoleProtected( 219 PermissionChecker permissionChecker, long userId, 220 long organizationId, long roleId) 221 throws PortalException; 222 223 /** 224 * Returns <code>true</code> if the role is mandatory for the user on the 225 * organization. Liferay's UI calls this method. 226 * 227 * @param userId the primary key of the user 228 * @param organizationId the primary key of the organization 229 * @param roleId the primary key of the role 230 * @return <code>true</code> if the role is mandatory for the user on the 231 * organization; <code>false</code> otherwise 232 */ 233 public boolean isRoleRequired(long userId, long organizationId, long roleId) 234 throws PortalException; 235 236 /** 237 * Performs membership policy related actions after the users are added to 238 * and removed from the respective organizations. Liferay's core services 239 * call this method after adding and removing the users to and from the 240 * respective organizations. 241 * 242 * <p> 243 * The actions must ensure the integrity of each organization's membership 244 * policy. For example, some actions for implementations to consider 245 * performing are: 246 * </p> 247 * 248 * <ul> 249 * <li> 250 * Adding the users to the child organizations of each organization to which 251 * the users 252 * were added. 253 * </li> 254 * <li> 255 * Removing the users from the child organizations of each organization from 256 * which the users 257 * were removed. 258 * </li> 259 * </ul> 260 * 261 * @param userIds the primary key of the users to be added or removed 262 * @param addOrganizationIds the primary keys of the organizations to which 263 * the users were added (optionally <code>null</code>) 264 * @param removeOrganizationIds the primary keys of the organizations from 265 * which the users were removed (optionally <code>null</code>) 266 */ 267 public void propagateMembership( 268 long[] userIds, long[] addOrganizationIds, 269 long[] removeOrganizationIds) 270 throws PortalException; 271 272 /** 273 * Performs membership policy related actions after the respective 274 * organization roles are added to and removed from the affected users. 275 * Liferay's core services call this method after the roles are added to and 276 * removed from the users. 277 * 278 * <p> 279 * The actions must ensure the membership policy of each organization role. 280 * For example, some actions for implementations to consider performing are: 281 * </p> 282 * 283 * <ul> 284 * <li> 285 * If the role A is added to a user, role B should be added too. 286 * </li> 287 * <li> 288 * If the role A is removed from a user, role B should be removed too. 289 * </li> 290 * </ul> 291 * 292 * @param addUserGroupRoles the user group roles added 293 * @param removeUserGroupRoles the user group roles removed 294 */ 295 public void propagateRoles( 296 List<UserGroupRole> addUserGroupRoles, 297 List<UserGroupRole> removeUserGroupRoles) 298 throws PortalException; 299 300 /** 301 * Checks the integrity of the membership policy of each of the portal's 302 * organizations and performs operations necessary for the compliance of 303 * each organization and organization role. This method can be triggered 304 * manually from the Control Panel. If the 305 * <code>membership.policy.auto.verify</code> portal property is 306 * <code>true</code> this method is triggered when starting Liferay and 307 * every time a membership policy hook is deployed. 308 */ 309 public void verifyPolicy() throws PortalException; 310 311 /** 312 * Checks the integrity of the membership policy of the organization and 313 * performs operations necessary for the organization's compliance. 314 * 315 * @param organization the organization to verify 316 */ 317 public void verifyPolicy(Organization organization) throws PortalException; 318 319 /** 320 * Checks the integrity of the membership policy of the organization, with 321 * respect to the organization's new attribute values, categories, tags, and 322 * expando attributes, and performs operations necessary for the compliance 323 * of the organization and its organization roles. Liferay calls this method 324 * when adding and updating organizations. 325 * 326 * <p> 327 * The actions must ensure the integrity of the organization's membership 328 * policy based on what has changed in the organization's attribute values, 329 * categories, tags, and expando attributes. 330 * </p> 331 * 332 * <p> 333 * For example, if the membership policy is that organizations with the 334 * "admnistrator" tag should only allow administrators as users, then this 335 * method could enforce that policy using the following logic: 336 * </p> 337 * 338 * <ul> 339 * <li> 340 * If the old tags include the "administrator" tag and the new tags include 341 * it too, then no action needs to be performed regarding the 342 * policy. Note, the new tags can be obtained by calling 343 * <code>assetTagLocalService.getTags(Group.class.getName(), 344 * group.getGroupId());</code>. 345 * </li> 346 * <li> 347 * If the old tags include the "administrator" tag and the new tags don't 348 * include it, 349 * then no action needs to be performed regarding the 350 * policy, as non-administrator users need not be removed. 351 * </li> 352 * <li> 353 * However, if the old tags don't include the "administrator" tag, but the 354 * new tags include it, any organization user that does not have the 355 * Administrator role must be removed from the organization. 356 * </li> 357 * 358 * @param organization the added or updated organization to verify 359 * @param oldOrganization the old organization 360 * @param oldAssetCategories the old categories 361 * @param oldAssetTags the old tags 362 * @param oldExpandoAttributes the old expando attributes 363 */ 364 public void verifyPolicy( 365 Organization organization, Organization oldOrganization, 366 List<AssetCategory> oldAssetCategories, List<AssetTag> oldAssetTags, 367 Map<String, Serializable> oldExpandoAttributes) 368 throws PortalException; 369 370 /** 371 * Checks the integrity of the membership policy of the organization role 372 * and performs operations necessary for the role's compliance. 373 * 374 * @param role the role to verify 375 */ 376 public void verifyPolicy(Role role) throws PortalException; 377 378 /** 379 * Checks the integrity of the membership policy of the organization role, 380 * with respect to its expando attributes, and performs operations necessary 381 * for the role's compliance. Liferay calls this method when adding and 382 * updating organization roles. 383 * 384 * @param role the added or updated role to verify 385 * @param oldRole the old role 386 * @param oldExpandoAttributes the old expando attributes 387 */ 388 public void verifyPolicy( 389 Role role, Role oldRole, 390 Map<String, Serializable> oldExpandoAttributes) 391 throws PortalException; 392 393 }