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