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    }