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