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