001/**
002 * Copyright 2005-2016 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.kim.framework.role;
017
018import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
019import org.kuali.rice.core.api.membership.MemberType;
020import org.kuali.rice.core.api.util.jaxb.MapStringStringAdapter;
021import org.kuali.rice.kim.api.KimConstants;
022import org.kuali.rice.kim.api.role.RoleMember;
023import org.kuali.rice.kim.api.role.RoleMembership;
024import org.kuali.rice.kim.framework.type.KimTypeService;
025
026import javax.jws.WebMethod;
027import javax.jws.WebParam;
028import javax.jws.WebResult;
029import javax.jws.WebService;
030import javax.jws.soap.SOAPBinding;
031import javax.xml.bind.annotation.XmlElement;
032import javax.xml.bind.annotation.XmlElementWrapper;
033import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
034import java.util.List;
035import java.util.Map;
036
037/**
038 * A {@link KimTypeService} with specific methods for Roles.
039 */
040@WebService(name = "roleTypeService", targetNamespace = KimConstants.Namespaces.KIM_NAMESPACE_2_0)
041@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
042public interface RoleTypeService extends KimTypeService {
043
044    /**
045     * Gets whether a role assignment with the given qualifier is applicable for the given qualification.
046     * 
047     * For example, the qualifier for a role could be as follows:
048     *   chartOfAccountsCode = BL
049     *   organizationCode = ARSC
050     *   descendsHierarchy = true
051     *   
052     * The qualification could be:
053     *   chartOfAccountsCode = BL
054     *   organizationCode = PSY    (reports to BL-ARSC)
055     *   
056     * This method would return true for this set of arguments.  This would require a query of 
057     * the KFS organization hierarchy, so an implementation of this sort must be done by
058     * a service which lives within KFS and will be called remotely by KIM.
059     * 
060     * The contents of the passed in attribute sets should not be modified as they may be used in future calls by
061     * the role service.
062     *
063     * @param qualification the qualification.  cannot be null.
064     * @param roleQualifier the role qualifier. cannot be null.
065     * @return true if the qualifications match
066     * @throws RiceIllegalArgumentException if the qualification or roleQualifier is null
067     */
068    @WebMethod(operationName="doesRoleQualifierMatchQualification")
069    @WebResult(name = "match")
070    boolean doesRoleQualifierMatchQualification(@WebParam(name = "qualification")
071                                                @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
072                                                Map<String, String> qualification,
073                                                @WebParam(name = "roleQualifier")
074                                                @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
075                                                Map<String, String> roleQualifier) throws RiceIllegalArgumentException;
076
077    /**
078     * Gets whether a role membership with the given details is applicable for the given qualification.
079     *
080     * @param qualification the qualification.  cannot be null.
081     * @param roleMemberships the list of roleMemberships to check for matches. cannot be null.
082     * @return an immutable list of matched roleMemberships.  will not return null.
083     * @throws RiceIllegalArgumentException if the qualification or roleMemberships is null.
084     */
085    @WebMethod(operationName="getMatchingRoleMemberships")
086    @XmlElementWrapper(name = "roleMemberships", required = true)
087    @XmlElement(name = "roleMembership", required = false)
088    @WebResult(name = "roleMemberships")
089    List<RoleMembership> getMatchingRoleMemberships(@WebParam(name = "qualification")
090                                                    @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
091                                                    Map<String, String> qualification,
092                                                    @WebParam(name = "roleMemberships")
093                                                    List<RoleMembership> roleMemberships) throws RiceIllegalArgumentException;
094
095    /**
096     * Returns true if this role type represents a "derived" role type.  That is, the members of the 
097     * role are known to the host application, not to KIM.  This is needed for cases like the KFS
098     * Fiscal Officer, where the members of the role are in the Account table in the KFS database.
099     *
100     * @return true if derived type
101     */
102    @WebMethod(operationName="isDerivedRoleType")
103    @WebResult(name = "derivedRoleType")
104    boolean isDerivedRoleType();
105
106    /**
107     * This method can be used to check if the given principal has this derived role.  It is designed to be used in case
108     * there is a more efficient way to check for whether a principal is in a role rather than retrieving all the
109     * members of the role and checking against that.
110     * 
111     * The groupIds parameter is intended to be the complete list of groups to which the principal belongs.  If either the
112     * principalId or the groupIds parameters are blank/empty, that parameter should be ignored.
113     *
114     * @param principalId the principalId. cannot be null or blank.
115     * @param groupIds the groupIds the principal is a member of. cannot be null.
116     * @param namespaceCode the namespace code the role is in. cannot be blank or null.
117     * @param roleName the name of the role.  cannot be blank or null.
118     * @param qualification the qualification.  cannot be null.
119     * @return if the principal has a derived role.
120     * @throws RiceIllegalArgumentException if the principalId, namespaceCode, roleName is blank or null.
121     * @throws RiceIllegalArgumentException if the groupIds, qualification is null.
122     */
123    @WebMethod(operationName="hasDerivedRole")
124    @WebResult(name = "derivedRole")
125    boolean hasDerivedRole( @WebParam(name = "principalId")
126                                String principalId,
127                                @WebParam(name = "groupIds")
128                                List<String> groupIds,
129                                @WebParam(name = "namespaceCode")
130                                String namespaceCode,
131                                @WebParam(name = "roleName")
132                                String roleName,
133                                @WebParam(name = "qualification")
134                                @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
135                                Map<String, String> qualification ) throws RiceIllegalArgumentException;
136
137    @WebMethod(operationName = "getRoleMembersFromDerivedRole")
138    @XmlElementWrapper(name = "roleMemberships", required = true)
139    @XmlElement(name = "roleMembership", required = false)
140    @WebResult(name = "roleMemberships")
141    List<RoleMembership> getRoleMembersFromDerivedRole(
142            @WebParam(name = "namespaceCode") String namespaceCode,
143            @WebParam(name = "roleName") String roleName,
144            @WebParam(name = "qualification")
145            @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualification
146    ) throws RiceIllegalArgumentException;
147
148    /**
149     * For roles where the order of members returned may be meaningful,
150     * this method provides a hook to sort the results before they
151     * are returned from getRoleMembers on the RoleService.
152     *
153     * This method may alter the passed in list directly and return it rather than
154     * allocating a new list.
155     * 
156     * This is also the place where the roleSortingCode property on the RoleMembershipInfo objects can be
157     * populated in preparation for routing if not all members of this role should be group as separate
158     * units for routing.
159     * 
160     * @param roleMemberships the list of roleMemberships to check for matches. cannot be null.
161     * @return an immutable list of matched roleMemberships.  will not return null.
162     * @throws RiceIllegalArgumentException if the roleMemberships is null.
163     */
164    @WebMethod(operationName="sortRoleMembers")
165    @XmlElementWrapper(name = "roleMemberships", required = true)
166    @XmlElement(name = "roleMembership", required = false)
167    @WebResult(name = "roleMemberships")
168    List<RoleMembership> sortRoleMembers( @WebParam(name = "roleMemberships")
169                                          List<RoleMembership> roleMembers ) throws RiceIllegalArgumentException;
170    
171    /**
172     * Takes the passed in qualifications and converts them, if necessary, for any downstream roles which may be present.
173     *
174     * @deprecated use convertQualificationForMemberRolesAndMemberAttributes
175     * @param namespaceCode the namespace code the role is in. cannot be blank or null.
176     * @param roleName the name of the role.  cannot be blank or null.
177     * @param memberRoleNamespaceCode the namespace code the member role is in. cannot be blank or null.
178     * @param memberRoleName the name of the member role.  cannot be blank or null.
179     * @param qualification the qualification.  cannot be null.
180     * @return an immutable map of qualifiers. Will never return null.
181     * @throws RiceIllegalArgumentException if the namespaceCode, roleName, memberRoleNamespaceCode, memberRoleName is blank or null.
182     * @throws RiceIllegalArgumentException if the qualification is null.
183     */
184    @Deprecated
185    @WebMethod(operationName="convertQualificationForMemberRoles")
186    @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
187    @WebResult(name = "qualification")
188    Map<String, String> convertQualificationForMemberRoles( @WebParam(name = "namespaceCode")
189                                                            String namespaceCode,
190                                                            @WebParam(name = "roleName")
191                                                            String roleName,
192                                                            @WebParam(name = "memberRoleNamespaceCode")
193                                                            String memberRoleNamespaceCode,
194                                                            @WebParam(name = "memberRoleName")
195                                                            String memberRoleName,
196                                                            @WebParam(name = "qualification")
197                                                            @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
198                                                            Map<String, String> qualification ) throws RiceIllegalArgumentException;
199
200    /**
201     * Takes the passed in qualifications and converts them, if necessary, for any downstream roles which may be present.
202     *
203     * @since 2.3.4
204     * @param namespaceCode the namespace code the role is in. cannot be blank or null.
205     * @param roleName the name of the role.  cannot be blank or null.
206     * @param memberRoleNamespaceCode the namespace code the member role is in. cannot be blank or null.
207     * @param memberRoleName the name of the member role.  cannot be blank or null.
208     * @param qualification the qualification.  cannot be null.
209     * @param memberQualification the attributes defined for the memberRole
210     * @return an immutable map of qualifiers. Will never return null.
211     * @throws RiceIllegalArgumentException if the namespaceCode, roleName, memberRoleNamespaceCode, memberRoleName is blank or null.
212     * @throws RiceIllegalArgumentException if the qualification is null.
213     */
214    @WebMethod(operationName="convertQualificationForMemberRolesAndMemberAttributes")
215    @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
216    @WebResult(name = "qualification")
217    Map<String, String> convertQualificationForMemberRolesAndMemberAttributes( @WebParam(name = "namespaceCode")
218    String namespaceCode,
219            @WebParam(name = "roleName")
220            String roleName,
221            @WebParam(name = "memberRoleNamespaceCode")
222            String memberRoleNamespaceCode,
223            @WebParam(name = "memberRoleName")
224            String memberRoleName,
225            @WebParam(name = "qualification")
226            @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
227            Map<String, String> qualification,
228            @WebParam(name = "memberQualification")
229            @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
230            Map<String, String> memberQualification) throws RiceIllegalArgumentException;
231    
232    /**
233     * Determines if the role specified by the given namespace and role name has a dynamic role membership.
234     *
235     * A dynamic role membership means that a role membership may be changed over time and cannot be safely cached.
236     * 
237     * @param namespaceCode the namespace code of the role. cannot be null or blank
238     * @param roleName the name of the role. cannot be null or blank.
239     * @return true if the membership results of the Role are dynamic, false otherwise
240     * @throws IllegalArgumentException if the namespaceCode, roleName is blank or null.
241     */
242    @WebMethod(operationName="dynamicRoleMembership")
243    @WebResult(name = "dynamic")
244    boolean dynamicRoleMembership(@WebParam(name = "namespaceCode") String namespaceCode, @WebParam(name = "roleName") String roleName) throws RiceIllegalArgumentException;
245    
246    /**
247     * Roles whose memberships may be matched exactly by qualifiers,
248     * this method returns the list of such qualifier names.
249     * 
250     * @return immutable list of qualifier names that can be used for exact match.  Will never return null.
251     */
252    @WebMethod(operationName="getQualifiersForExactMatch")
253    @XmlElementWrapper(name = "names", required = true)
254    @XmlElement(name = "name", required = false)
255    @WebResult(name = "names")
256    List<String> getQualifiersForExactMatch();
257
258    /**
259     * Returns whether a membertype should have its qualifiers validated
260     * @return true if
261     * @since 2.1.2
262     */
263    @WebMethod(operationName="shouldvalidateQualifiersForMemberType")
264    @WebResult(name="validateQualifiers")
265    boolean shouldValidateQualifiersForMemberType(@WebParam(name="memberType") MemberType memberType);
266
267    // Added a hook which is called whenever a member is removed from a role.
268    @WebMethod(operationName="roleMemberRemoved")
269    void roleMemberRemoved(@WebParam(name="member") RoleMember member);
270}