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