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
118             *         from 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             * @throws PortalException if any one user could not be added to a site, if
124             *         any one user could not be removed from a site, or if a portal
125             *         exception occurred
126             */
127            public void checkMembership(
128                            long[] userIds, long[] addGroupIds, long[] removeGroupIds)
129                    throws PortalException;
130    
131            /**
132             * Checks if the site roles can be added to or removed from their users.
133             *
134             * <p>
135             * Liferay's core services call this method before adding the users to and
136             * removing the users from the respective site roles. If this method throws
137             * an exception, the service foregoes making the changes.
138             * </p>
139             *
140             * @param  addUserGroupRoles the user group roles to be added
141             * @param  removeUserGroupRoles the user group roles to be removed
142             * @throws PortalException if any one user group role violated the policy or
143             *         if a portal exception occurred
144             */
145            public void checkRoles(
146                            List<UserGroupRole> addUserGroupRoles,
147                            List<UserGroupRole> removeUserGroupRoles)
148                    throws PortalException;
149    
150            /**
151             * Returns <code>true</code> if the user can be added to the site. Liferay's
152             * UI calls this method.
153             *
154             * @param  userId the primary key of the user
155             * @param  groupId the primary key of the site
156             * @return <code>true</code> if the user can be added to the site;
157             *         <code>false</code> otherwise
158             * @throws PortalException if a portal exception occurred
159             */
160            public boolean isMembershipAllowed(long userId, long groupId)
161                    throws PortalException;
162    
163            /**
164             * Returns <code>true</code> if the policy prevents the user from being
165             * removed from the site by the user associated with the permission checker.
166             *
167             * @param  permissionChecker the permission checker referencing a user
168             * @param  userId the primary key of the user to check for protection
169             * @param  groupId the primary key of the site
170             * @return <code>true</code> if the policy prevents the user from being
171             *         removed from the site by the user associated with the permission
172             *         checker; <code>false</code> otherwise
173             * @throws PortalException if a portal exception occurred
174             */
175            public boolean isMembershipProtected(
176                            PermissionChecker permissionChecker, long userId, long groupId)
177                    throws PortalException;
178    
179            /**
180             * Returns <code>true</code> if site membership for the user is mandatory.
181             * Liferay's UI, for example, calls this method in deciding whether to
182             * display the option to leave the site.
183             *
184             * @param  userId the primary key of the user
185             * @param  groupId the primary key of the site
186             * @return <code>true</code> if site membership for the user is mandatory;
187             *         <code>false</code> otherwise
188             * @throws PortalException if a portal exception occurred
189             */
190            public boolean isMembershipRequired(long userId, long groupId)
191                    throws PortalException;
192    
193            /**
194             * Returns <code>true</code> if the role can be added to the user on the
195             * site. Liferay's UI calls this method.
196             *
197             * @param  userId the primary key of the user
198             * @param  groupId the primary key of the site
199             * @param  roleId the primary key of the role
200             * @return <code>true</code> if the role can be added to the user on the
201             *         site; <code>false</code> otherwise
202             * @throws PortalException if a portal exception occurred
203             */
204            public boolean isRoleAllowed(long userId, long groupId, long roleId)
205                    throws PortalException;
206    
207            /**
208             * Returns <code>true</code> if the policy prevents the user from being
209             * removed from the role by the user associated with the permission checker.
210             *
211             * @param  permissionChecker the permission checker referencing a user
212             * @param  userId the primary key of the user to check for protection
213             * @param  groupId the primary key of the site
214             * @param  roleId the primary key of the role
215             * @return <code>true</code> if the policy prevents the user from being
216             *         removed from the role by the user associated with the permission
217             *         checker; <code>false</code> otherwise
218             * @throws PortalException if a portal exception occurred
219             */
220            public boolean isRoleProtected(
221                            PermissionChecker permissionChecker, long userId, long groupId,
222                            long roleId)
223                    throws PortalException;
224    
225            /**
226             * Returns <code>true</code> if the role is mandatory for the user on the
227             * site. Liferay's UI calls this method.
228             *
229             * @param  userId the primary key of the user
230             * @param  groupId the primary key of the site
231             * @param  roleId the primary key of the role
232             * @return <code>true</code> if the role is mandatory for the user on the
233             *         site; <code>false</code> otherwise
234             * @throws PortalException if a portal exception occurred
235             */
236            public boolean isRoleRequired(long userId, long groupId, long roleId)
237                    throws PortalException;
238    
239            /**
240             * Performs membership policy related actions after the users are added to
241             * and removed from the respective sites. Liferay's core services call this
242             * method after adding and removing the users to and from the respective
243             * sites.
244             *
245             * <p>
246             * The actions must ensure the integrity of each site's membership policy.
247             * For example, some actions for implementations to consider performing are:
248             * </p>
249             *
250             * <ul>
251             * <li>
252             * Adding the users to the child sites of each site to which the users
253             * were added.
254             * </li>
255             * <li>
256             * Removing the users from the child sites of each site from which the users
257             * were removed.
258             * </li>
259             * </ul>
260             *
261             * @param  userIds the primary key of the users that have been added or
262             *         removed
263             * @param  addGroupIds the primary keys of the sites to which the users were
264             *         added (optionally <code>null</code>)
265             * @param  removeGroupIds the primary keys of the sites from which the users
266             *         were removed (optionally <code>null</code>)
267             * @throws PortalException if a portal exception occurred
268             */
269            public void propagateMembership(
270                            long[] userIds, long[] addGroupIds, long[] removeGroupIds)
271                    throws PortalException;
272    
273            /**
274             * Performs membership policy related actions after the respective site
275             * roles are added to and removed from the affected users. Liferay's core
276             * services call this method after the roles are added to and removed from
277             * the users.
278             *
279             * <p>
280             * The actions must ensure the membership policy of each site role. For
281             * example, some actions for implementations to consider performing are:
282             * </p>
283             *
284             * <ul>
285             * <li>
286             * If the role A is added to a user, role B should be added too.
287             * </li>
288             * <li>
289             * If the role A is removed from a user, role B should be removed too.
290             * </li>
291             * </ul>
292             *
293             * @param  addUserGroupRoles the user group roles added
294             * @param  removeUserGroupRoles the user group roles removed
295             * @throws PortalException if a portal exception occurred
296             */
297            public void propagateRoles(
298                            List<UserGroupRole> addUserGroupRoles,
299                            List<UserGroupRole> removeUserGroupRoles)
300                    throws PortalException;
301    
302            /**
303             * Checks the integrity of the membership policy of each of the portal's
304             * sites and performs operations necessary for the compliance of each site
305             * and site role. This method can be triggered manually from the Control
306             * Panel. If the <code>membership.policy.auto.verify</code> portal property
307             * is <code>true</code> this method is triggered when starting Liferay and
308             * every time a membership policy hook is deployed.
309             *
310             * @throws PortalException if a portal exception occurred
311             */
312            public void verifyPolicy() throws PortalException;
313    
314            /**
315             * Checks the integrity of the membership policy of the site and performs
316             * operations necessary for the site's compliance.
317             *
318             * @param  group the site to verify
319             * @throws PortalException if a portal exception occurred
320             */
321            public void verifyPolicy(Group group) throws PortalException;
322    
323            /**
324             * Checks the integrity of the membership policy of the site, with respect
325             * to the site's new attribute values, categories, tags, expando attributes,
326             * and type settings properties, and performs operations necessary for the
327             * compliance of the site and its site roles. Liferay calls this method when
328             * adding and updating sites.
329             *
330             * <p>
331             * The actions must ensure the integrity of the site's membership policy
332             * based on what has changed in the site's attribute values, categories,
333             * tags, expando attributes, and type settings properties.
334             * </p>
335             *
336             * <p>
337             * For example, if the membership policy is that sites with the
338             * "admnistrator" tag should only allow administrators as users, then this
339             * method could enforce that policy using the following logic:
340             * </p>
341             *
342             * <ul>
343             * <li>
344             * If the old tags include the "administrator" tag and the new tags include
345             * it too, then no action needs to be performed regarding the
346             * policy. Note, the new tags can be obtained by calling
347             * <code>assetTagLocalService.getTags(Group.class.getName(),
348             * group.getGroupId());</code>.
349             * </li>
350             * <li>
351             * If the old tags include the "administrator" tag and the new tags don't
352             * include it,
353             * then no action needs to be performed regarding the
354             * policy, as non-administrator users need not be removed.
355             * </li>
356             * <li>
357             * However, if the old tags don't include the "administrator" tag, but the
358             * new tags include it, any site user that does not have the Administrator
359             * role
360             * must be removed from the site.
361             * </li>
362             *
363             * @param  group the added or updated site to verify
364             * @param  oldGroup the old site
365             * @param  oldAssetCategories the old categories
366             * @param  oldAssetTags the old tags
367             * @param  oldExpandoAttributes the old expando attributes
368             * @param  oldTypeSettingsProperties the old type settings properties
369             * @throws PortalException if a portal exception occurred
370             */
371            public void verifyPolicy(
372                            Group group, Group oldGroup, List<AssetCategory> oldAssetCategories,
373                            List<AssetTag> oldAssetTags,
374                            Map<String, Serializable> oldExpandoAttributes,
375                            UnicodeProperties oldTypeSettingsProperties)
376                    throws PortalException;
377    
378            /**
379             * Checks the integrity of the membership policy of the site role and
380             * performs operations necessary for the role's compliance.
381             *
382             * @param  role the role to verify
383             * @throws PortalException if a portal exception occurred
384             */
385            public void verifyPolicy(Role role) throws PortalException;
386    
387            /**
388             * Checks the integrity of the membership policy of the site role, with
389             * respect to its expando attributes, and performs operations necessary for
390             * the role's compliance. Liferay calls this method when adding and updating
391             * site roles.
392             *
393             * @param  role the added or updated role to verify
394             * @param  oldRole the old role
395             * @param  oldExpandoAttributes the old expando attributes
396             * @throws PortalException if a portal exception occurred
397             */
398            public void verifyPolicy(
399                            Role role, Role oldRole,
400                            Map<String, Serializable> oldExpandoAttributes)
401                    throws PortalException;
402    
403    }