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