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    }