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 121 * from 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 * @throws PortalException if any one user could not be added to a 127 * organization, if any one user could not be removed from a 128 * organization, or if a portal exception occurred 129 */ 130 public void checkMembership( 131 long[] userIds, long[] addOrganizationIds, 132 long[] removeOrganizationIds) 133 throws PortalException; 134 135 /** 136 * Checks if the organization roles can be added to or removed from their 137 * users. 138 * 139 * <p> 140 * Liferay's core services call this method before adding the users to and 141 * removing the users from the respective organization roles. If this method 142 * throws an exception, the service foregoes making the changes. 143 * </p> 144 * 145 * @param addUserGroupRoles the user group roles to be added 146 * @param removeUserGroupRoles the user group roles to be removed 147 * @throws PortalException if any one user group role violated the policy or 148 * if a portal exception occurred 149 */ 150 public void checkRoles( 151 List<UserGroupRole> addUserGroupRoles, 152 List<UserGroupRole> removeUserGroupRoles) 153 throws PortalException; 154 155 /** 156 * Returns <code>true</code> if the user can be added to the organization. 157 * Liferay's UI calls this method. 158 * 159 * @param userId the primary key of the user 160 * @param organizationId the primary key of the organization 161 * @return <code>true</code> if the user can be added to the organization; 162 * <code>false</code> otherwise 163 * @throws PortalException if a portal exception occurred 164 */ 165 public boolean isMembershipAllowed(long userId, long organizationId) 166 throws PortalException; 167 168 /** 169 * Returns <code>true</code> if the policy prevents the user from being 170 * removed from the organization by the user associated with the permission 171 * checker. 172 * 173 * @param permissionChecker the permission checker referencing a user 174 * @param userId the primary key of the user to check for protection 175 * @param organizationId the primary key of the organization 176 * @return <code>true</code> if the policy prevents the user from being 177 * removed from the organization by the user associated with the 178 * permission checker; <code>false</code> otherwise 179 * @throws PortalException if a portal exception occurred 180 */ 181 public boolean isMembershipProtected( 182 PermissionChecker permissionChecker, long userId, 183 long organizationId) 184 throws PortalException; 185 186 /** 187 * Returns <code>true</code> if organization membership for the user is 188 * mandatory. Liferay's UI, for example, calls this method in deciding 189 * whether to enable the checkbox for removing the user from the 190 * organization. 191 * 192 * @param userId the primary key of the user 193 * @param organizationId the primary key of the organization 194 * @return <code>true</code> if organization membership for the user is 195 * mandatory; <code>false</code> otherwise 196 * @throws PortalException if a portal exception occurred 197 */ 198 public boolean isMembershipRequired(long userId, long organizationId) 199 throws PortalException; 200 201 /** 202 * Returns <code>true</code> if the role can be added to the user on the 203 * organization. Liferay's UI calls this method. 204 * 205 * @param userId the primary key of the user 206 * @param organizationId the primary key of the organization 207 * @param roleId the primary key of the role 208 * @return <code>true</code> if the role can be added to the user on the 209 * organization; <code>false</code> otherwise 210 * @throws PortalException if a portal exception occurred 211 */ 212 public boolean isRoleAllowed(long userId, long organizationId, long roleId) 213 throws PortalException; 214 215 /** 216 * Returns <code>true</code> if the policy prevents the user from being 217 * removed from the role by the user associated with the permission checker. 218 * 219 * @param permissionChecker the permission checker referencing a user 220 * @param userId the primary key of the user to check for protection 221 * @param organizationId the primary key of the organization 222 * @param roleId the primary key of the role 223 * @return <code>true</code> if the policy prevents the user from being 224 * removed from the role by the user associated with the permission 225 * checker; <code>false</code> otherwise 226 * @throws PortalException if a portal exception occurred 227 */ 228 public boolean isRoleProtected( 229 PermissionChecker permissionChecker, long userId, 230 long organizationId, long roleId) 231 throws PortalException; 232 233 /** 234 * Returns <code>true</code> if the role is mandatory for the user on the 235 * organization. Liferay's UI calls this method. 236 * 237 * @param userId the primary key of the user 238 * @param organizationId the primary key of the organization 239 * @param roleId the primary key of the role 240 * @return <code>true</code> if the role is mandatory for the user on the 241 * organization; <code>false</code> otherwise 242 * @throws PortalException if a portal exception occurred 243 */ 244 public boolean isRoleRequired(long userId, long organizationId, long roleId) 245 throws PortalException; 246 247 /** 248 * Performs membership policy related actions after the users are added to 249 * and removed from the respective organizations. Liferay's core services 250 * call this method after adding and removing the users to and from the 251 * respective organizations. 252 * 253 * <p> 254 * The actions must ensure the integrity of each organization's membership 255 * policy. For example, some actions for implementations to consider 256 * performing are: 257 * </p> 258 * 259 * <ul> 260 * <li> 261 * Adding the users to the child organizations of each organization to which 262 * the users 263 * were added. 264 * </li> 265 * <li> 266 * Removing the users from the child organizations of each organization from 267 * which the users 268 * were removed. 269 * </li> 270 * </ul> 271 * 272 * @param userIds the primary key of the users to be added or removed 273 * @param addOrganizationIds the primary keys of the organizations to which 274 * the users were added (optionally <code>null</code>) 275 * @param removeOrganizationIds the primary keys of the organizations from 276 * which the users were removed (optionally <code>null</code>) 277 * @throws PortalException if a portal exception occurred 278 */ 279 public void propagateMembership( 280 long[] userIds, long[] addOrganizationIds, 281 long[] removeOrganizationIds) 282 throws PortalException; 283 284 /** 285 * Performs membership policy related actions after the respective 286 * organization roles are added to and removed from the affected users. 287 * Liferay's core services call this method after the roles are added to and 288 * removed from the users. 289 * 290 * <p> 291 * The actions must ensure the membership policy of each organization role. 292 * For example, some actions for implementations to consider performing are: 293 * </p> 294 * 295 * <ul> 296 * <li> 297 * If the role A is added to a user, role B should be added too. 298 * </li> 299 * <li> 300 * If the role A is removed from a user, role B should be removed too. 301 * </li> 302 * </ul> 303 * 304 * @param addUserGroupRoles the user group roles added 305 * @param removeUserGroupRoles the user group roles removed 306 * @throws PortalException if a portal exception occurred 307 */ 308 public void propagateRoles( 309 List<UserGroupRole> addUserGroupRoles, 310 List<UserGroupRole> removeUserGroupRoles) 311 throws PortalException; 312 313 /** 314 * Checks the integrity of the membership policy of each of the portal's 315 * organizations and performs operations necessary for the compliance of 316 * each organization and organization role. This method can be triggered 317 * manually from the Control Panel. If the 318 * <code>membership.policy.auto.verify</code> portal property is 319 * <code>true</code> this method is triggered when starting Liferay and 320 * every time a membership policy hook is deployed. 321 * 322 * @throws PortalException if a portal exception occurred 323 */ 324 public void verifyPolicy() throws PortalException; 325 326 /** 327 * Checks the integrity of the membership policy of the organization and 328 * performs operations necessary for the organization's compliance. 329 * 330 * @param organization the organization to verify 331 * @throws PortalException if a portal exception occurred 332 */ 333 public void verifyPolicy(Organization organization) throws PortalException; 334 335 /** 336 * Checks the integrity of the membership policy of the organization, with 337 * respect to the organization's new attribute values, categories, tags, and 338 * expando attributes, and performs operations necessary for the compliance 339 * of the organization and its organization roles. Liferay calls this method 340 * when adding and updating organizations. 341 * 342 * <p> 343 * The actions must ensure the integrity of the organization's membership 344 * policy based on what has changed in the organization's attribute values, 345 * categories, tags, and expando attributes. 346 * </p> 347 * 348 * <p> 349 * For example, if the membership policy is that organizations with the 350 * "admnistrator" tag should only allow administrators as users, then this 351 * method could enforce that policy using the following logic: 352 * </p> 353 * 354 * <ul> 355 * <li> 356 * If the old tags include the "administrator" tag and the new tags include 357 * it too, then no action needs to be performed regarding the 358 * policy. Note, the new tags can be obtained by calling 359 * <code>assetTagLocalService.getTags(Group.class.getName(), 360 * group.getGroupId());</code>. 361 * </li> 362 * <li> 363 * If the old tags include the "administrator" tag and the new tags don't 364 * include it, 365 * then no action needs to be performed regarding the 366 * policy, as non-administrator users need not be removed. 367 * </li> 368 * <li> 369 * However, if the old tags don't include the "administrator" tag, but the 370 * new tags include it, any organization user that does not have the 371 * Administrator role must be removed from the organization. 372 * </li> 373 * 374 * @param organization the added or updated organization to verify 375 * @param oldOrganization the old organization 376 * @param oldAssetCategories the old categories 377 * @param oldAssetTags the old tags 378 * @param oldExpandoAttributes the old expando attributes 379 * @throws PortalException if a portal exception occurred 380 */ 381 public void verifyPolicy( 382 Organization organization, Organization oldOrganization, 383 List<AssetCategory> oldAssetCategories, List<AssetTag> oldAssetTags, 384 Map<String, Serializable> oldExpandoAttributes) 385 throws PortalException; 386 387 /** 388 * Checks the integrity of the membership policy of the organization role 389 * and performs operations necessary for the role's compliance. 390 * 391 * @param role the role to verify 392 * @throws PortalException if a portal exception occurred 393 */ 394 public void verifyPolicy(Role role) throws PortalException; 395 396 /** 397 * Checks the integrity of the membership policy of the organization role, 398 * with respect to its expando attributes, and performs operations necessary 399 * for the role's compliance. Liferay calls this method when adding and 400 * updating organization roles. 401 * 402 * @param role the added or updated role to verify 403 * @param oldRole the old role 404 * @param oldExpandoAttributes the old expando attributes 405 * @throws PortalException if a portal exception occurred 406 */ 407 public void verifyPolicy( 408 Role role, Role oldRole, 409 Map<String, Serializable> oldExpandoAttributes) 410 throws PortalException; 411 412 }