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.kernel.util.UnicodeProperties;
020    import com.liferay.portal.model.Group;
021    import com.liferay.portal.model.Role;
022    import com.liferay.portal.model.UserGroupRole;
023    import com.liferay.portal.security.permission.PermissionChecker;
024    import com.liferay.portlet.asset.model.AssetCategory;
025    import com.liferay.portlet.asset.model.AssetTag;
026    
027    import java.io.Serializable;
028    
029    import java.util.List;
030    import java.util.Map;
031    
032    /**
033     * Provides the Site Membership Policy interface, allowing customization of user
034     * membership regarding sites and site roles.
035     *
036     * <p>
037     * Site Membership Policies define the sites a user is allowed to be a member
038     * of, the sites the user must be a member of, the site roles the user is
039     * allowed to be assigned, and the site roles the user must be assigned.
040     * </p>
041     *
042     * <p>
043     * An implementation may include any number of rules and actions to enforce
044     * those rules. The implementation may include rules and actions like the
045     * following:
046     * </p>
047     *
048     * <ul>
049     * <li>
050     * If a user is a member of the site he will automatically be a member of all
051     * its child sites.
052     * </li>
053     * <li>
054     * Only the members of the parent site can become a member of this site.
055     * </li>
056     * <li>
057     * If a user doesn't have the custom attribute A, he cannot be assigned to site
058     * B.
059     * </li>
060     * <li>
061     * If the user is added to site A, he will automatically be added to site B.
062     * </li>
063     * <li>
064     * The user must have the Administrator Role in order to be added to site "Admin
065     * Site".
066     * </li>
067     * <li>
068     * All users with the custom attribute A will automatically have the site
069     * role B.
070     * </li>
071     * <li>
072     * All the users with site role A cannot have site role B (incompatible
073     * roles).
074     * </li>
075     * </ul>
076     *
077     * <p>
078     * Liferay's core services invoke {@link #checkMembership(long[], long[],
079     * long[])} to detect policy violations before adding the users to and removing
080     * the users from the sites. On passing the check, the service proceeds with the
081     * changes and propagates appropriate related actions in the portal by invoking
082     * {@link #propagateMembership(long[], long[], long[])}. On failing the check,
083     * the service foregoes making the changes. For example, Liferay executes this
084     * logic when adding and updating sites, adding and removing users with respect
085     * to sites, and adding and removing site roles with respect to users.
086     * </p>
087     *
088     * <p>
089     * Liferay's UI calls the "is*" methods, such as {@link
090     * #isMembershipAllowed(long, long)}, to determine appropriate options to
091     * display to the user. For example, the UI calls {@link
092     * #isMembershipAllowed(long, long)} to decide whether to display the "Join"
093     * link to the user.
094     * </p>
095     *
096     * <p>
097     * Liferay's core services call {@link #isMembershipProtected(PermissionChecker,
098     * long, long)} and {@link #isRoleProtected(PermissionChecker, long, long,
099     * long)} to protect user site memberships and site role assignments,
100     * appropriately.
101     * </p>
102     *
103     * @author Sergio Gonz??lez
104     * @author Roberto D??az
105     */
106    public interface SiteMembershipPolicy {
107    
108            /**
109             * Checks if the users can be added to and removed from the respective
110             * sites.
111             *
112             * <p>
113             * Liferay's core services call this method before adding the users to and
114             * removing the users from the respective sites. If this method throws an
115             * exception, the service foregoes making the changes.
116             * </p>
117             *
118             * @param  userIds the primary keys of the users to be added and removed
119             *         from the sites
120             * @param  addGroupIds the primary keys of the sites to which the users are
121             *         to be added (optionally <code>null</code>)
122             * @param  removeGroupIds the primary keys of the sites from which the users
123             *         are to be removed (optionally <code>null</code>)
124             * @throws PortalException if any one user could not be added to a site, if
125             *         any one user could not be removed from a site, or if a portal
126             *         exception occurred
127             * @throws SystemException if a system exception occurred
128             */
129            public void checkMembership(
130                            long[] userIds, long[] addGroupIds, long[] removeGroupIds)
131                    throws PortalException, SystemException;
132    
133            /**
134             * Checks if the site roles can be added to or removed from their users.
135             *
136             * <p>
137             * Liferay's core services call this method before adding the users to and
138             * removing the users from the respective site roles. If this method throws
139             * an exception, the service foregoes making the changes.
140             * </p>
141             *
142             * @param  addUserGroupRoles the user group roles to be added
143             * @param  removeUserGroupRoles the user group roles to be removed
144             * @throws PortalException if any one user group role violated the policy or
145             *         if a portal exception occurred
146             * @throws SystemException if a system exception occurred
147             */
148            public void checkRoles(
149                            List<UserGroupRole> addUserGroupRoles,
150                            List<UserGroupRole> removeUserGroupRoles)
151                    throws PortalException, SystemException;
152    
153            /**
154             * Returns <code>true</code> if the user can be added to the site. Liferay's
155             * UI calls this method.
156             *
157             * @param  userId the primary key of the user
158             * @param  groupId the primary key of the site
159             * @return <code>true</code> if the user can be added to the site;
160             *         <code>false</code> otherwise
161             * @throws PortalException if a portal exception occurred
162             * @throws SystemException if a system exception occurred
163             */
164            public boolean isMembershipAllowed(long userId, long groupId)
165                    throws PortalException, SystemException;
166    
167            /**
168             * Returns <code>true</code> if the policy prevents the user from being
169             * removed from the site by the user associated with the permission checker.
170             *
171             * @param  permissionChecker the permission checker referencing a user
172             * @param  userId the primary key of the user to check for protection
173             * @param  groupId the primary key of the site
174             * @return <code>true</code> if the policy prevents the user from being
175             *         removed from the site by the user associated with the permission
176             *         checker; <code>false</code> otherwise
177             * @throws PortalException if a portal exception occurred
178             * @throws SystemException if a system exception occurred
179             */
180            public boolean isMembershipProtected(
181                            PermissionChecker permissionChecker, long userId, long groupId)
182                    throws PortalException, SystemException;
183    
184            /**
185             * Returns <code>true</code> if site membership for the user is mandatory.
186             * Liferay's UI, for example, calls this method in deciding whether to
187             * display the option to leave the site.
188             *
189             * @param  userId the primary key of the user
190             * @param  groupId the primary key of the site
191             * @return <code>true</code> if site membership for the user is mandatory;
192             *         <code>false</code> otherwise
193             * @throws PortalException if a portal exception occurred
194             * @throws SystemException if a system exception occurred
195             */
196            public boolean isMembershipRequired(long userId, long groupId)
197                    throws PortalException, SystemException;
198    
199            /**
200             * Returns <code>true</code> if the role can be added to the user on the
201             * site. Liferay's UI calls this method.
202             *
203             * @param  userId the primary key of the user
204             * @param  groupId the primary key of the site
205             * @param  roleId the primary key of the role
206             * @return <code>true</code> if the role can be added to the user on the
207             *         site; <code>false</code> otherwise
208             * @throws PortalException if a portal exception occurred
209             * @throws SystemException if a system exception occurred
210             */
211            public boolean isRoleAllowed(long userId, long groupId, long roleId)
212                    throws PortalException, SystemException;
213    
214            /**
215             * Returns <code>true</code> if the policy prevents the user from being
216             * removed from the role by the user associated with the permission checker.
217             *
218             * @param  permissionChecker the permission checker referencing a user
219             * @param  userId the primary key of the user to check for protection
220             * @param  groupId the primary key of the site
221             * @param  roleId the primary key of the role
222             * @return <code>true</code> if the policy prevents the user from being
223             *         removed from the role by the user associated with the permission
224             *         checker; <code>false</code> otherwise
225             * @throws PortalException if a portal exception occurred
226             * @throws SystemException if a system exception occurred
227             */
228            public boolean isRoleProtected(
229                            PermissionChecker permissionChecker, long userId, long groupId,
230                            long roleId)
231                    throws PortalException, SystemException;
232    
233            /**
234             * Returns <code>true</code> if the role is mandatory for the user on the
235             * site. Liferay's UI calls this method.
236             *
237             * @param  userId the primary key of the user
238             * @param  groupId the primary key of the site
239             * @param  roleId the primary key of the role
240             * @return <code>true</code> if the role is mandatory for the user on the
241             *         site; <code>false</code> otherwise
242             * @throws PortalException if a portal exception occurred
243             * @throws SystemException if a system exception occurred
244             */
245            public boolean isRoleRequired(long userId, long groupId, long roleId)
246                    throws PortalException, SystemException;
247    
248            /**
249             * Performs membership policy related actions after the users are added to
250             * and removed from the respective sites. Liferay's core services call this
251             * method after adding and removing the users to and from the respective
252             * sites.
253             *
254             * <p>
255             * The actions must ensure the integrity of each site's membership policy.
256             * For example, some actions for implementations to consider performing are:
257             * </p>
258             *
259             * <ul>
260             * <li>
261             * Adding the users to the child sites of each site to which the users
262             * were added.
263             * </li>
264             * <li>
265             * Removing the users from the child sites of each site from which the users
266             * were removed.
267             * </li>
268             * </ul>
269             *
270             * @param  userIds the primary key of the users that have been added or
271             *         removed
272             * @param  addGroupIds the primary keys of the sites to which the users were
273             *         added (optionally <code>null</code>)
274             * @param  removeGroupIds the primary keys of the sites from which the users
275             *         were removed (optionally <code>null</code>)
276             * @throws PortalException if a portal exception occurred
277             * @throws SystemException if a system exception occurred
278             */
279            public void propagateMembership(
280                            long[] userIds, long[] addGroupIds, long[] removeGroupIds)
281                    throws PortalException, SystemException;
282    
283            /**
284             * Performs membership policy related actions after the respective site
285             * roles are added to and removed from the affected users. Liferay's core
286             * services call this method after the roles are added to and removed from
287             * the users.
288             *
289             * <p>
290             * The actions must ensure the membership policy of each site role. For
291             * example, some actions for implementations to consider performing are:
292             * </p>
293             *
294             * <ul>
295             * <li>
296             * If the role A is added to a user, role B should be added too.
297             * </li>
298             * <li>
299             * If the role A is removed from a user, role B should be removed too.
300             * </li>
301             * </ul>
302             *
303             * @param  addUserGroupRoles the user group roles added
304             * @param  removeUserGroupRoles the user group roles removed
305             * @throws PortalException if a portal exception occurred
306             * @throws SystemException if a system exception occurred
307             */
308            public void propagateRoles(
309                            List<UserGroupRole> addUserGroupRoles,
310                            List<UserGroupRole> removeUserGroupRoles)
311                    throws PortalException, SystemException;
312    
313            /**
314             * Checks the integrity of the membership policy of each of the portal's
315             * sites and performs operations necessary for the compliance of each site
316             * and site role. This method can be triggered manually from the Control
317             * Panel. If the <code>membership.policy.auto.verify</code> portal property
318             * is <code>true</code> this method is triggered when starting Liferay and
319             * every time a membership policy hook is deployed.
320             *
321             * @throws PortalException if a portal exception occurred
322             * @throws SystemException if a system exception occurred
323             */
324            public void verifyPolicy() throws PortalException, SystemException;
325    
326            /**
327             * Checks the integrity of the membership policy of the site and performs
328             * operations necessary for the site's compliance.
329             *
330             * @param  group the site to verify
331             * @throws PortalException if a portal exception occurred
332             * @throws SystemException if a system exception occurred
333             */
334            public void verifyPolicy(Group group)
335                    throws PortalException, SystemException;
336    
337            /**
338             * Checks the integrity of the membership policy of the site, with respect
339             * to the site's new attribute values, categories, tags, expando attributes,
340             * and type settings properties, and performs operations necessary for the
341             * compliance of the site and its site roles. Liferay calls this method when
342             * adding and updating sites.
343             *
344             * <p>
345             * The actions must ensure the integrity of the site's membership policy
346             * based on what has changed in the site's attribute values, categories,
347             * tags, expando attributes, and type settings properties.
348             * </p>
349             *
350             * <p>
351             * For example, if the membership policy is that sites with the
352             * "admnistrator" tag should only allow administrators as users, then this
353             * method could enforce that policy using the following logic:
354             * </p>
355             *
356             * <ul>
357             * <li>
358             * If the old tags include the "administrator" tag and the new tags include
359             * it too, then no action needs to be performed regarding the
360             * policy. Note, the new tags can be obtained by calling
361             * <code>assetTagLocalService.getTags(Group.class.getName(),
362             * group.getGroupId());</code>.
363             * </li>
364             * <li>
365             * If the old tags include the "administrator" tag and the new tags don't
366             * include it,
367             * then no action needs to be performed regarding the
368             * policy, as non-administrator users need not be removed.
369             * </li>
370             * <li>
371             * However, if the old tags don't include the "administrator" tag, but the
372             * new tags include it, any site user that does not have the Administrator
373             * role
374             * must be removed from the site.
375             * </li>
376             *
377             * @param  group the added or updated site to verify
378             * @param  oldGroup the old site
379             * @param  oldAssetCategories the old categories
380             * @param  oldAssetTags the old tags
381             * @param  oldExpandoAttributes the old expando attributes
382             * @param  oldTypeSettingsProperties the old type settings properties
383             * @throws PortalException if a portal exception occurred
384             * @throws SystemException if a system exception occurred
385             */
386            public void verifyPolicy(
387                            Group group, Group oldGroup, List<AssetCategory> oldAssetCategories,
388                            List<AssetTag> oldAssetTags,
389                            Map<String, Serializable> oldExpandoAttributes,
390                            UnicodeProperties oldTypeSettingsProperties)
391                    throws PortalException, SystemException;
392    
393            /**
394             * Checks the integrity of the membership policy of the site role and
395             * performs operations necessary for the role's compliance.
396             *
397             * @param  role the role to verify
398             * @throws PortalException if a portal exception occurred
399             * @throws SystemException if a system exception occurred
400             */
401            public void verifyPolicy(Role role) throws PortalException, SystemException;
402    
403            /**
404             * Checks the integrity of the membership policy of the site role, with
405             * respect to its expando attributes, and performs operations necessary for
406             * the role's compliance. Liferay calls this method when adding and updating
407             * site roles.
408             *
409             * @param  role the added or updated role to verify
410             * @param  oldRole the old role
411             * @param  oldExpandoAttributes the old expando attributes
412             * @throws PortalException if a portal exception occurred
413             * @throws SystemException if a system exception occurred
414             */
415            public void verifyPolicy(
416                            Role role, Role oldRole,
417                            Map<String, Serializable> oldExpandoAttributes)
418                    throws PortalException, SystemException;
419    
420    }