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.Role;
019    
020    import java.io.Serializable;
021    
022    import java.util.Map;
023    
024    /**
025     * Provides the Role Membership Policy interface, allowing customization of user
026     * membership regarding roles.
027     *
028     * <p>
029     * Role Membership Policies define the roles a user is allowed to be assigned,
030     * and the roles the user must be assigned.
031     * </p>
032     *
033     * <p>
034     * An implementation may include any number of rules and actions to enforce
035     * those rules. The implementation may include rules and actions like the
036     * following:
037     * </p>
038     *
039     * <ul>
040     * <li>
041     * If a user doesn't have the custom attribute A, he cannot be assigned to role
042     * B.
043     * </li>
044     * <li>
045     * If the user is added to role A, he will automatically be added to role B.
046     * </li>
047     * <li>
048     * All users with the custom attribute A will automatically have the role B.
049     * </li>
050     * <li>
051     * All the users with role A cannot have role B (incompatible roles).
052     * </li>
053     * </ul>
054     *
055     * <p>
056     * Liferay's core services invoke {@link #checkRoles(long[], long[], long[])} to
057     * detect policy violations before adding the users to and removing the users
058     * from the roles. On passing the check, the service proceeds with the changes
059     * and propagates appropriate related actions in the portal by invoking {@link
060     * #propagateRoles(long[], long[], long[])}. On failing the check, the service
061     * foregoes making the changes. For example, Liferay executes this logic when
062     * adding and updating roles, and adding and removing roles with respect to
063     * users.
064     * </p>
065     *
066     * <p>
067     * Liferay's UI calls the "is*" methods, such as {@link #isRoleAllowed(long,
068     * long)}, to determine appropriate options to display to the user. For example,
069     * the UI calls {@link #isRoleAllowed(long, long)} to decide whether to enable
070     * the checkbox for adding the role to the user.
071     * </p>
072     *
073     * @author Roberto D??az
074     * @author Sergio Gonz??lez
075     */
076    public interface RoleMembershipPolicy {
077    
078            /**
079             * Checks if the roles can be added to or removed from their users.
080             *
081             * <p>
082             * Liferay's core services call this method before adding the users to and
083             * removing the users from the respective roles. If this method throws an
084             * exception, the service foregoes making the changes.
085             * </p>
086             *
087             * @param  userIds the primary keys of the users to be added and removed
088             *         from the roles
089             * @param  addRoleIds the primary keys of the roles to be added (optionally
090             *         <code>null</code>)
091             * @param  removeRoleIds the primary keys of the roles to be removed
092             *         (optionally <code>null</code>)
093             * @throws PortalException if any one role violated the policy or if a
094             *         portal exception occurred
095             */
096            public void checkRoles(
097                            long[] userIds, long[] addRoleIds, long[] removeRoleIds)
098                    throws PortalException;
099    
100            /**
101             * Returns <code>true</code> if the role can be added to the user. Liferay's
102             * UI calls this method.
103             *
104             * @param  userId the primary key of the user
105             * @param  roleId the primary key of the role
106             * @return <code>true</code> if the role can be added to the user;
107             *         <code>false</code> otherwise
108             * @throws PortalException if a portal exception occurred
109             */
110            public boolean isRoleAllowed(long userId, long roleId)
111                    throws PortalException;
112    
113            /**
114             * Returns <code>true</code> if the role is mandatory for the user.
115             * Liferay's UI, for example, calls this method in deciding whether the
116             * checkbox to select a role will be enable.
117             *
118             * @param  userId the primary key of the user
119             * @param  roleId the primary key of the role
120             * @return <code>true</code> if the role is mandatory for the user;
121             *         <code>false</code> otherwise
122             * @throws PortalException if a portal exception occurred
123             */
124            public boolean isRoleRequired(long userId, long roleId)
125                    throws PortalException;
126    
127            /**
128             * Performs membership policy related actions after the respective roles are
129             * added to and removed from the affected users. Liferay's core services
130             * call this method after the roles are added to and removed from the users.
131             *
132             * <p>
133             * The actions must ensure the membership policy of each role. For example,
134             * some actions for implementations to consider performing are:
135             * </p>
136             *
137             * <ul>
138             * <li>
139             * If the role A is added to a user, role B should be added too.
140             * </li>
141             * <li>
142             * If the role A is removed from a user, role B should be removed too.
143             * </li>
144             * </ul>
145             *
146             * @param  userIds the primary keys of the users
147             * @param  addRoleIds the primary keys of the added roles
148             * @param  removeRoleIds the primary keys of the removed roles
149             * @throws PortalException if a portal exception occurred
150             */
151            public void propagateRoles(
152                            long[] userIds, long[] addRoleIds, long[] removeRoleIds)
153                    throws PortalException;
154    
155            /**
156             * Checks the integrity of the membership policy of each of the portal's
157             * roles and performs operations necessary for the compliance of each role.
158             * This method can be triggered manually from the Control Panel. If the
159             * <code>membership.policy.auto.verify</code> portal property is
160             * <code>true</code> this method is triggered when starting Liferay and
161             * every time a membership policy hook is deployed.
162             *
163             * @throws PortalException if a portal exception occurred
164             */
165            public void verifyPolicy() throws PortalException;
166    
167            /**
168             * Checks the integrity of the membership policy of the role and performs
169             * operations necessary for the compliance of the role.
170             *
171             * @param  role the role to verify
172             * @throws PortalException if a portal exception occurred
173             */
174            public void verifyPolicy(Role role) throws PortalException;
175    
176            /**
177             * Checks the integrity of the membership policy of the role, with respect
178             * to the role's new attribute values and expando attributes, and performs
179             * operations necessary for the role's compliance. Liferay calls this method
180             * when adding and updating roles.
181             *
182             * @param  role the added or updated role to verify
183             * @param  oldRole the old role
184             * @param  oldExpandoAttributes the old expando attributes
185             * @throws PortalException if a portal exception occurred
186             */
187            public void verifyPolicy(
188                            Role role, Role oldRole,
189                            Map<String, Serializable> oldExpandoAttributes)
190                    throws PortalException;
191    
192    }