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 089 * from 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 * @throws PortalException if any one user could not be added to a user 095 * group, if any one user could not be removed from a user group, or 096 * if a portal exception occurred 097 */ 098 public void checkMembership( 099 long[] userIds, long[] addUserGroupIds, long[] removeUserGroupIds) 100 throws PortalException; 101 102 /** 103 * Returns <code>true</code> if the user can be added to the user group. 104 * Liferay's UI calls this method. 105 * 106 * @param userId the primary key of the user 107 * @param userGroupId the primary key of the user group 108 * @return <code>true</code> if the user can be added to the user group; 109 * <code>false</code> otherwise 110 * @throws PortalException if a portal exception occurred 111 */ 112 public boolean isMembershipAllowed(long userId, long userGroupId) 113 throws PortalException; 114 115 /** 116 * Returns <code>true</code> if user group membership for the user is 117 * mandatory. Liferay's UI, for example, calls this method in deciding 118 * whether the checkbox to select the user group will be enable. 119 * 120 * @param userId the primary key of the user 121 * @param userGroupId the primary key of the user group 122 * @return <code>true</code> if user group membership for the user is 123 * mandatory; <code>false</code> otherwise 124 * @throws PortalException if a portal exception occurred 125 */ 126 public boolean isMembershipRequired(long userId, long userGroupId) 127 throws PortalException; 128 129 /** 130 * Performs membership policy related actions after the users are added to 131 * and removed from the respective user groups. Liferay's core services call 132 * this method after adding and removing the users to and from the 133 * respective user groups. 134 * 135 * <p> 136 * The actions must ensure the integrity of each user group's membership 137 * policy. For example, some actions for implementations to consider 138 * performing are: 139 * </p> 140 * 141 * <ul> 142 * <li> 143 * If a user is added to user group A, he should be added to user group B 144 * too. 145 * </li> 146 * <li> 147 * If a user is removed from user group A, he should be removed from user 148 * group B too. 149 * </li> 150 * </ul> 151 * 152 * @param userIds the primary key of the users to be added or removed 153 * @param addUserGroupIds the primary keys of the user groups to which the 154 * users were added (optionally <code>null</code>) 155 * @param removeUserGroupIds the primary keys of the user groups from which 156 * the users were removed (optionally <code>null</code>) 157 * @throws PortalException if a portal exception occurred 158 */ 159 public void propagateMembership( 160 long[] userIds, long[] addUserGroupIds, long[] removeUserGroupIds) 161 throws PortalException; 162 163 /** 164 * Checks the integrity of the membership policy of each of the portal's 165 * user groups and performs operations necessary for the compliance of each 166 * user group. This method can be triggered manually from the Control Panel. 167 * If the <code>membership.policy.auto.verify</code> portal property is 168 * <code>true</code> this method is triggered when starting Liferay and 169 * every time a membership policy hook is deployed. 170 * 171 * @throws PortalException if a portal exception occurred 172 */ 173 public void verifyPolicy() throws PortalException; 174 175 /** 176 * Checks the integrity of the membership policy of the user group and 177 * performs operations necessary for the user group's compliance. 178 * 179 * @param userGroup the user group to verify 180 * @throws PortalException if a portal exception occurred 181 */ 182 public void verifyPolicy(UserGroup userGroup) throws PortalException; 183 184 /** 185 * Checks the integrity of the membership policy of the user group, with 186 * respect to the user group's new attribute values and expando attributes, 187 * and performs operations necessary for the compliance of the user group. 188 * Liferay calls this method when adding and updating user groups. 189 * 190 * <p> 191 * The actions must ensure the integrity of the user group's membership 192 * policy based on what has changed in the user group's attribute values and 193 * expando attributes. 194 * </p> 195 * 196 * <p> 197 * For example, if the membership policy is that user groups with the 198 * expando attribute A should only allow administrators, then this method 199 * could enforce that policy using the following logic: 200 * </p> 201 * 202 * <ul> 203 * <li> 204 * If the oldExpandoAttributes include the expando attribute A and the new 205 * expando attributes include it too, then no action needs to be performed 206 * regarding the policy. Note, the new expando attributes can be obtained 207 * by calling <code>assetTagLocalService.getTags(Group.class.getName(), 208 * group.getGroupId());</code>. 209 * </li> 210 * <li> 211 * If the oldExpandoAttributes include the expando attribute A and the new 212 * expando attributes don't include it, then no action needs to be performed 213 * regarding the policy, as non-administrator users need not be removed. 214 * </li> 215 * <li> 216 * However, if the oldExpandoAttributes don't include the expando attribute 217 * A and the new expando attributes include it, any user group user that 218 * does not have the Administrator role must be removed from the user group. 219 * </li> 220 * 221 * @param userGroup the added or updated user group to verify 222 * @param oldUserGroup the old user group 223 * @param oldExpandoAttributes the old expando attributes 224 * @throws PortalException if a portal exception occurred 225 */ 226 public void verifyPolicy( 227 UserGroup userGroup, UserGroup oldUserGroup, 228 Map<String, Serializable> oldExpandoAttributes) 229 throws PortalException; 230 231 }