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