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