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    }