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.RoleMembership;
023import org.kuali.rice.kim.framework.type.KimTypeService;
024
025import javax.jws.WebMethod;
026import javax.jws.WebParam;
027import javax.jws.WebResult;
028import javax.jws.WebService;
029import javax.jws.soap.SOAPBinding;
030import javax.xml.bind.annotation.XmlElement;
031import javax.xml.bind.annotation.XmlElementWrapper;
032import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
033import java.util.List;
034import java.util.Map;
035
036/**
037 * A {@link KimTypeService} with specific methods for Roles.
038 */
039@WebService(name = "roleTypeService", targetNamespace = KimConstants.Namespaces.KIM_NAMESPACE_2_0)
040@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
041public interface RoleTypeService extends KimTypeService {
042
043    /**
044     * Gets whether a role assignment with the given qualifier is applicable for the given qualification.
045     * 
046     * For example, the qualifier for a role could be as follows:
047     *   chartOfAccountsCode = BL
048     *   organizationCode = ARSC
049     *   descendsHierarchy = true
050     *   
051     * The qualification could be:
052     *   chartOfAccountsCode = BL
053     *   organizationCode = PSY    (reports to BL-ARSC)
054     *   
055     * This method would return true for this set of arguments.  This would require a query of 
056     * the KFS organization hierarchy, so an implementation of this sort must be done by
057     * a service which lives within KFS and will be called remotely by KIM.
058     * 
059     * The contents of the passed in attribute sets should not be modified as they may be used in future calls by
060     * the role service.
061     *
062     * @param qualification the qualification.  cannot be null.
063     * @param roleQualifier the role qualifier. cannot be null.
064     * @return true if the qualifications match
065     * @throws RiceIllegalArgumentException if the qualification or roleQualifier is null
066     */
067    @WebMethod(operationName="doesRoleQualifierMatchQualification")
068    @WebResult(name = "match")
069    boolean doesRoleQualifierMatchQualification(@WebParam(name = "qualification")
070                                                @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
071                                                Map<String, String> qualification,
072                                                @WebParam(name = "roleQualifier")
073                                                @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
074                                                Map<String, String> roleQualifier) throws RiceIllegalArgumentException;
075
076    /**
077     * Gets whether a role membership with the given details is applicable for the given qualification.
078     *
079     * @param qualification the qualification.  cannot be null.
080     * @param roleMemberships the list of roleMemberships to check for matches. cannot be null.
081     * @return an immutable list of matched roleMemberships.  will not return null.
082     * @throws RiceIllegalArgumentException if the qualification or roleMemberships is null.
083     */
084    @WebMethod(operationName="getMatchingRoleMemberships")
085    @XmlElementWrapper(name = "roleMemberships", required = true)
086    @XmlElement(name = "roleMembership", required = false)
087    @WebResult(name = "roleMemberships")
088    List<RoleMembership> getMatchingRoleMemberships(@WebParam(name = "qualification")
089                                                    @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
090                                                    Map<String, String> qualification,
091                                                    @WebParam(name = "roleMemberships")
092                                                    List<RoleMembership> roleMemberships) throws RiceIllegalArgumentException;
093
094    /**
095     * Returns true if this role type represents a "derived" role type.  That is, the members of the 
096     * role are known to the host application, not to KIM.  This is needed for cases like the KFS
097     * Fiscal Officer, where the members of the role are in the Account table in the KFS database.
098     *
099     * @return true if derived type
100     */
101    @WebMethod(operationName="isDerivedRoleType")
102    @WebResult(name = "derivedRoleType")
103    boolean isDerivedRoleType();
104
105    /**
106     * This method can be used to check if the given principal has this derived role.  It is designed to be used in case
107     * there is a more efficient way to check for whether a principal is in a role rather than retrieving all the
108     * members of the role and checking against that.
109     * 
110     * The groupIds parameter is intended to be the complete list of groups to which the principal belongs.  If either the
111     * principalId or the groupIds parameters are blank/empty, that parameter should be ignored.
112     *
113     * @param principalId the principalId. cannot be null or blank.
114     * @param groupIds the groupIds the principal is a member of. cannot be null.
115     * @param namespaceCode the namespace code the role is in. cannot be blank or null.
116     * @param roleName the name of the role.  cannot be blank or null.
117     * @param qualification the qualification.  cannot be null.
118     * @return if the principal has a derived role.
119     * @throws RiceIllegalArgumentException if the principalId, namespaceCode, roleName is blank or null.
120     * @throws RiceIllegalArgumentException if the groupIds, qualification is null.
121     */
122    @WebMethod(operationName="hasDerivedRole")
123    @WebResult(name = "derivedRole")
124    boolean hasDerivedRole( @WebParam(name = "principalId")
125                                String principalId,
126                                @WebParam(name = "groupIds")
127                                List<String> groupIds,
128                                @WebParam(name = "namespaceCode")
129                                String namespaceCode,
130                                @WebParam(name = "roleName")
131                                String roleName,
132                                @WebParam(name = "qualification")
133                                @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
134                                Map<String, String> qualification ) throws RiceIllegalArgumentException;
135
136    @WebMethod(operationName = "getRoleMembersFromDerivedRole")
137    @XmlElementWrapper(name = "roleMemberships", required = true)
138    @XmlElement(name = "roleMembership", required = false)
139    @WebResult(name = "roleMemberships")
140    List<RoleMembership> getRoleMembersFromDerivedRole(
141            @WebParam(name = "namespaceCode") String namespaceCode,
142            @WebParam(name = "roleName") String roleName,
143            @WebParam(name = "qualification")
144            @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualification
145    ) throws RiceIllegalArgumentException;
146
147    /**
148     * For roles where the order of members returned may be meaningful,
149     * this method provides a hook to sort the results before they
150     * are returned from getRoleMembers on the RoleService.
151     *
152     * This method may alter the passed in list directly and return it rather than
153     * allocating a new list.
154     * 
155     * This is also the place where the roleSortingCode property on the RoleMembershipInfo objects can be
156     * populated in preparation for routing if not all members of this role should be group as separate
157     * units for routing.
158     * 
159     * @param roleMemberships the list of roleMemberships to check for matches. cannot be null.
160     * @return an immutable list of matched roleMemberships.  will not return null.
161     * @throws RiceIllegalArgumentException if the roleMemberships is null.
162     */
163    @WebMethod(operationName="sortRoleMembers")
164    @XmlElementWrapper(name = "roleMemberships", required = true)
165    @XmlElement(name = "roleMembership", required = false)
166    @WebResult(name = "roleMemberships")
167    List<RoleMembership> sortRoleMembers( @WebParam(name = "roleMemberships")
168                                          List<RoleMembership> roleMembers ) throws RiceIllegalArgumentException;
169    
170    /**
171     * Takes the passed in qualifications and converts them, if necessary, for any downstream roles which may be present.
172     *
173     * @param namespaceCode the namespace code the role is in. cannot be blank or null.
174     * @param roleName the name of the role.  cannot be blank or null.
175     * @param memberRoleNamespaceCode the namespace code the member role is in. cannot be blank or null.
176     * @param memberRoleName the name of the member role.  cannot be blank or null.
177     * @param qualification the qualification.  cannot be null.
178     * @return an immutable map of qualifiers. Will never return null.
179     * @throws RiceIllegalArgumentException if the namespaceCode, roleName, memberRoleNamespaceCode, memberRoleName is blank or null.
180     * @throws RiceIllegalArgumentException if the qualification is null.
181     */
182    @WebMethod(operationName="convertQualificationForMemberRoles")
183    @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
184    @WebResult(name = "qualification")
185    Map<String, String> convertQualificationForMemberRoles( @WebParam(name = "namespaceCode")
186                                                            String namespaceCode,
187                                                            @WebParam(name = "roleName")
188                                                            String roleName,
189                                                            @WebParam(name = "memberRoleNamespaceCode")
190                                                            String memberRoleNamespaceCode,
191                                                            @WebParam(name = "memberRoleName")
192                                                            String memberRoleName,
193                                                            @WebParam(name = "qualification")
194                                                            @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
195                                                            Map<String, String> qualification ) throws RiceIllegalArgumentException;
196    
197    /**
198     * Determines if the role specified by the given namespace and role name has a dynamic role membership.
199     *
200     * A dynamic role membership means that a role membership may be changed over time and cannot be safely cached.
201     * 
202     * @param namespaceCode the namespace code of the role. cannot be null or blank
203     * @param roleName the name of the role. cannot be null or blank.
204     * @return true if the membership results of the Role are dynamic, false otherwise
205     * @throws IllegalArgumentException if the namespaceCode, roleName is blank or null.
206     */
207    @WebMethod(operationName="dynamicRoleMembership")
208    @WebResult(name = "dynamic")
209    boolean dynamicRoleMembership(@WebParam(name = "namespaceCode") String namespaceCode, @WebParam(name = "roleName") String roleName) throws RiceIllegalArgumentException;
210    
211    /**
212     * Roles whose memberships may be matched exactly by qualifiers,
213     * this method returns the list of such qualifier names.
214     * 
215     * @return immutable list of qualifier names that can be used for exact match.  Will never return null.
216     */
217    @WebMethod(operationName="getQualifiersForExactMatch")
218    @XmlElementWrapper(name = "names", required = true)
219    @XmlElement(name = "name", required = false)
220    @WebResult(name = "names")
221    List<String> getQualifiersForExactMatch();
222
223    /**
224     * Returns whether a membertype should have its qualifiers validated
225     * @return true if
226     * @since 2.1.2
227     */
228    @WebMethod(operationName="shouldvalidateQualifiersForMemberType")
229    @WebResult(name="validateQualifiers")
230    boolean shouldValidateQualifiersForMemberType(@WebParam(name="memberType") MemberType memberType);
231}