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 from
088             *        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             */
094            public void checkRoles(
095                            long[] userIds, long[] addRoleIds, long[] removeRoleIds)
096                    throws PortalException;
097    
098            /**
099             * Returns <code>true</code> if the role can be added to the user. Liferay's
100             * UI calls this method.
101             *
102             * @param  userId the primary key of the user
103             * @param  roleId the primary key of the role
104             * @return <code>true</code> if the role can be added to the user;
105             *         <code>false</code> otherwise
106             */
107            public boolean isRoleAllowed(long userId, long roleId)
108                    throws PortalException;
109    
110            /**
111             * Returns <code>true</code> if the role is mandatory for the user.
112             * Liferay's UI, for example, calls this method in deciding whether the
113             * checkbox to select a role will be enable.
114             *
115             * @param  userId the primary key of the user
116             * @param  roleId the primary key of the role
117             * @return <code>true</code> if the role is mandatory for the user;
118             *         <code>false</code> otherwise
119             */
120            public boolean isRoleRequired(long userId, long roleId)
121                    throws PortalException;
122    
123            /**
124             * Performs membership policy related actions after the respective roles are
125             * added to and removed from the affected users. Liferay's core services
126             * call this method after the roles are added to and removed from the users.
127             *
128             * <p>
129             * The actions must ensure the membership policy of each role. For example,
130             * some actions for implementations to consider performing are:
131             * </p>
132             *
133             * <ul>
134             * <li>
135             * If the role A is added to a user, role B should be added too.
136             * </li>
137             * <li>
138             * If the role A is removed from a user, role B should be removed too.
139             * </li>
140             * </ul>
141             *
142             * @param userIds the primary keys of the users
143             * @param addRoleIds the primary keys of the added roles
144             * @param removeRoleIds the primary keys of the removed roles
145             */
146            public void propagateRoles(
147                            long[] userIds, long[] addRoleIds, long[] removeRoleIds)
148                    throws PortalException;
149    
150            /**
151             * Checks the integrity of the membership policy of each of the portal's
152             * roles and performs operations necessary for the compliance of each role.
153             * This method can be triggered manually from the Control Panel. If the
154             * <code>membership.policy.auto.verify</code> portal property is
155             * <code>true</code> this method is triggered when starting Liferay and
156             * every time a membership policy hook is deployed.
157             */
158            public void verifyPolicy() throws PortalException;
159    
160            /**
161             * Checks the integrity of the membership policy of the role and performs
162             * operations necessary for the compliance of the role.
163             *
164             * @param role the role to verify
165             */
166            public void verifyPolicy(Role role) throws PortalException;
167    
168            /**
169             * Checks the integrity of the membership policy of the role, with respect
170             * to the role's new attribute values and expando attributes, and performs
171             * operations necessary for the role's compliance. Liferay calls this method
172             * when adding and updating roles.
173             *
174             * @param role the added or updated role to verify
175             * @param oldRole the old role
176             * @param oldExpandoAttributes the old expando attributes
177             */
178            public void verifyPolicy(
179                            Role role, Role oldRole,
180                            Map<String, Serializable> oldExpandoAttributes)
181                    throws PortalException;
182    
183    }