001 /**
002 * Copyright 2005-2015 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 */
016 package org.kuali.rice.kim.api.role;
017
018 import org.kuali.rice.core.api.criteria.QueryByCriteria;
019 import org.kuali.rice.core.api.delegation.DelegationType;
020 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
021 import org.kuali.rice.core.api.exception.RiceIllegalStateException;
022 import org.kuali.rice.core.api.util.jaxb.MapStringStringAdapter;
023 import org.kuali.rice.kim.api.KimApiConstants;
024 import org.kuali.rice.kim.api.common.delegate.DelegateMember;
025 import org.kuali.rice.kim.api.common.delegate.DelegateType;
026 import org.kuali.rice.kim.api.permission.Permission;
027 import org.kuali.rice.kim.api.responsibility.Responsibility;
028 import org.springframework.cache.annotation.CacheEvict;
029 import org.springframework.cache.annotation.Cacheable;
030
031 import javax.jws.WebMethod;
032 import javax.jws.WebParam;
033 import javax.jws.WebResult;
034 import javax.jws.WebService;
035 import javax.jws.soap.SOAPBinding;
036 import javax.xml.bind.annotation.XmlElement;
037 import javax.xml.bind.annotation.XmlElementWrapper;
038 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
039 import java.util.Collection;
040 import java.util.List;
041 import java.util.Map;
042 import java.util.Set;
043
044 /**
045 *
046 * This service provides operations for querying role and role qualification
047 * data.
048 *
049 * <p>A role is where permissions and responsibilities are granted. Roles have
050 * a membership consisting of principals, groups or even other roles. By
051 * being assigned as members of a role, the associated principals will be
052 * granted all permissions and responsibilities that have been granted to the
053 * role.
054 *
055 * <p>Each membership assignment on the role can have a qualification which
056 * defines extra information about that particular member of the role. For
057 * example, one may have the role of "Dean" but that can be further qualified
058 * by the school they are the dean of, such as "Dean of Computer Science".
059 * Authorization checks that are then done in the permission service can pass
060 * qualifiers as part of the operation if they want to restrict the subset of
061 * the role against which the check is made.
062 *
063 * @author Kuali Rice Team (rice.collab@kuali.org)
064 *
065 */
066 @WebService(name = "roleService", targetNamespace = KimApiConstants.Namespaces.KIM_NAMESPACE_2_0 )
067 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
068 public interface RoleService {
069 /**
070 * This will create a {@link org.kuali.rice.kim.api.role.Role} exactly like the role passed in.
071 *
072 * @param role the role to create
073 * @return the newly created object. will never be null.
074 * @throws RiceIllegalArgumentException if the role passed in is null
075 * @throws RiceIllegalStateException if the role is already existing in the system
076 */
077 @WebMethod(operationName="createRole")
078 @WebResult(name = "role")
079 @CacheEvict(value={Permission.Cache.NAME, Responsibility.Cache.NAME, Role.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME}, allEntries = true)
080 Role createRole(@WebParam(name = "role") Role role)
081 throws RiceIllegalArgumentException, RiceIllegalStateException;
082
083 /**
084 * This will update a {@link Role}.
085 *
086 * @param role the role to update
087 * @throws RiceIllegalArgumentException if the role is null
088 * @throws RiceIllegalStateException if the role does not exist in the system
089 */
090 @WebMethod(operationName="updateRole")
091 @WebResult(name = "role")
092 @CacheEvict(value={Permission.Cache.NAME, Responsibility.Cache.NAME, Role.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME}, allEntries = true)
093 Role updateRole(@WebParam(name = "role") Role role)
094 throws RiceIllegalArgumentException, RiceIllegalStateException;
095
096 /**
097 * Get the KIM Role object with the given ID.
098 *
099 * @param id the id of the role.
100 * @return the role with the given id or null if role doesn't exist.
101 * @throws RiceIllegalArgumentException if roleId is null or Blank
102 */
103 @WebMethod(operationName = "getRole")
104 @WebResult(name = "role")
105 @Cacheable(value= Role.Cache.NAME, key="'id=' + #p0")
106 Role getRole(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
107
108 /**
109 * Get the KIM Role objects for the role IDs in the given List.
110 *
111 * @param ids the ids of the roles.
112 * @return a list of roles with the given ids or null if no roles are found.
113 * @throws RiceIllegalArgumentException if ids is null or Blank
114 */
115 @WebMethod(operationName = "getRoles")
116 @XmlElementWrapper(name = "roles", required = true)
117 @XmlElement(name = "role", required = false)
118 @WebResult(name = "roles")
119 @Cacheable(value= Role.Cache.NAME, key="'ids=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0)")
120 List<Role> getRoles( @WebParam(name="ids") List<String> ids ) throws RiceIllegalArgumentException;
121
122 /** Get the KIM Role object with the unique combination of namespace, component,
123 * and role name.
124 *
125 * @param namespaceCode the namespace code of the role.
126 * @param name the name of the role.
127 * @return a role with the given namespace code and name or null if role does not exist.
128 * @throws RiceIllegalArgumentException if namespaceCode or name is null or blank.
129 */
130 @WebMethod(operationName = "getRoleByNamespaceCodeAndName")
131 @WebResult(name = "role")
132 @Cacheable(value=Role.Cache.NAME, key="'namespaceCode=' + #p0 + '|' + 'name=' + #p1")
133 Role getRoleByNamespaceCodeAndName(@WebParam(name = "namespaceCode") String namespaceCode,
134 @WebParam(name = "name") String name) throws RiceIllegalArgumentException;
135
136 /**
137 * Return the Role ID for the given unique combination of namespace,
138 * component and role name.
139 *
140 * @param namespaceCode the namespace code of the role.
141 * @param name the name of the role.
142 * @return a role id for a role with the given namespace code and name or null if role does not exist.
143 * @throws RiceIllegalArgumentException if namespaceCode or name is null or blank.
144 */
145 @WebMethod(operationName = "getRoleIdByNamespaceCodeAndName")
146 @WebResult(name = "roleId")
147 @Cacheable(value=Role.Cache.NAME, key="'{getRoleIdByNamespaceCodeAndName}' + 'namespaceCode=' + #p0 + '|' + 'name=' + #p1")
148 String getRoleIdByNamespaceCodeAndName(@WebParam(name = "namespaceCode") String namespaceCode,
149 @WebParam(name = "name") String name) throws RiceIllegalArgumentException;
150
151 /**
152 * Checks whether the role with the given role ID is active.
153 *
154 * @param id the unique id of a role.
155 * @return true if the role with the given id is active.
156 * @throws RiceIllegalArgumentException if id is null or blank.
157 */
158 @WebMethod(operationName = "isRoleActive")
159 @WebResult(name = "isRoleActive")
160 @Cacheable(value=Role.Cache.NAME, key="'{isRoleActive}' + 'id=' + #p0")
161 boolean isRoleActive( @WebParam(name="id") String id ) throws RiceIllegalArgumentException;
162
163 /**
164 * Returns a list of role qualifiers that the given principal has without taking into consideration
165 * that the principal may be a member via an assigned group or role. Use in situations where
166 * you are only interested in the qualifiers that are directly assigned to the principal.
167 *
168 * @param principalId the principalId to
169 * @param roleIds the namespace code of the role.
170 * @param qualification the qualifications for the roleIds.
171 * @return a map of role qualifiers for the given principalId, roleIds and qualifications or an empty map if none found.
172 * @throws RiceIllegalArgumentException if principalId is null or blank or roleIds is null.
173 */
174 @WebMethod(operationName = "getRoleQualifersForPrincipalByRoleIds")
175 @XmlElementWrapper(name = "attributes", required = true)
176 @XmlElement(name = "attribute", required = false)
177 @WebResult(name = "attributes")
178 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
179 List<Map<String, String>> getRoleQualifersForPrincipalByRoleIds(@WebParam(name = "principalId") String principalId,
180 @WebParam(name = "roleIds") List<String> roleIds, @WebParam(name = "qualification") @XmlJavaTypeAdapter(
181 value = MapStringStringAdapter.class) Map<String, String> qualification)
182 throws RiceIllegalArgumentException;
183
184 /**
185 * Returns a list of role qualifiers that the given principal has without taking into consideration
186 * that the principal may be a member via an assigned group or role. Use in situations where
187 * you are only interested in the qualifiers that are directly assigned to the principal.
188 *
189 * @param principalId the principalId to
190 * @param namespaceCode the namespace code of the role.
191 * @param roleName the name of the role.
192 * @param qualification the qualifications for the roleIds.
193 * @return a map of role qualifiers for the given parameters or an empty map if none found.
194 * @throws RiceIllegalArgumentException if principalId, namespaceCode, or roleName is null or blank.
195 */
196 @WebMethod(operationName = "getRoleQualifersForPrincipalByNamespaceAndRolename")
197 @XmlElementWrapper(name = "attributes", required = true)
198 @XmlElement(name = "attribute", required = false)
199 @WebResult(name = "attributes")
200 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
201 List<Map<String, String>> getRoleQualifersForPrincipalByNamespaceAndRolename(
202 @WebParam(name = "principalId") String principalId, @WebParam(name = "namespaceCode") String namespaceCode,
203 @WebParam(name = "roleName") String roleName, @WebParam(name = "qualification") @XmlJavaTypeAdapter(
204 value = MapStringStringAdapter.class) Map<String, String> qualification)
205 throws RiceIllegalArgumentException;
206
207 /**
208 * Returns a list of role qualifiers that the given principal. If the principal's membership
209 * is via a group or role, that group or role's qualifier on the given role is returned.
210 *
211 * @param principalId the principalId to
212 * @param namespaceCode the namespace code of the role.
213 * @param roleName the name of the role.
214 * @param qualification the qualifications for the roleIds.
215 * @return a map of nested role qualifiers for the given parameters or an empty map if none found.
216 * @throws RiceIllegalArgumentException if principalId, namespaceCode, or roleName is null or blank.
217 */
218 @WebMethod(operationName = "getNestedRoleQualifersForPrincipalByNamespaceAndRolename")
219 @XmlElementWrapper(name = "attributes", required = true)
220 @XmlElement(name = "attribute", required = false)
221 @WebResult(name = "attributes")
222 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
223 List<Map<String, String>> getNestedRoleQualifersForPrincipalByNamespaceAndRolename(
224 @WebParam(name = "principalId") String principalId, @WebParam(name = "namespaceCode") String namespaceCode,
225 @WebParam(name = "roleName") String roleName, @WebParam(name = "qualification") @XmlJavaTypeAdapter(
226 value = MapStringStringAdapter.class) Map<String, String> qualification)
227 throws RiceIllegalArgumentException;
228
229 /**
230 * Returns a list of role qualifiers that the given principal. If the principal's membership
231 * is via a group or role, that group or role's qualifier on the given role is returned.
232 *
233 * @param principalId the principalId to
234 * @param roleIds the namespace code of the role.
235 * @param qualification the qualifications for the roleIds.
236 * @return a map of role qualifiers for the given roleIds and qualifications or an empty map if none found.
237 * @throws RiceIllegalArgumentException if principalId, namespaceCode, or roleName is null or blank.
238 */
239 @WebMethod(operationName = "getNestedRoleQualifiersForPrincipalByRoleIds")
240 @XmlElementWrapper(name = "attributes", required = true)
241 @XmlElement(name = "attribute", required = false)
242 @WebResult(name = "attributes")
243 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
244 List<Map<String, String>> getNestedRoleQualifiersForPrincipalByRoleIds(
245 @WebParam(name = "principalId") String principalId, @WebParam(name = "roleIds") List<String> roleIds,
246 @WebParam(name = "qualification") @XmlJavaTypeAdapter(
247 value = MapStringStringAdapter.class) Map<String, String> qualification)
248 throws RiceIllegalArgumentException;
249
250
251 // --------------------
252 // Role Membership Checks
253 // --------------------
254
255 /**
256 * Get all the role members (groups and principals) associated with the given list of roles
257 * where their role membership/assignment matches the given qualification. The list of RoleMemberships returned
258 * will only contain group and principal members. Any nested role members will be resolved and flattened into
259 * the principals and groups that are members of that nested role (assuming qualifications match).
260 *
261 * The return object will have each membership relationship along with the delegations
262 *
263 * @param roleIds a list of role Ids.
264 * @param qualification the qualifications for the roleIds.
265 * @return a list of role members for the given roleIds and qualifications or an empty list if none found.
266 * @throws RiceIllegalArgumentException if roleIds is null.
267 */
268 @WebMethod(operationName = "getRoleMembers")
269 @XmlElementWrapper(name = "roleMemberships", required = true)
270 @XmlElement(name = "roleMembership", required = false)
271 @WebResult(name = "roleMemberships")
272 @Cacheable(value= RoleMember.Cache.NAME,
273 key="'roleIds=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0) + '|' + 'qualification=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).mapKey(#p1)",
274 condition="!T(org.kuali.rice.kim.api.cache.KimCacheUtils).isDynamicRoleMembership(#p0)" )
275 List<RoleMembership> getRoleMembers(
276 @WebParam(name="roleIds")
277 List<String> roleIds,
278 @WebParam(name="qualification")
279 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
280 Map<String, String> qualification )
281 throws RiceIllegalArgumentException;
282
283 /**
284 * This method gets all the members, then traverses down into members of type role and group to obtain the nested principal ids
285 *
286 * @param namespaceCode the namespace code of the role.
287 * @param roleName the name of the role
288 * @param qualification the qualifications for the roleIds.
289 * @return a list of role member principalIds for the given roleIds and qualifications, or an empty list if none found.
290 * @throws RiceIllegalArgumentException if namespaceCode, or roleName is null or blank.
291 */
292 @WebMethod(operationName = "getRoleMemberPrincipalIds")
293 @XmlElementWrapper(name = "principalIds", required = true)
294 @XmlElement(name = "principalId", required = false)
295 @WebResult(name = "principalIds")
296 @Cacheable(value= RoleMember.Cache.NAME,
297 key="'namespaceCode=' + #p0 + '|' + 'roleName=' + #p1 + '|' + 'qualification=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).mapKey(#p2)",
298 condition="!T(org.kuali.rice.kim.api.cache.KimCacheUtils).isDynamicMembshipRoleByNamespaceAndName(#p0, #p1)" )
299 Collection<String> getRoleMemberPrincipalIds(@WebParam(name="namespaceCode") String namespaceCode,
300 @WebParam(name="roleName") String roleName,
301 @WebParam(name="qualification")
302 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
303 Map<String, String> qualification)
304 throws RiceIllegalArgumentException;
305
306 /**
307 * Returns whether the given principal has any of the passed role IDs with the given qualification.
308 *
309 * @param principalId the principal Id to check.
310 * @param roleIds the list of role ids.
311 * @param qualification the qualifications for the roleIds.
312 * @return true if the principal is assigned the one of the given roleIds with the passed in qualifications.
313 * @throws RiceIllegalArgumentException if roleIds is null or principalId is null or blank.
314 */
315 @WebMethod(operationName = "principalHasRole")
316 @WebResult(name = "principalHasRole")
317 boolean principalHasRole( @WebParam(name="principalId") String principalId,
318 @WebParam(name="roleIds") List<String> roleIds,
319 @WebParam(name="qualification") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualification )
320 throws RiceIllegalArgumentException;
321
322 /**
323 * Returns whether the given principal has any of the passed role IDs with the given qualification.
324 *
325 * @param principalId the principal Id to check.
326 * @param roleIds the list of role ids.
327 * @param qualification the qualifications for the roleIds.
328 * @param checkDelegations whether delegations should be checked or not
329 * @return true if the principal is assigned the one of the given roleIds with the passed in qualifications.
330 * @throws RiceIllegalArgumentException if roleIds is null or principalId is null or blank.
331 * @since 2.1.1
332 */
333 @WebMethod(operationName = "principalHasRoleCheckDelegation")
334 @WebResult(name = "principalHasRoleCheckDelegation")
335 boolean principalHasRole( @WebParam(name="principalId") String principalId,
336 @WebParam(name="roleIds") List<String> roleIds,
337 @WebParam(name="qualification") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualification, boolean checkDelegations)
338 throws RiceIllegalArgumentException;
339
340 /**
341 * Returns the subset of the given principal ID list which has the given role and qualification.
342 * This is designed to be used by lookups of people by their roles.
343 *
344 * @param principalIds the principal Ids to check.
345 * @param roleNamespaceCode the namespaceCode of the role.
346 * @param roleName the name of the role.
347 * @param qualification the qualifications for the roleIds.
348 * @return list of principalIds that is the subset of list passed in with the given role and qualifications or an empty list.
349 * @throws RiceIllegalArgumentException if principalIds is null or the roleNamespaceCode or roleName is null or blank.
350 */
351 @WebMethod(operationName = "getPrincipalIdSubListWithRole")
352 @XmlElementWrapper(name = "principalIds", required = true)
353 @XmlElement(name = "principalId", required = false)
354 @WebResult(name = "principalIds")
355 @Cacheable(value= RoleMember.Cache.NAME,
356 key="'getPrincipalIdSubListWithRole' + 'principalIds=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0) + '|' + 'roleNamespaceCode=' + #p1 + '|' + 'roleName=' + #p2 + '|' + 'qualification=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).mapKey(#p3)",
357 condition="!T(org.kuali.rice.kim.api.cache.KimCacheUtils).isDynamicMembshipRoleByNamespaceAndName(#p1, #p2)" )
358 List<String> getPrincipalIdSubListWithRole( @WebParam(name="principalIds") List<String> principalIds,
359 @WebParam(name="roleNamespaceCode") String roleNamespaceCode,
360 @WebParam(name="roleName") String roleName,
361 @WebParam(name="qualification") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualification )
362 throws RiceIllegalArgumentException;
363
364 /**
365 *
366 * This method gets search results for role lookup
367 *
368 * @param queryByCriteria the qualifications for the roleIds.
369 * @return query results. will never return null.
370 * @throws RiceIllegalArgumentException if queryByCriteria is null.
371 */
372 @WebMethod(operationName = "getRolesSearchResults")
373 @WebResult(name = "results")
374 RoleQueryResults findRoles(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
375
376
377
378 /**
379 * Gets all direct members of the roles that have ids within the given list
380 * of role ids. This method does not recurse into any nested roles.
381 *
382 * <p>The resulting List of role membership will contain membership for
383 * all the roles with the specified ids. The list is not guaranteed to be
384 * in any particular order and may have membership info for the
385 * different roles interleaved with each other.
386 *
387 * @param roleIds a list of role Ids.
388 * @return list of RoleMembership that contains membership for the specified roleIds or empty list if none found.
389 * @throws RiceIllegalArgumentException if roleIds is null.
390 */
391 @WebMethod(operationName = "getFirstLevelRoleMembers")
392 @XmlElementWrapper(name = "roleMemberships", required = true)
393 @XmlElement(name = "roleMembership", required = false)
394 @WebResult(name = "roleMemberships")
395 @Cacheable(value=RoleMembership.Cache.NAME, key="'roleIds=' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0)")
396 List<RoleMembership> getFirstLevelRoleMembers(
397 @WebParam(name="roleIds") List<String> roleIds) throws RiceIllegalArgumentException;
398
399 /**
400 * Gets role member information based on the given search criteria.
401 *
402 * @param queryByCriteria the qualifications for the roleIds.
403 * @return query results. will never return null.
404 * @throws RiceIllegalArgumentException if queryByCriteria is null.
405 */
406 @WebMethod(operationName = "findRoleMemberships")
407 @WebResult(name = "results")
408 RoleMembershipQueryResults findRoleMemberships(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
409
410 /**
411 * Gets a list of Roles that the given member belongs to.
412 *
413 * @param memberType the role member type.
414 * @param memberId the role member id (principalId, roleId, groupId).
415 * @return list of RoleMembership that contains membership for the specified roleIds or an empty list if none found.
416 * @throws RiceIllegalArgumentException if memberType or memberId is null or blank.
417 */
418 @WebMethod(operationName = "getMemberParentRoleIds")
419 @XmlElementWrapper(name = "roleIds", required = true)
420 @XmlElement(name = "roleId", required = false)
421 @WebResult(name = "roleIds")
422 @Cacheable(value=RoleMembership.Cache.NAME, key="'memberType=' + #p0 + '|' + 'memberId=' + #p1")
423 List<String> getMemberParentRoleIds(String memberType, String memberId) throws RiceIllegalArgumentException;
424
425
426 /**
427 * Gets role members based on the given search criteria.
428 *
429 * @param queryByCriteria the qualifications for the roleIds.
430 * @return query results. will never return null.
431 * @throws RiceIllegalArgumentException if queryByCriteria is null.
432 */
433 @WebMethod(operationName = "findRoleMembers")
434 @WebResult(name = "results")
435 RoleMemberQueryResults findRoleMembers(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
436
437
438 /**
439 * Gets a list of Roles Ids that are a member of the given roleId, including nested membership.
440 *
441 * @param roleId the role id.
442 * @return list of RoleIds that are members of the given role or and empty list if none found.
443 * @throws RiceIllegalArgumentException if roleId is null or blank.
444 */
445 @WebMethod(operationName = "getRoleTypeRoleMemberIds")
446 @XmlElementWrapper(name = "memberIds", required = true)
447 @XmlElement(name = "memberId", required = false)
448 @WebResult(name = "memberIds")
449 @Cacheable(value=RoleMember.Cache.NAME, key="'{getRoleTypeRoleMemberIds}' + 'roleId=' + #p0")
450 Set<String> getRoleTypeRoleMemberIds(@WebParam(name = "roleId") String roleId) throws RiceIllegalArgumentException;
451
452
453 /**
454 * Gets role members based on the given search criteria.
455 *
456 * @param queryByCriteria the qualifications for the roleIds.
457 * @return query results. will never return null.
458 * @throws RiceIllegalArgumentException if queryByCriteria is null.
459 */
460 @WebMethod(operationName = "findDelegateMembers")
461 @WebResult(name = "results")
462 DelegateMemberQueryResults findDelegateMembers(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
463
464 /**
465 * Gets the delegate members for the given delegation.
466 *
467 * @param delegateId the delegate id.
468 * @return list of delegate members that are members of the given delegation or an empty list if none found.
469 * @throws RiceIllegalArgumentException if delegationId is null or blank.
470 */
471 @WebMethod(operationName = "getDelegationMembersByDelegationId")
472 @XmlElementWrapper(name = "delegateMembers", required = true)
473 @XmlElement(name = "delegateMember", required = false)
474 @WebResult(name = "delegateMembers")
475 @Cacheable(value=DelegateMember.Cache.NAME, key="'delegateId=' + #p0")
476 List<DelegateMember> getDelegationMembersByDelegationId(
477 @WebParam(name = "delegateId") String delegateId) throws RiceIllegalArgumentException;
478
479
480 /**
481 * Gets the delegate member for the given delegationId and memberId.
482 *
483 * @param delegationId the delegate id.
484 * @param memberId the member id matching the DelegateMember
485 * @return the delegate member with the given parameters or null if not found.
486 * @throws RiceIllegalArgumentException if delegationId or memberId is null or blank.
487 */
488 @WebMethod(operationName = "getDelegationMemberByDelegationAndMemberId")
489 @WebResult(name = "delegateMember")
490 @Cacheable(value=DelegateMember.Cache.NAME, key="'delegationId=' + #p0 + '|' + 'memberId=' + #p1")
491 DelegateMember getDelegationMemberByDelegationAndMemberId(
492 @WebParam(name = "delegationId") String delegationId, @WebParam(name = "memberId") String memberId) throws RiceIllegalArgumentException;
493
494
495 /**
496 * Gets the delegate member with the given delegation member id.
497 *
498 * @param id the member id matching the DelegateMember
499 * @return the delegate member with the given parameters or null if not found.
500 * @throws RiceIllegalArgumentException if delegationId or memberId is null or blank.
501 */
502 @WebMethod(operationName = "getDelegationMemberById")
503 @WebResult(name = "delegateMember")
504 @Cacheable(value=DelegateMember.Cache.NAME, key="'id=' + #p0")
505 DelegateMember getDelegationMemberById(@WebParam(name = "id") String id) throws RiceIllegalArgumentException;
506
507
508 /**
509 * Gets a list of role reponsibilities for the given role id.
510 *
511 * @param roleId the role Id.
512 * @return a list of RoleResponsibilities for the given role Id, or an empty list if none found.
513 * @throws RiceIllegalArgumentException if roleId is null or blank.
514 */
515 @WebMethod(operationName = "getRoleResponsibilities")
516 @XmlElementWrapper(name = "roleResponsibilities", required = true)
517 @XmlElement(name = "roleResponsibility", required = false)
518 @WebResult(name = "roleResponsibilities")
519 @Cacheable(value=RoleResponsibility.Cache.NAME, key="'roleId=' + #p0")
520 List<RoleResponsibility> getRoleResponsibilities(@WebParam(name="roleId") String roleId) throws RiceIllegalArgumentException;
521
522
523 /**
524 * Gets a list of RoleResponsibilityActions for the given role member id.
525 *
526 * @param roleMemberId the role member Id.
527 * @return a list of RoleResponsibilityActions for the given role member Id, or an empty list if none found.
528 * @throws RiceIllegalArgumentException if roleMemberId is null or blank.
529 */
530 @WebMethod(operationName = "getRoleMemberResponsibilityActions")
531 @XmlElementWrapper(name = "roleResponsibilityActions", required = true)
532 @XmlElement(name = "roleResponsibilityAction", required = false)
533 @WebResult(name = "roleResponsibilityActions")
534 @Cacheable(value=RoleResponsibility.Cache.NAME, key="'roleMemberId=' + #p0")
535 List<RoleResponsibilityAction> getRoleMemberResponsibilityActions(
536 @WebParam(name = "roleMemberId") String roleMemberId) throws RiceIllegalArgumentException;
537
538
539 /**
540 * Gets a DelegateType for the given role id and delegation type.
541 *
542 * @param roleId the role Id.
543 * @param delegateType type of delegation
544 * @return the DelegateType for the given role Id and delegationType, or null if none found.
545 * @throws RiceIllegalArgumentException if roleId or delegationType is null or blank.
546 */
547 @WebMethod(operationName = "getDelegateTypeByRoleIdAndDelegateTypeCode")
548 @WebResult(name = "delegateType")
549 @Cacheable(value=DelegateType.Cache.NAME, key="'roleId=' + #p0 + '|' + 'delegateType=' + #p1")
550 DelegateType getDelegateTypeByRoleIdAndDelegateTypeCode(@WebParam(name = "roleId") String roleId,
551 @WebParam(name = "delegateType") DelegationType delegateType) throws RiceIllegalArgumentException;
552
553
554 /**
555 * Gets a DelegateType for the given delegation id.
556 *
557 * @param delegationId the id of delegation
558 * @return the DelegateType for the given delegation Id, or null if none found.
559 * @throws RiceIllegalArgumentException if delegationId is null or blank.
560 */
561 @WebMethod(operationName = "getDelegateTypeByDelegationId")
562 @WebResult(name = "delegateType")
563 @Cacheable(value=DelegateType.Cache.NAME, key="'delegationId=' + #p0")
564 DelegateType getDelegateTypeByDelegationId(@WebParam(name = "delegationId") String delegationId) throws RiceIllegalArgumentException;
565
566 /**
567 * Assigns the principal with the given id to the role with the specified
568 * namespace code and name with the supplied set of qualifications.
569 *
570 * @param principalId the principalId
571 * @param namespaceCode the namespaceCode of the Role
572 * @param roleName the name of the role
573 * @param qualifications the qualifications for the principalId to be assigned to the role
574 * @return newly created/assigned RoleMember.
575 * @throws RiceIllegalArgumentException if princialId, namespaceCode or roleName is null or blank.
576 */
577 @WebMethod(operationName = "assignPrincipalToRole")
578 @WebResult(name = "roleMember")
579 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
580 RoleMember assignPrincipalToRole(@WebParam(name="principalId") String principalId,
581 @WebParam(name="namespaceCode")
582 String namespaceCode,
583 @WebParam(name="roleName")
584 String roleName,
585 @WebParam(name="qualifications")
586 @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)
587 Map<String, String> qualifications)
588 throws RiceIllegalArgumentException;
589
590 /**
591 * Assigns the group with the given id to the role with the specified
592 * namespace code and name with the supplied set of qualifications.
593 *
594 * @param groupId the groupId
595 * @param namespaceCode the namespaceCode of the Role
596 * @param roleName the name of the role
597 * @param qualifications the qualifications for the principalId to be assigned to the role
598 * @return newly created/assigned RoleMember.
599 * @throws RiceIllegalArgumentException if groupId, namespaceCode or roleName is null or blank.
600 */
601 @WebMethod(operationName = "assignGroupToRole")
602 @WebResult(name = "roleMember")
603 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
604 RoleMember assignGroupToRole(@WebParam(name="groupId") String groupId,
605 @WebParam(name="namespaceCode") String namespaceCode,
606 @WebParam(name="roleName") String roleName,
607 @WebParam(name="qualifications") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualifications)
608 throws RiceIllegalArgumentException;
609
610 /**
611 * Assigns the role with the given id to the role with the specified
612 * namespace code and name with the supplied set of qualifications.
613 *
614 * @param roleId the roleId
615 * @param namespaceCode the namespaceCode of the Role
616 * @param roleName the name of the role
617 * @param qualifications the qualifications for the principalId to be assigned to the role
618 * @return newly created/assigned RoleMember.
619 * @throws RiceIllegalArgumentException if princiapId, namespaceCode or roleName is null or blank.
620 */
621 @WebMethod(operationName = "assignRoleToRole")
622 @WebResult(name = "roleMember")
623 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
624 RoleMember assignRoleToRole(@WebParam(name="roleId") String roleId,
625 @WebParam(name="namespaceCode") String namespaceCode,
626 @WebParam(name="roleName") String roleName,
627 @WebParam(name="qualifications") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualifications)
628 throws RiceIllegalArgumentException;
629
630 /**
631 * Creates a new RoleMember. Needs to be passed a valid RoleMember object that does not currently exist.
632 *
633 * @param roleMember the new RoleMember to save.
634 * @return RoleMember as created.
635 * @throws RiceIllegalArgumentException if roleMember is null.
636 * @throws RiceIllegalStateException if roleMember already exists.
637 */
638 @WebMethod(operationName = "createRoleMember")
639 @WebResult(name = "roleMember")
640 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
641 RoleMember createRoleMember(
642 @WebParam(name = "roleMember")
643 RoleMember roleMember) throws RiceIllegalArgumentException, RiceIllegalStateException;
644
645 /**
646 * Updates the given roleMember to the values in the passed in roleMember
647 *
648 * @param roleMember the new RoleMember to save.
649 * @return RoleMember as updated.
650 * @throws RiceIllegalArgumentException if roleMember is null.
651 * @throws RiceIllegalStateException if roleMember does not yet exist.
652 */
653 @WebMethod(operationName = "updateRoleMember")
654 @WebResult(name = "roleMember")
655 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
656 RoleMember updateRoleMember(@WebParam(name = "roleMember") RoleMember roleMember) throws RiceIllegalArgumentException, RiceIllegalStateException;
657
658 /**
659 * Updates the given delegateMember to the values in the passed in delegateMember
660 *
661 * @param delegateMember the new DelegateMember to save.
662 * @return DelegateMember as updated.
663 * @throws RiceIllegalArgumentException if delegateMember is null.
664 * @throws RiceIllegalStateException if delegateMember does not yet exist.
665 */
666 @WebMethod(operationName = "updateDelegateMember")
667 @WebResult(name = "delegateMember")
668 @CacheEvict(value={Role.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
669 DelegateMember updateDelegateMember(@WebParam(name = "delegateMember") DelegateMember delegateMember) throws RiceIllegalArgumentException, RiceIllegalStateException;
670
671 /**
672 * Creates a new DelegateMember. Needs to be passed a valid DelegateMember object that does not currently exist.
673 *
674 * @param delegateMember the new DelegateMember to save.
675 * @return DelegateMember as created.
676 * @throws RiceIllegalArgumentException if delegateMember is null.
677 * @throws RiceIllegalStateException if delegateMember already exists.
678 */
679 @WebMethod(operationName = "createDelegateMember")
680 @WebResult(name = "delegateMember")
681 @CacheEvict(value={Role.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
682 DelegateMember createDelegateMember(
683 @WebParam(name = "delegateMember")
684 DelegateMember delegateMember) throws RiceIllegalArgumentException, RiceIllegalStateException;
685
686 /**
687 * Removes existing DelegateMembers. Needs to be passed DelegateMember objects.
688 *
689 * @param DelegateMembers to remove.
690 * @throws RiceIllegalArgumentException if delegateMember is null.
691 */
692 @WebMethod(operationName = "removeDelegateMembers")
693 @CacheEvict(value={Role.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
694 void removeDelegateMembers(
695 @WebParam(name = "delegateMembers")
696 List<DelegateMember> delegateMembers) throws RiceIllegalArgumentException, RiceIllegalStateException;
697
698 /**
699 * Creates a new RoleResponsibilityAction. Needs to be passed a valid RoleResponsibilityAction
700 * object that does not currently exist.
701 *
702 * @param roleResponsibilityAction the new RoleResponsibilityAction to save.
703 * @return RoleResponsibilityAction as created.
704 * @throws RiceIllegalArgumentException if roleResponsibilityAction is null.
705 * @throws RiceIllegalStateException if roleResponsibilityAction already exists.
706 */
707 @WebMethod(operationName = "createRoleResponsibilityAction")
708 @CacheEvict(value={Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
709 RoleResponsibilityAction createRoleResponsibilityAction(@WebParam(name = "roleResponsibilityAction") RoleResponsibilityAction roleResponsibilityAction) throws RiceIllegalArgumentException;
710
711 /**
712 * Updates the given RoleResponsibilityAction to the values in the passed in roleResponsibilityAction
713 *
714 * @since 2.1.2
715 * @param roleResponsibilityAction the new RoleResponsibilityAction to save.
716 * @return RoleResponsibilityAction as updated.
717 * @throws RiceIllegalArgumentException if roleResponsibilityAction is null.
718 * @throws RiceIllegalStateException if roleResponsibilityAction does not exist.
719 */
720 @WebMethod(operationName = "updateRoleResponsibilityAction")
721 @CacheEvict(value={Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
722 RoleResponsibilityAction updateRoleResponsibilityAction(@WebParam(name = "roleResponsibilityAction") RoleResponsibilityAction roleResponsibilityAction) throws RiceIllegalArgumentException;
723
724 /**
725 * Deletes the given RoleResponsibilityAction
726 *
727 * @since 2.1.2
728 * @param roleResponsibilityActionId id of the RoleResponsibilityAction to delete.
729 * @throws RiceIllegalArgumentException if roleResponsibilityActionId is null.
730 * @throws RiceIllegalStateException if roleResponsibilityAction does not exist.
731 */
732 @WebMethod(operationName = "deleteRoleResponsibilityAction")
733 @CacheEvict(value={Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
734 void deleteRoleResponsibilityAction(@WebParam(name = "roleResponsibilityActionId") String roleResponsibilityActionId) throws RiceIllegalArgumentException;
735
736 /**
737 * Creates a new DelegateType. Needs to be passed a valid DelegateType
738 * object that does not currently exist.
739 *
740 * @param delegateType the new DelegateType to save.
741 * @return DelegateType as created.
742 * @throws RiceIllegalArgumentException if delegateType is null.
743 * @throws RiceIllegalStateException if delegateType already exists.
744 */
745 @WebMethod(operationName = "createDelegateType")
746 @CacheEvict(value={Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
747 DelegateType createDelegateType(@WebParam(name="delegateType") DelegateType delegateType) throws RiceIllegalArgumentException, RiceIllegalStateException;
748
749 /**
750 * Updates the given DelegateType to the values in the passed in delegateType
751 *
752 * @param delegateType the new DelegateType to save.
753 * @return DelegateType as updated.
754 * @throws RiceIllegalArgumentException if delegateType is null.
755 * @throws RiceIllegalStateException if delegateType does not yet exist.
756 */
757 @WebMethod(operationName = "updateDelegateType")
758 @CacheEvict(value={Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
759 DelegateType updateDelegateType(@WebParam(name="delegateType") DelegateType delegateType) throws RiceIllegalArgumentException, RiceIllegalStateException;
760
761 /**
762 * Remove the principal with the given id and qualifications from the role
763 * with the specified namespace code and role name.
764 *
765 * @param principalId the principalId
766 * @param namespaceCode the namespaceCode of the Role
767 * @param roleName the name of the role
768 * @param qualifications the qualifications for the principalId to be assigned to the role
769 * @return void.
770 * @throws RiceIllegalArgumentException if principalId, namespaceCode or roleName is null or blank.
771 */
772 @WebMethod(operationName = "removePrincipalFromRole")
773 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
774 void removePrincipalFromRole(@WebParam(name="principalId") String principalId,
775 @WebParam(name="namespaceCode") String namespaceCode,
776 @WebParam(name="roleName") String roleName,
777 @WebParam(name="qualifications") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualifications) throws RiceIllegalArgumentException;
778
779 /**
780 * Remove the group with the given id and qualifications from the role
781 * with the specified namespace code and role name.
782 *
783 * @param groupId the groupId
784 * @param namespaceCode the namespaceCode of the Role
785 * @param roleName the name of the role
786 * @param qualifications the qualifications for the principalId to be assigned to the role
787 * @return void.
788 * @throws RiceIllegalArgumentException if groupId, namespaceCode or roleName is null or blank.
789 */
790 @WebMethod(operationName = "removeGroupFromRole")
791 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
792 void removeGroupFromRole(@WebParam(name="groupId") String groupId,
793 @WebParam(name="namespaceCode") String namespaceCode,
794 @WebParam(name="roleName") String roleName,
795 @WebParam(name="qualifications") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualifications) throws RiceIllegalArgumentException;
796
797 /**
798 * Remove the group with the given id and qualifications from the role
799 * with the specified namespace code and role name.
800 *
801 * @param roleId the roleId
802 * @param namespaceCode the namespaceCode of the Role
803 * @param roleName the name of the role
804 * @param qualifications the qualifications for the principalId to be assigned to the role
805 * @return void.
806 * @throws RiceIllegalArgumentException if roleId, namespaceCode or roleName is null or blank.
807 */
808 @WebMethod(operationName = "removeRoleFromRole")
809 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
810 void removeRoleFromRole(@WebParam(name="roleId") String roleId,
811 @WebParam(name="namespaceCode") String namespaceCode,
812 @WebParam(name="roleName") String roleName,
813 @WebParam(name="qualifications") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String, String> qualifications) throws RiceIllegalArgumentException;
814
815 /**
816 * Assigns the given permission to the given role
817 *
818 * @param permissionId the permissionId
819 * @param roleId the roleId
820 * @return void.
821 * @throws RiceIllegalArgumentException if permissionId or roleId is null or blank.
822 */
823 @WebMethod(operationName = "assignPermissionToRole")
824 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
825 void assignPermissionToRole(
826 @WebParam(name = "permissionId") String permissionId,
827 @WebParam(name = "roleId") String roleId)
828 throws RiceIllegalArgumentException;
829
830 /**
831 * Removes the given permission to the given role
832 *
833 * @param permissionId the permissionId
834 * @param roleId the roleId
835 * @return void.
836 * @throws RiceIllegalArgumentException if permissionId or roleId is null or blank.
837 */
838 @WebMethod(operationName = "revokePermissionFromRole")
839 @CacheEvict(value={Role.Cache.NAME, Permission.Cache.NAME, Responsibility.Cache.NAME, RoleMembership.Cache.NAME, RoleMember.Cache.NAME, DelegateMember.Cache.NAME, RoleResponsibility.Cache.NAME, DelegateType.Cache.NAME }, allEntries = true)
840 void revokePermissionFromRole(
841 @WebParam(name = "permissionId") String permissionId,
842 @WebParam(name = "roleId") String roleId)
843 throws RiceIllegalArgumentException;
844
845
846 /**
847 * Determines if a role with a provided id is a derived role
848 *
849 * @since 2.1.1
850 * @param roleId the roleId
851 * @return true if role is a derived role
852 * @throws RiceIllegalArgumentException if roleId is null or blank.
853 */
854 @WebMethod(operationName = "isDerivedRole")
855 @WebResult(name = "isDerivedRole")
856 @Cacheable(value= Role.Cache.NAME, key="'{isDerivedRole}' + 'roleId=' + #p0")
857 boolean isDerivedRole(@WebParam(name = "roleId") String roleId) throws RiceIllegalArgumentException;
858
859 /**
860 * Determines if a role with a provided id is a uses dynamic role memberships
861 *
862 * @since 2.1.1
863 * @param roleId the roleId
864 * @return true if role uses dynamic memberships
865 * @throws RiceIllegalArgumentException if roleId is null or blank.
866 */
867 @WebMethod(operationName = "isDynamicRoleMembership")
868 @WebResult(name = "isDynamicRoleMembership")
869 @Cacheable(value= Role.Cache.NAME, key="'{isDynamicRoleMembership}' + 'roleId=' + #p0")
870 boolean isDynamicRoleMembership(@WebParam(name = "roleId") String roleId) throws RiceIllegalArgumentException;
871 }