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