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.UserGroup; 019 020 import java.io.Serializable; 021 022 import java.util.Map; 023 024 /** 025 * Provides the User Group Membership Policy interface, allowing customization 026 * of user membership regarding user groups. 027 * 028 * <p> 029 * User Group Membership Policies define the user groups a user is allowed to be 030 * a member of and the user groups the user must be a member of. 031 * </p> 032 * 033 * <p> 034 * An implementation may include any number of rules and actions to enforce 035 * those rules. The implementation may include rules and actions like the 036 * following: 037 * </p> 038 * 039 * <ul> 040 * <li> 041 * If a user doesn't have the custom attribute A, he cannot be assigned to user 042 * group B. 043 * </li> 044 * <li> 045 * If the user is added to user group A, he will automatically be added to user 046 * group B. 047 * </li> 048 * <li> 049 * The user must have the Administrator Role in order to be added to user group 050 * "Admin User Group". 051 * </li> 052 * </ul> 053 * 054 * <p> 055 * Liferay's core services invoke {@link #checkMembership(long[], long[], 056 * long[])} to detect policy violations before adding the users to and removing 057 * the users from the user groups. On passing the check, the service proceeds 058 * with the changes and propagates appropriate related actions in the portal by 059 * invoking {@link #propagateMembership(long[], long[], long[])}. On failing the 060 * check, the service foregoes making the changes. For example, Liferay executes 061 * this logic when adding and updating user groups, adding and removing users 062 * with respect to user groups. 063 * </p> 064 * 065 * <p> 066 * Liferay's UI calls the "is*" methods, such as {@link 067 * #isMembershipAllowed(long, long)}, to determine appropriate options to 068 * display to the user. For example, the UI calls {@link 069 * #isMembershipAllowed(long, long)} to decide whether to enable the checkbox 070 * for adding the user to the user group. 071 * </p> 072 * 073 * @author Roberto D??az 074 * @author Sergio Gonz??lez 075 */ 076 public interface UserGroupMembershipPolicy { 077 078 /** 079 * Checks if the users can be added to and removed from the respective user 080 * groups. 081 * 082 * <p> 083 * Liferay's core services call this method before adding the users to and 084 * removing the users from the respective user groups. If this method throws 085 * an exception, the service foregoes making the changes. 086 * </p> 087 * 088 * @param userIds the primary keys of the users to be added and removed from 089 * the user groups 090 * @param addUserGroupIds the primary keys of the user groups to which the 091 * users are to be added (optionally <code>null</code>) 092 * @param removeUserGroupIds the primary keys of the user groups from which 093 * the users are to be removed (optionally <code>null</code>) 094 */ 095 public void checkMembership( 096 long[] userIds, long[] addUserGroupIds, long[] removeUserGroupIds) 097 throws PortalException; 098 099 /** 100 * Returns <code>true</code> if the user can be added to the user group. 101 * Liferay's UI calls this method. 102 * 103 * @param userId the primary key of the user 104 * @param userGroupId the primary key of the user group 105 * @return <code>true</code> if the user can be added to the user group; 106 * <code>false</code> otherwise 107 */ 108 public boolean isMembershipAllowed(long userId, long userGroupId) 109 throws PortalException; 110 111 /** 112 * Returns <code>true</code> if user group membership for the user is 113 * mandatory. Liferay's UI, for example, calls this method in deciding 114 * whether the checkbox to select the user group will be enable. 115 * 116 * @param userId the primary key of the user 117 * @param userGroupId the primary key of the user group 118 * @return <code>true</code> if user group membership for the user is 119 * mandatory; <code>false</code> otherwise 120 */ 121 public boolean isMembershipRequired(long userId, long userGroupId) 122 throws PortalException; 123 124 /** 125 * Performs membership policy related actions after the users are added to 126 * and removed from the respective user groups. Liferay's core services call 127 * this method after adding and removing the users to and from the 128 * respective user groups. 129 * 130 * <p> 131 * The actions must ensure the integrity of each user group's membership 132 * policy. For example, some actions for implementations to consider 133 * performing are: 134 * </p> 135 * 136 * <ul> 137 * <li> 138 * If a user is added to user group A, he should be added to user group B 139 * too. 140 * </li> 141 * <li> 142 * If a user is removed from user group A, he should be removed from user 143 * group B too. 144 * </li> 145 * </ul> 146 * 147 * @param userIds the primary key of the users to be added or removed 148 * @param addUserGroupIds the primary keys of the user groups to which the 149 * users were added (optionally <code>null</code>) 150 * @param removeUserGroupIds the primary keys of the user groups from which 151 * the users were removed (optionally <code>null</code>) 152 */ 153 public void propagateMembership( 154 long[] userIds, long[] addUserGroupIds, long[] removeUserGroupIds) 155 throws PortalException; 156 157 /** 158 * Checks the integrity of the membership policy of each of the portal's 159 * user groups and performs operations necessary for the compliance of each 160 * user group. This method can be triggered manually from the Control Panel. 161 * If the <code>membership.policy.auto.verify</code> portal property is 162 * <code>true</code> this method is triggered when starting Liferay and 163 * every time a membership policy hook is deployed. 164 */ 165 public void verifyPolicy() throws PortalException; 166 167 /** 168 * Checks the integrity of the membership policy of the user group and 169 * performs operations necessary for the user group's compliance. 170 * 171 * @param userGroup the user group to verify 172 */ 173 public void verifyPolicy(UserGroup userGroup) throws PortalException; 174 175 /** 176 * Checks the integrity of the membership policy of the user group, with 177 * respect to the user group's new attribute values and expando attributes, 178 * and performs operations necessary for the compliance of the user group. 179 * Liferay calls this method when adding and updating user groups. 180 * 181 * <p> 182 * The actions must ensure the integrity of the user group's membership 183 * policy based on what has changed in the user group's attribute values and 184 * expando attributes. 185 * </p> 186 * 187 * <p> 188 * For example, if the membership policy is that user groups with the 189 * expando attribute A should only allow administrators, then this method 190 * could enforce that policy using the following logic: 191 * </p> 192 * 193 * <ul> 194 * <li> 195 * If the oldExpandoAttributes include the expando attribute A and the new 196 * expando attributes include it too, then no action needs to be performed 197 * regarding the policy. Note, the new expando attributes can be obtained 198 * by calling <code>assetTagLocalService.getTags(Group.class.getName(), 199 * group.getGroupId());</code>. 200 * </li> 201 * <li> 202 * If the oldExpandoAttributes include the expando attribute A and the new 203 * expando attributes don't include it, then no action needs to be performed 204 * regarding the policy, as non-administrator users need not be removed. 205 * </li> 206 * <li> 207 * However, if the oldExpandoAttributes don't include the expando attribute 208 * A and the new expando attributes include it, any user group user that 209 * does not have the Administrator role must be removed from the user group. 210 * </li> 211 * 212 * @param userGroup the added or updated user group to verify 213 * @param oldUserGroup the old user group 214 * @param oldExpandoAttributes the old expando attributes 215 */ 216 public void verifyPolicy( 217 UserGroup userGroup, UserGroup oldUserGroup, 218 Map<String, Serializable> oldExpandoAttributes) 219 throws PortalException; 220 221 }