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