001package org.kuali.rice.kim.api.identity;
002
003import org.kuali.rice.core.api.criteria.QueryByCriteria;
004import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
005import org.kuali.rice.core.api.exception.RiceIllegalStateException;
006import org.kuali.rice.kim.api.KimConstants;
007import org.kuali.rice.kim.api.identity.address.EntityAddress;
008import org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation;
009import org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType;
010import org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship;
011import org.kuali.rice.kim.api.identity.email.EntityEmail;
012import org.kuali.rice.kim.api.identity.employment.EntityEmployment;
013import org.kuali.rice.kim.api.identity.entity.Entity;
014import org.kuali.rice.kim.api.identity.entity.EntityDefault;
015import org.kuali.rice.kim.api.identity.entity.EntityDefaultQueryResults;
016import org.kuali.rice.kim.api.identity.entity.EntityQueryResults;
017import org.kuali.rice.kim.api.identity.external.EntityExternalIdentifier;
018import org.kuali.rice.kim.api.identity.external.EntityExternalIdentifierType;
019import org.kuali.rice.kim.api.identity.name.EntityName;
020import org.kuali.rice.kim.api.identity.personal.EntityBioDemographics;
021import org.kuali.rice.kim.api.identity.personal.EntityEthnicity;
022import org.kuali.rice.kim.api.identity.phone.EntityPhone;
023import org.kuali.rice.kim.api.identity.principal.EntityNamePrincipalName;
024import org.kuali.rice.kim.api.identity.principal.Principal;
025import org.kuali.rice.kim.api.identity.principal.PrincipalQueryResults;
026import org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences;
027import org.kuali.rice.kim.api.identity.residency.EntityResidency;
028import org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo;
029import org.kuali.rice.kim.api.identity.visa.EntityVisa;
030import org.springframework.cache.annotation.CacheEvict;
031import org.springframework.cache.annotation.Cacheable;
032
033import javax.jws.WebMethod;
034import javax.jws.WebParam;
035import javax.jws.WebResult;
036import javax.jws.WebService;
037import javax.jws.soap.SOAPBinding;
038import java.util.List;
039
040/**
041 * Created by sheiksalahudeenm on 5/5/15.
042 */
043
044@WebService(name = "identityService", targetNamespace = KimConstants.Namespaces.KIM_NAMESPACE_2_0)
045@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
046public interface IdentityService {
047
048    /**
049     * This method finds EntityDefault data based on a query criteria.  The criteria cannot be null.
050     *
051     * @param query the criteria.  Cannot be null.
052     * @return query results.  will never return null.
053     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if the queryByCriteria is null
054     */
055    @WebMethod(operationName = "findEntityDefaults")
056    @WebResult(name = "results")
057    EntityDefaultQueryResults findEntityDefaults(@WebParam(name = "query") QueryByCriteria query)  throws RiceIllegalArgumentException;
058
059    /**
060     * This method finds Entities based on a query criteria.  The criteria cannot be null.
061     *
062     * @param query the criteria.  Cannot be null.
063     * @return query results.  will never return null.
064     * @throws RiceIllegalArgumentException if the queryByCriteria is null
065     */
066    @WebMethod(operationName = "findEntities")
067    @WebResult(name = "results")
068    EntityQueryResults findEntities(@WebParam(name = "query") QueryByCriteria query)  throws RiceIllegalArgumentException;
069
070
071    /**
072     * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from an id.
073     *
074     * <p>
075     *   This method will return null if the Entity does not exist.
076     * </p>
077     *
078     * @param id the unique id to retrieve the entity by. cannot be null.
079     * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
080     * @throws RiceIllegalArgumentException if the id is blank
081     */
082    @WebMethod(operationName = "getEntity")
083    @WebResult(name = "entity")
084    //@Cacheable(value= Entity.Cache.NAME, key="'id=' + #p0")
085    Entity getEntity( @WebParam(name="id") String id )  throws RiceIllegalArgumentException;
086
087    /**
088     * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from a principalId.
089     *
090     * <p>
091     *   This method will return null if the Entity does not exist.
092     * </p>
093     *
094     * @param principalId the unique id to retrieve the entity by. cannot be null.
095     * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
096     * @throws RiceIllegalArgumentException if the principalId is blank
097     */
098    @WebMethod(operationName = "getEntityByPrincipalId")
099    @WebResult(name = "entity")
100    @Cacheable(value= Entity.Cache.NAME, key="'principalId=' + #p0")
101    Entity getEntityByPrincipalId(@WebParam(name = "principalId") String principalId)  throws RiceIllegalArgumentException;
102
103    /**
104     * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from a principalName.
105     *
106     * <p>
107     *   This method will return null if the Entity does not exist.
108     * </p>
109     *
110     * @param principalName the unique id to retrieve the entity by. cannot be null.
111     * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
112     * @throws RiceIllegalArgumentException if the id is blank
113     */
114    @WebMethod(operationName = "getEntityByPrincipalName")
115    @WebResult(name = "entity")
116    @Cacheable(value= Entity.Cache.NAME, key="'principalName=' + #p0")
117    Entity getEntityByPrincipalName(@WebParam(name = "principalName") String principalName)  throws RiceIllegalArgumentException;
118
119    /**
120     * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from a employeeId.
121     *
122     * <p>
123     *   This method will return null if the Entity does not exist.
124     * </p>
125     *
126     * @param employeeId the unique id to retrieve the entity by. cannot be null.
127     * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
128     * @throws RiceIllegalArgumentException if the employeeId is blank
129     */
130    @WebMethod(operationName = "getEntityByEmployeeId")
131    @WebResult(name = "entity")
132    @Cacheable(value= Entity.Cache.NAME, key="'employeeId=' + #p0")
133    Entity getEntityByEmployeeId(@WebParam(name = "employeeId") String employeeId)  throws RiceIllegalArgumentException;
134
135
136    /**
137     * This will create a {@link org.kuali.rice.kim.api.identity.entity.Entity} exactly like the entity passed in.
138     *
139     * @param entity the entity to create
140     * @return the newly created Entity object.
141     * @throws RiceIllegalArgumentException if the entity is null
142     * @throws org.kuali.rice.core.api.exception.RiceIllegalStateException if the entity already exists in the system
143     */
144    @WebMethod(operationName="createEntity")
145    @WebResult(name = "entity")
146    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
147    Entity createEntity(@WebParam(name = "entity") Entity entity)
148            throws RiceIllegalArgumentException, RiceIllegalStateException;
149
150    /**
151     * This will update a {@link org.kuali.rice.kim.api.identity.entity.Entity}.
152     *
153     * @param entity the entity to update
154     * @return the updated Entity object.
155     * @throws RiceIllegalArgumentException if the entity is null
156     * @throws RiceIllegalStateException if the entity does not already exist in the system
157     */
158    @WebMethod(operationName="updateEntity")
159    @WebResult(name = "entity")
160    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
161    Entity updateEntity(@WebParam(name = "entity") Entity entity)
162            throws RiceIllegalArgumentException, RiceIllegalStateException;
163
164    /**
165     * This will inactivate a {@link org.kuali.rice.kim.api.identity.entity.Entity}.
166     *
167     * @param id the unique id of the entity to inactivate
168     * @return the inactivated Entity object.
169     * @throws RiceIllegalArgumentException if the entity is null
170     * @throws RiceIllegalStateException if the entity does not already exist in the system
171     */
172    @WebMethod(operationName="inactivateEntity")
173    @WebResult(name = "entity")
174    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
175    Entity inactivateEntity(@WebParam(name = "id") String id)
176            throws RiceIllegalArgumentException, RiceIllegalStateException;
177
178
179
180    /**
181     * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an id.
182     * {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} is a condensed version of {@link org.kuali.rice.kim.api.identity.entity.Entity} that contains
183     * default values of its subclasses
184     *
185     * <p>
186     *   This method will return null if the Entity does not exist.
187     * </p>
188     *
189     * @param id the unique id to retrieve the entity by. cannot be null.
190     * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
191     * @throws RiceIllegalArgumentException if the id is blank
192     */
193    @WebMethod(operationName = "getEntityDefault")
194    @WebResult(name = "entityDefault")
195    @Cacheable(value= EntityDefault.Cache.NAME, key="'id=' + #p0")
196    EntityDefault getEntityDefault(@WebParam(name = "id") String id)  throws RiceIllegalArgumentException;
197
198    /**
199     * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an principalId.
200     * {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} is a condensed version of {@link org.kuali.rice.kim.api.identity.entity.Entity} that contains
201     * default values of its subclasses
202     *
203     * <p>
204     *   This method will return null if the Entity does not exist.
205     * </p>
206     *
207     * @param principalId the unique id to retrieve the entity by. cannot be null.
208     * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
209     * @throws RiceIllegalArgumentException if the principalId is blank
210     */
211    @WebMethod(operationName = "getEntityDefaultByPrincipalId")
212    @WebResult(name = "entityDefault")
213    @Cacheable(value= EntityDefault.Cache.NAME, key="'principalId=' + #p0")
214    EntityDefault getEntityDefaultByPrincipalId(@WebParam(name = "principalId") String principalId)  throws RiceIllegalArgumentException;
215
216    /**
217     * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an principalName.
218     * {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} is a condensed version of {@link org.kuali.rice.kim.api.identity.entity.Entity} that contains
219     * default values of its subclasses
220     *
221     * <p>
222     *   This method will return null if the Entity does not exist.
223     * </p>
224     *
225     * @param principalName the unique id to retrieve the entity by. cannot be null.
226     * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
227     * @throws RiceIllegalArgumentException if the principalId is blank
228     */
229    @WebMethod(operationName = "getEntityDefaultByPrincipalName")
230    @WebResult(name = "entityDefault")
231    @Cacheable(value= EntityDefault.Cache.NAME, key="'principalName=' + #p0")
232    EntityDefault getEntityDefaultByPrincipalName(@WebParam(name = "principalName") String principalName)  throws RiceIllegalArgumentException;
233
234    /**
235     * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an employeeId.
236     * {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} is a condensed version of {@link org.kuali.rice.kim.api.identity.entity.Entity} that contains
237     * default values of its subclasses
238     *
239     * <p>
240     *   This method will return null if the Entity does not exist.
241     * </p>
242     *
243     * @param employeeId the unique id to retrieve the entity by. cannot be null.
244     * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
245     * @throws RiceIllegalArgumentException if the employeeId is blank
246     */
247    @WebMethod(operationName = "getEntityDefaultByEmployeeId")
248    @WebResult(name = "entityDefault")
249    @Cacheable(value= EntityDefault.Cache.NAME, key="'employeeId=' + #p0")
250    EntityDefault getEntityDefaultByEmployeeId(@WebParam(name = "employeeId") String employeeId)  throws RiceIllegalArgumentException;
251
252
253    /**
254     * Gets a {@link org.kuali.rice.kim.api.identity.principal.Principal} from an principalId.
255     *
256     * <p>
257     *   This method will return null if the Principal does not exist.
258     * </p>
259     *
260     * @param principalId the unique id to retrieve the principal by. cannot be null.
261     * @return a {@link org.kuali.rice.kim.api.identity.principal.Principal} or null
262     * @throws RiceIllegalArgumentException if the principalId is blank
263     */
264    @WebMethod(operationName = "getPrincipal")
265    @WebResult(name = "principal")
266    @Cacheable(value= Principal.Cache.NAME, key="'principalId=' + #p0")
267    Principal getPrincipal( @WebParam(name="principalId") String principalId )  throws RiceIllegalArgumentException;
268
269
270    /**
271     * Gets a list of {@link org.kuali.rice.kim.api.identity.principal.Principal} from a string list of principalId.
272     *
273     * <p>
274     *   This method will only return principals that exist.
275     * </p>
276     *
277     * @param principalIds the unique id to retrieve the principal by. cannot be null.
278     * @return a list of {@link org.kuali.rice.kim.api.identity.principal.Principal}
279     * @throws RiceIllegalArgumentException if the principalId is blank
280     */
281    @WebMethod(operationName = "getPrincipals")
282    @WebResult(name = "ret")
283    List<Principal> getPrincipals( @WebParam(name="principalIds") List<String> principalIds)  ;
284
285    /**
286     * Gets a list of {@link org.kuali.rice.kim.api.identity.principal.Principal} from an entityId.
287     *
288     * <p>
289     *   This method will only return principals that exist.
290     * </p>
291     *
292     * @param entityId the unique id to retrieve the principals by. cannot be null.
293     * @return a list of {@link org.kuali.rice.kim.api.identity.principal.Principal}
294     * @throws RiceIllegalArgumentException if the entityId is blank
295     */
296    @WebMethod(operationName = "getPrincipalsByEntityId")
297    @WebResult(name = "principals")
298    List<Principal> getPrincipalsByEntityId( @WebParam(name="entityId") String entityId)  ;
299
300    /**
301     * Gets a list of {@link org.kuali.rice.kim.api.identity.principal.Principal} from an employeeId
302     *
303     * <p>
304     *   This method will only return principals that exist.
305     * </p>
306     *
307     * @param employeeId the employee id to retrieve the principals by. cannot be null.
308     * @return a list of {@link org.kuali.rice.kim.api.identity.principal.Principal}
309     * @throws RiceIllegalArgumentException if the employeeId is blank
310     */
311    @WebMethod(operationName = "getPrincipalsByEmployeeId")
312    @WebResult(name = "principals")
313    List<Principal> getPrincipalsByEmployeeId( @WebParam(name="employeeId") String employeeId)  ;
314
315    /**
316     * Gets a {@link org.kuali.rice.kim.api.identity.principal.Principal} from an principalName.
317     *
318     * <p>
319     *   This method will return null if the Principal does not exist.
320     * </p>
321     *
322     * @param principalName the unique id to retrieve the principal by. cannot be null.
323     * @return a {@link org.kuali.rice.kim.api.identity.principal.Principal} or null
324     */
325    @WebMethod(operationName = "getPrincipalByPrincipalName")
326    @WebResult(name = "principal")
327    @Cacheable(value= Principal.Cache.NAME, key="'principalName=' + #p0")
328    Principal getPrincipalByPrincipalName( @WebParam(name="principalName") String principalName )  throws RiceIllegalArgumentException;
329
330    /**
331     * Gets a {@link org.kuali.rice.kim.api.identity.principal.Principal} from an principalName and password.
332     *
333     * <p>
334     *   This method will return null if the Principal does not exist or the password is incorrect.
335     * </p>
336     *
337     * @param principalName the unique id to retrieve the principal by. cannot be null.
338     * @param password the password for the principal
339     * @return a {@link org.kuali.rice.kim.api.identity.principal.Principal} or null
340     * @throws RiceIllegalArgumentException if the principalName is blank
341     */
342    @WebMethod(operationName = "getPrincipalByPrincipalNameAndPassword")
343    @WebResult(name = "principal")
344    @Cacheable(value= Principal.Cache.NAME, key="'principalName=' + #p0 + '|' + 'password=' + #p1")
345    Principal getPrincipalByPrincipalNameAndPassword( @WebParam(name="principalName") String principalName,  @WebParam(name="password") String password )  throws RiceIllegalArgumentException;
346
347    /**
348     * This will create a {@link org.kuali.rice.kim.api.identity.principal.Principal} exactly like the principal passed in.
349     *
350     * The principal object passed in must be populated with an entityId and a principalName
351     *
352     * @param principal the principal to create
353     * @return the newly created Principal object.
354     * @throws RiceIllegalArgumentException if the principal is null
355     * @throws RiceIllegalStateException if the principal already exists in the system or the principal object is not populated with entityId and principalName
356     */
357    @WebMethod(operationName="addPrincipalToEntity")
358    @WebResult(name = "principal")
359    @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
360    Principal addPrincipalToEntity(@WebParam(name = "principal") Principal principal)
361            throws RiceIllegalArgumentException, RiceIllegalStateException;
362
363    /**
364     * This will update a {@link org.kuali.rice.kim.api.identity.principal.Principal} exactly like the principal passed in.
365     *
366     *
367     * @param principal the principal to update
368     * @return the updated Principal object.
369     * @throws RiceIllegalArgumentException if the principal is null
370     * @throws RiceIllegalStateException if the principal does not exist in the system.
371     */
372    @WebMethod(operationName="updatePrincipal")
373    @WebResult(name = "principal")
374    @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
375    Principal updatePrincipal(@WebParam(name = "principal") Principal principal)
376            throws RiceIllegalArgumentException, RiceIllegalStateException;
377
378    /**
379     * This will inactivate a {@link org.kuali.rice.kim.api.identity.principal.Principal}.
380     *
381     *
382     * @param principalId the unique id of the principal to inactivate
383     * @return the inactivated Principal object.
384     * @throws RiceIllegalArgumentException if the principal is null
385     * @throws RiceIllegalStateException if the principal does not exist in the system.
386     */
387    @WebMethod(operationName="inactivatePrincipal")
388    @WebResult(name = "principal")
389    @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
390    Principal inactivatePrincipal(@WebParam(name = "principalId") String principalId)
391            throws RiceIllegalArgumentException, RiceIllegalStateException;
392
393    /**
394     * This will inactivate a {@link org.kuali.rice.kim.api.identity.principal.Principal}.
395     *
396     *
397     * @param principalName the unique principalName of the principal to inactivate
398     * @return the inactivated Principal object.
399     * @throws RiceIllegalArgumentException if the principal is null
400     * @throws RiceIllegalStateException if the principal does not exist in the system.
401     */
402    @WebMethod(operationName="inactivatePrincipalByName")
403    @WebResult(name = "principal")
404    @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
405    Principal inactivatePrincipalByName(@WebParam(name = "principalName") String principalName)
406            throws RiceIllegalArgumentException, RiceIllegalStateException;
407
408
409    /**
410     * This will create a {@link org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo} exactly like the entityTypeContactInfo passed in.
411     *
412     * The EntityTypeContactInfo object passed in must be populated with an entityId and a entityTypeCode
413     *
414     * @param entityTypeContactInfo the EntityTypeContactInfo to create
415     * @return the newly created EntityTypeContactInfo object.
416     * @throws RiceIllegalArgumentException if the entityTypeContactInfo is null
417     * @throws RiceIllegalStateException if the entityTypeContactInfo already exists in the system or the EntityTypeContactInfo object is not populated with entityId and entityTypeCode
418     */
419    @WebMethod(operationName="addEntityTypeContactInfoToEntity")
420    @WebResult(name = "entityTypeContactInfo")
421    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
422    EntityTypeContactInfo addEntityTypeContactInfoToEntity(
423            @WebParam(name = "entityTypeContactInfo") EntityTypeContactInfo entityTypeContactInfo)
424            throws RiceIllegalArgumentException, RiceIllegalStateException;
425
426    /**
427     * This will update a {@link org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo} exactly like the entityTypeContactInfo passed in.
428     *
429     *
430     * @param entityTypeContactInfo the EntityTypeContactInfo to update
431     * @return the updated EntityTypeContactInfo object.
432     * @throws RiceIllegalArgumentException if the entityTypeContactInfo is null
433     * @throws RiceIllegalStateException if the entityTypeContactInfo does not exist in the system.
434     */
435    @WebMethod(operationName="updateEntityTypeContactInfo")
436    @WebResult(name = "entityTypeContactInfo")
437    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
438    EntityTypeContactInfo updateEntityTypeContactInfo(@WebParam(name = "entityTypeContactInfo") EntityTypeContactInfo entityTypeContactInfo)
439            throws RiceIllegalArgumentException, RiceIllegalStateException;
440
441    /**
442     * This will inactivate a {@link org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo} with the passed in parameters.
443     *
444     *
445     * @param entityId the entityId of the EntityTypeContactInfo to inactivate
446     * @param entityTypeCode the entityTypeCode of the EntityTypeContactInfo to inactivate
447     * @return the inactivated EntityTypeContactInfo object.
448     * @throws RiceIllegalArgumentException if the entityId or entityTypeCode passed in is null
449     * @throws RiceIllegalStateException if the EntityTypeContactInfo does not exist in the system.
450     */
451    @WebMethod(operationName="inactivateEntityTypeContactInfo")
452    @WebResult(name = "entityTypeContactInfo")
453    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
454    EntityTypeContactInfo inactivateEntityTypeContactInfo(@WebParam(name = "entityId") String entityId,
455                                                          @WebParam(name = "entityTypeCode") String entityTypeCode)
456            throws RiceIllegalArgumentException, RiceIllegalStateException;
457
458    /**
459     * This will create a {@link org.kuali.rice.kim.api.identity.address.EntityAddress} exactly like the address passed in.
460     *
461     * The EntityAddress object passed in must be populated with an entityId and a entityTypeCode
462     *
463     * @param address the EntityAddress to create
464     * @return the newly created EntityAddress object.
465     * @throws RiceIllegalArgumentException if the address is null
466     * @throws RiceIllegalStateException if the address already exists in the system or address is not populated with entityId and entityTypeCode
467     */
468    @WebMethod(operationName="addAddressToEntity")
469    @WebResult(name = "address")
470    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
471    EntityAddress addAddressToEntity(@WebParam(name = "address") EntityAddress address)
472            throws RiceIllegalArgumentException, RiceIllegalStateException;
473
474    /**
475     * This will update a {@link org.kuali.rice.kim.api.identity.address.EntityAddress} exactly like the address passed in.
476     *
477     *
478     * @param address the EntityAddress to update
479     * @return the updated EntityAddress object.
480     * @throws IllegalArgumentException if the address is null
481     * @throws RiceIllegalArgumentException if the address does not exist in the system.
482     */
483    @WebMethod(operationName="updateAddress")
484    @WebResult(name = "address")
485    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
486    EntityAddress updateAddress(@WebParam(name = "address")EntityAddress address)
487            throws RiceIllegalArgumentException, RiceIllegalStateException;
488
489    /**
490     * This will inactivate a {@link org.kuali.rice.kim.api.identity.address.EntityAddress} with the id passed in.
491     *
492     *
493     * @param id the unique id of the EntityAddress to inactivate
494     * @return the updated EntityAddress object.
495     * @throws RiceIllegalArgumentException if the id is null
496     * @throws RiceIllegalStateException if the address does not exist in the system.
497     */
498    @WebMethod(operationName="inactivateAddress")
499    @WebResult(name = "address")
500    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
501    EntityAddress inactivateAddress(@WebParam(name = "id") String id)
502            throws RiceIllegalArgumentException, RiceIllegalStateException;
503
504    /**
505     * This will create a {@link org.kuali.rice.kim.api.identity.email.EntityEmail} exactly like the email passed in.
506     *
507     * The EntityEmail object passed in must be populated with an entityId and a entityTypeCode
508     *
509     * @param email the EntityEmail to create
510     * @return the newly created EntityEmail object.
511     * @throws RiceIllegalArgumentException if the email is null
512     * @throws RiceIllegalStateException if the email already exists in the system or email is not populated with entityId and entityTypeCode
513     */
514    @WebMethod(operationName="addEmailToEntity")
515    @WebResult(name = "email")
516    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
517    EntityEmail addEmailToEntity(@WebParam(name = "email") EntityEmail email)
518            throws RiceIllegalArgumentException, RiceIllegalStateException;
519
520    /**
521     * This will update a {@link org.kuali.rice.kim.api.identity.email.EntityEmail} exactly like the email passed in.
522     *
523     *
524     * @param email the EntityEmail to update
525     * @return the updated EntityEmail object.
526     * @throws RiceIllegalArgumentException if the email is null
527     * @throws RiceIllegalStateException if the email does not exist in the system.
528     */
529    @WebMethod(operationName="updateEmail")
530    @WebResult(name = "email")
531    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
532    EntityEmail updateEmail(@WebParam(name = "email") EntityEmail email)
533            throws RiceIllegalArgumentException, RiceIllegalStateException;
534
535    /**
536     * This will inactivate the {@link org.kuali.rice.kim.api.identity.email.EntityEmail} with the passed in id.
537     *
538     *
539     * @param id the unique id of the EntityEmail to inactivate
540     * @return the inactivated EntityEmail object.
541     * @throws RiceIllegalArgumentException if the id is null
542     * @throws RiceIllegalStateException if the email does not exist in the system.
543     */
544    @WebMethod(operationName="inactivateEmail")
545    @WebResult(name = "email")
546    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
547    EntityEmail inactivateEmail(@WebParam(name = "id") String id)
548            throws RiceIllegalArgumentException, RiceIllegalStateException;
549
550    /**
551     * This will create a {@link org.kuali.rice.kim.api.identity.phone.EntityPhone} exactly like the phone passed in.
552     *
553     * The EntityPhone object passed in must be populated with an entityId and a entityTypeCode
554     *
555     * @param phone the EntityPhone to create
556     * @return the newly created EntityPhone object.
557     * @throws RiceIllegalArgumentException if the phone is null
558     * @throws RiceIllegalStateException if the phone already exists in the system or phone is not populated with entityId and entityTypeCode
559     */
560    @WebMethod(operationName="addPhoneToEntity")
561    @WebResult(name = "phone")
562    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
563    EntityPhone addPhoneToEntity(@WebParam(name = "phone") EntityPhone phone)
564            throws RiceIllegalArgumentException, RiceIllegalStateException;
565
566    /**
567     * This will update a {@link org.kuali.rice.kim.api.identity.phone.EntityPhone} exactly like the phone passed in.
568     *
569     *
570     * @param phone the EntityPhone to update
571     * @return the updated EntityPhone object.
572     * @throws RiceIllegalArgumentException if the phone is null
573     * @throws RiceIllegalStateException if the phone does not exist in the system.
574     */
575    @WebMethod(operationName="updatePhone")
576    @WebResult(name = "phone")
577    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
578    EntityPhone updatePhone(@WebParam(name = "phone") EntityPhone phone)
579            throws RiceIllegalArgumentException, RiceIllegalStateException;
580
581    /**
582     * This will inactivate the {@link org.kuali.rice.kim.api.identity.phone.EntityPhone} with the passed in id.
583     *
584     *
585     * @param id the unique id of the EntityPhone to inactivate
586     * @return the inactivated EntityPhone object.
587     * @throws RiceIllegalArgumentException if the id is null
588     * @throws RiceIllegalStateException if the phone does not exist in the system.
589     */
590    @WebMethod(operationName="inactivatePhone")
591    @WebResult(name = "phone")
592    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
593    EntityPhone inactivatePhone(@WebParam(name = "id") String id)
594            throws RiceIllegalArgumentException, RiceIllegalStateException;
595
596
597    /**
598     * This will create a {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifier} exactly like the externalId passed in.
599     *
600     * The EntityExternalIdentifier object passed in must be populated with an entityId and a externalIdentifierTypeCode
601     *
602     * @param externalId the EntityExternalIdentifier to create
603     * @return the newly created EntityExternalIdentifier object.
604     * @throws RiceIllegalArgumentException if the externalId is null
605     * @throws RiceIllegalStateException if the externalId already exists in the system or externalId is not populated with entityId and externalIdentifierTypeCode
606     */
607    @WebMethod(operationName="addExternalIdentifierToEntity")
608    @WebResult(name = "externalId")
609    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
610    EntityExternalIdentifier addExternalIdentifierToEntity(@WebParam(name = "externalId") EntityExternalIdentifier externalId)
611            throws RiceIllegalArgumentException, RiceIllegalStateException;
612
613    /**
614     * This will update a {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifier} exactly like the externalId passed in.
615     *
616     *
617     * @param externalId the EntityExternalIdentifier to update
618     * @return the updated EntityExternalIdentifier object.
619     * @throws RiceIllegalArgumentException if the externalId is null
620     * @throws RiceIllegalStateException if the externalId does not exist in the system.
621     */
622    @WebMethod(operationName="updateExternalIdentifier")
623    @WebResult(name = "externalId")
624    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
625    EntityExternalIdentifier updateExternalIdentifier(@WebParam(name = "externalId") EntityExternalIdentifier externalId)
626            throws RiceIllegalArgumentException, RiceIllegalStateException;
627
628    /**
629     * This will create a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation} exactly like the affiliation passed in.
630     *
631     * The EntityAffiliation object passed in must be populated with an entityId and a affiliationType
632     *
633     * @param affiliation the EntityAffiliation to create
634     * @return the newly created EntityAffiliation object.
635     * @throws RiceIllegalArgumentException if the affiliation is null
636     * @throws RiceIllegalStateException if the affiliation already exists in the system or affiliation is not populated with entityId and affiliationType
637     */
638    @WebMethod(operationName="addAffiliationToEntity")
639    @WebResult(name = "affiliation")
640    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
641    EntityAffiliation addAffiliationToEntity(@WebParam(name = "affiliation") EntityAffiliation affiliation)
642            throws RiceIllegalArgumentException, RiceIllegalStateException;
643
644    /**
645     * This will update a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation} exactly like the affiliation passed in.
646     *
647     *
648     * @param affiliation the EntityAffiliation to update
649     * @return the updated EntityAffiliation object.
650     * @throws RiceIllegalArgumentException if the affiliation is null
651     * @throws RiceIllegalStateException if the affiliation does not exist in the system.
652     */
653    @WebMethod(operationName="updateAffiliation")
654    @WebResult(name = "affiliation")
655    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
656    EntityAffiliation updateAffiliation(@WebParam(name = "affiliation") EntityAffiliation affiliation)
657            throws RiceIllegalArgumentException, RiceIllegalStateException;
658
659    /**
660     * This will inactivate a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation} with the id passed in.
661     *
662     *
663     * @param id the unique id of the  EntityAffiliation to inactivate
664     * @return the updated EntityAffiliation object.
665     * @throws RiceIllegalArgumentException if the affiliation is null
666     * @throws RiceIllegalStateException if the affiliation does not exist in the system.
667     */
668    @WebMethod(operationName="inactivateAffiliation")
669    @WebResult(name = "affiliation")
670    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
671    EntityAffiliation inactivateAffiliation(@WebParam(name = "id") String id)
672            throws RiceIllegalArgumentException, RiceIllegalStateException;
673
674    /**
675     * This returns the display name information for the given principal
676     * without loading the full person object.
677     *
678     * @param principalId The principal ID to find the name information for
679     * @return The default name information for the principal
680     */
681    @WebMethod(operationName="getDefaultNamesForPrincipalId")
682    @WebResult(name="entityNamePrincipalName")
683    @Cacheable(value = EntityNamePrincipalName.Cache.NAME, key = "'principalId=' + #p0")
684    public EntityNamePrincipalName getDefaultNamesForPrincipalId(@WebParam(name = "principalId") String principalId);
685
686    /**
687     * This will create a {@link org.kuali.rice.kim.api.identity.name.EntityName} exactly like the name passed in.
688     *
689     * The EntityName object passed in must be populated with an entityId and a nameType
690     *
691     * @param name the EntityName to create
692     * @return the newly created EntityName object.
693     * @throws RiceIllegalArgumentException if the name is null
694     * @throws RiceIllegalStateException if the name already exists in the system or name is not populated with entityId and nameType
695     */
696    @WebMethod(operationName="addNameToEntity")
697    @WebResult(name = "name")
698    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
699    EntityName addNameToEntity(@WebParam(name = "name") EntityName name)
700            throws RiceIllegalArgumentException, RiceIllegalStateException;
701
702    /**
703     * This will update a {@link org.kuali.rice.kim.api.identity.name.EntityName} exactly like the name passed in.
704     *
705     *
706     * @param name the EntityName to update
707     * @return the updated EntityName object.
708     * @throws RiceIllegalArgumentException if the name is null
709     * @throws RiceIllegalStateException if the name does not exist in the system.
710     */
711    @WebMethod(operationName="updateName")
712    @WebResult(name = "name")
713    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
714    EntityName updateName(@WebParam(name = "name") EntityName name)
715            throws RiceIllegalArgumentException, RiceIllegalStateException;
716
717    /**
718     * This will inactivate a {@link org.kuali.rice.kim.api.identity.name.EntityName} with the passed in id.
719     *
720     *
721     * @param id the unique id of the EntityName to inactivate
722     * @return the inactivated EntityName object.
723     * @throws RiceIllegalArgumentException if the id is null
724     * @throws RiceIllegalStateException if the name with the id does not exist in the system.
725     */
726    @WebMethod(operationName="inactivateName")
727    @WebResult(name = "name")
728    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
729    EntityName inactivateName(@WebParam(name = "id") String id)
730            throws RiceIllegalArgumentException, RiceIllegalStateException;
731
732    /**
733     * This will create a {@link org.kuali.rice.kim.api.identity.employment.EntityEmployment} exactly like the employment passed in.
734     *
735     * The EntityEmployment object passed in must be populated with an entityId and a employmentType
736     *
737     * @param employment the EntityEmployment to create
738     * @return the newly created EntityName object.
739     * @throws RiceIllegalArgumentException if the employment is null
740     * @throws RiceIllegalStateException if the employment already exists in the system or employment is not populated with entityId and employmentType
741     */
742    @WebMethod(operationName="addEmploymentToEntity")
743    @WebResult(name = "employment")
744    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
745    EntityEmployment addEmploymentToEntity(@WebParam(name = "employment") EntityEmployment employment)
746            throws RiceIllegalArgumentException, RiceIllegalStateException;
747
748    /**
749     * This will update a {@link org.kuali.rice.kim.api.identity.employment.EntityEmployment} exactly like the employment passed in.
750     *
751     *
752     * @param employment the EntityEmployment to update
753     * @return the updated EntityEmployment object.
754     * @throws RiceIllegalArgumentException if the employment is null
755     * @throws RiceIllegalStateException if the employment does not exist in the system.
756     */
757    @WebMethod(operationName="updateEmployment")
758    @WebResult(name = "employment")
759    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
760    EntityEmployment updateEmployment(@WebParam(name = "employment") EntityEmployment employment)
761            throws RiceIllegalArgumentException, RiceIllegalStateException;
762
763    /**
764     * This will inactivate a {@link org.kuali.rice.kim.api.identity.employment.EntityEmployment} with the passed in id.
765     *
766     *
767     * @param id the unique id of the EntityEmployment to inactivate
768     * @return the inactivated EntityEmployment object.
769     * @throws RiceIllegalArgumentException if the id is null
770     * @throws RiceIllegalStateException if the employment with the id does not exist in the system.
771     */
772    @WebMethod(operationName="inactivateEmployment")
773    @WebResult(name = "employment")
774    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
775    EntityEmployment inactivateEmployment(@WebParam(name = "id") String id)
776            throws RiceIllegalArgumentException, RiceIllegalStateException;
777
778    /**
779     * This will create a {@link org.kuali.rice.kim.api.identity.personal.EntityBioDemographics} exactly like the bioDemographics passed in.
780     *
781     * The EntityBioDemographics object passed in must be populated with an entityId
782     *
783     * @param bioDemographics the EntityBioDemographics to create
784     * @return the newly created EntityBioDemographics object.
785     * @throws RiceIllegalArgumentException if the bioDemographics is null
786     * @throws RiceIllegalStateException if the bioDemographics already exists in the system or bioDemographics is not populated with entityId
787     */
788    @WebMethod(operationName="addBioDemographicsToEntity")
789    @WebResult(name = "bioDemographics")
790    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
791    EntityBioDemographics addBioDemographicsToEntity(@WebParam(name = "bioDemographics") EntityBioDemographics bioDemographics)
792            throws RiceIllegalArgumentException, RiceIllegalStateException;
793
794    /**
795     * This will update a {@link org.kuali.rice.kim.api.identity.personal.EntityBioDemographics} exactly like the bioDemographics passed in.
796     *
797     *
798     * @param bioDemographics the EntityBioDemographics to update
799     * @return the updated EntityBioDemographics object.
800     * @throws RiceIllegalArgumentException if the bioDemographics is null
801     * @throws RiceIllegalStateException if the bioDemographics does not exist in the system.
802     */
803    @WebMethod(operationName="updateBioDemographics")
804    @WebResult(name = "bioDemographics")
805    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
806    EntityBioDemographics updateBioDemographics(@WebParam(name = "bioDemographics") EntityBioDemographics bioDemographics)
807            throws RiceIllegalArgumentException, RiceIllegalStateException;
808
809    /**
810     * Gets a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} for a given id.
811     *
812     * <p>
813     *   This method will return null if the EntityPrivacyPreferences does not exist.
814     * </p>
815     *
816     * @param id the unique id to retrieve the EntityPrivacyPreferences by. Cannot be null.
817     * @return a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} or null
818     * @throws RiceIllegalArgumentException if the entityId is blank
819     */
820    @WebMethod(operationName = "getEntityPrivacyPreferences")
821    @WebResult(name = "privacyPreferences")
822    @Cacheable(value= EntityPrivacyPreferences.Cache.NAME, key="'id=' + #p0")
823    EntityPrivacyPreferences getEntityPrivacyPreferences( @WebParam(name="id") String id )  throws RiceIllegalArgumentException;
824
825    /**
826     * This will create a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} exactly like the privacyPreferences passed in.
827     *
828     * The EntityPrivacyPreferences object passed in must be populated with an entityId
829     *
830     * @param privacyPreferences the EntityPrivacyPreferences to create
831     * @return the newly created EntityPrivacyPreferences object.
832     * @throws RiceIllegalArgumentException if the privacyPreferences is null
833     * @throws RiceIllegalStateException if the privacyPreferences already exists in the system or privacyPreferences is not populated with entityId
834     */
835    @WebMethod(operationName="addPrivacyPreferencesToEntity")
836    @WebResult(name = "privacyPreferences")
837    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityPrivacyPreferences.Cache.NAME}, allEntries = true)
838    EntityPrivacyPreferences addPrivacyPreferencesToEntity(@WebParam(name = "privacyPreferences") EntityPrivacyPreferences privacyPreferences)
839            throws RiceIllegalArgumentException, RiceIllegalStateException;
840
841    /**
842     * This will update a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} exactly like the privacyPreferences passed in.
843     *
844     *
845     * @param privacyPreferences the EntityPrivacyPreferences to update
846     * @return the updated EntityPrivacyPreferences object.
847     * @throws RiceIllegalArgumentException if the privacyPreferences is null
848     * @throws RiceIllegalStateException if the privacyPreferences does not exist in the system.
849     */
850    @WebMethod(operationName="updatePrivacyPreferences")
851    @WebResult(name = "privacyPreferences")
852    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityPrivacyPreferences.Cache.NAME}, allEntries = true)
853    EntityPrivacyPreferences updatePrivacyPreferences(@WebParam(name = "privacyPreferences") EntityPrivacyPreferences privacyPreferences)
854            throws RiceIllegalArgumentException, RiceIllegalStateException;
855
856
857    /**
858     * This will create a {@link org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship} exactly like the citizenship passed in.
859     *
860     * The EntityCitizenship object passed in must be populated with an entityId and a status
861     *
862     * @param citizenship the EntityCitizenship to create
863     * @return the newly created EntityCitizenship object.
864     * @throws RiceIllegalArgumentException if the citizenship is null
865     * @throws RiceIllegalStateException if the citizenship already exists in the system or citizenship is not populated with entityId and status
866     */
867    @WebMethod(operationName="addCitizenshipToEntity")
868    @WebResult(name = "citizenship")
869    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
870    EntityCitizenship addCitizenshipToEntity(@WebParam(name = "citizenship") EntityCitizenship citizenship)
871            throws RiceIllegalArgumentException, RiceIllegalStateException;
872
873    /**
874     * This will update a {@link org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship} exactly like the citizenship passed in.
875     *
876     *
877     * @param citizenship the EntityCitizenship to update
878     * @return the updated EntityCitizenship object.
879     * @throws RiceIllegalArgumentException if the citizenship is null
880     * @throws RiceIllegalStateException if the citizenship does not exist in the system.
881     */
882    @WebMethod(operationName="updateCitizenship")
883    @WebResult(name = "citizenship")
884    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
885    EntityCitizenship updateCitizenship(@WebParam(name = "citizenship") EntityCitizenship citizenship)
886            throws RiceIllegalArgumentException, RiceIllegalStateException;
887
888    /**
889     * This will inactivate a {@link org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship} with the unique id passed in.
890     *
891     *
892     * @param id the id of the EntityCitizenship to inactivate
893     * @return the inactivated EntityCitizenship object.
894     * @throws RiceIllegalArgumentException if the citizenship is null
895     * @throws RiceIllegalStateException if the citizenship does not exist in the system.
896     */
897    @WebMethod(operationName="inactivateCitizenship")
898    @WebResult(name = "citizenship")
899    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
900    EntityCitizenship inactivateCitizenship(@WebParam(name = "id") String id)
901            throws RiceIllegalArgumentException, RiceIllegalStateException;
902
903    /**
904     * This will create a {@link org.kuali.rice.kim.api.identity.personal.EntityEthnicity} exactly like the ethnicity passed in.
905     *
906     * The EntityEthnicity object passed in must be populated with an entityId and a ethnicity code
907     *
908     * @param ethnicity the EntityEthnicity to create
909     * @return the newly created EntityEthnicity object.
910     * @throws RiceIllegalArgumentException if the ethnicity is null
911     * @throws RiceIllegalStateException if the ethnicity already exists in the system or ethnicity is not populated with entityId and ethnicity code
912     */
913    @WebMethod(operationName="addEthnicityToEntity")
914    @WebResult(name = "ethnicity")
915    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
916    EntityEthnicity addEthnicityToEntity(@WebParam(name = "ethnicity") EntityEthnicity ethnicity)
917            throws RiceIllegalArgumentException, RiceIllegalStateException;
918
919    /**
920     * This will update a {@link EntityEthnicity} exactly like the ethnicity passed in.
921     *
922     *
923     * @param ethnicity the EntityEthnicity to update
924     * @return the updated EntityEthnicity object.
925     * @throws RiceIllegalArgumentException if the ethnicity is null
926     * @throws RiceIllegalStateException if the ethnicity does not exist in the system.
927     */
928    @WebMethod(operationName="updateEthnicity")
929    @WebResult(name = "ethnicity")
930    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
931    EntityEthnicity updateEthnicity(@WebParam(name = "ethnicity") EntityEthnicity ethnicity)
932            throws RiceIllegalArgumentException, RiceIllegalStateException;
933
934    /**
935     * This will create a {@link org.kuali.rice.kim.api.identity.residency.EntityResidency} exactly like the residency passed in.
936     *
937     * The EntityResidency object passed in must be populated with an entityId
938     *
939     * @param residency the EntityResidency to create
940     * @return the newly created EntityResidency object.
941     * @throws RiceIllegalArgumentException if the residency is null
942     * @throws RiceIllegalStateException if the residency already exists in the system or residency is not populated with entityId
943     */
944    @WebMethod(operationName="addResidencyToEntity")
945    @WebResult(name = "residency")
946    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
947    EntityResidency addResidencyToEntity(@WebParam(name = "residency") EntityResidency residency)
948            throws RiceIllegalArgumentException, RiceIllegalStateException;
949
950    /**
951     * This will update a {@link org.kuali.rice.kim.api.identity.residency.EntityResidency} exactly like the residency passed in.
952     *
953     *
954     * @param residency the EntityResidency to update
955     * @return the updated EntityResidency object.
956     * @throws RiceIllegalArgumentException if the residency is null
957     * @throws RiceIllegalStateException if the residency does not exist in the system.
958     */
959    @WebMethod(operationName="updateResidency")
960    @WebResult(name = "residency")
961    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
962    EntityResidency updateResidency(@WebParam(name = "residency") EntityResidency residency)
963            throws RiceIllegalArgumentException, RiceIllegalStateException;
964
965
966    /**
967     * This will create a {@link org.kuali.rice.kim.api.identity.visa.EntityVisa} exactly like the visa passed in.
968     *
969     * The EntityVisa object passed in must be populated with an entityId and a visaTypeKey
970     *
971     * @param visa the EntityVisa to create
972     * @return the newly created EntityVisa object.
973     * @throws RiceIllegalArgumentException if the visa is null
974     * @throws RiceIllegalStateException if the visa already exists in the system or visa is not populated with entityId and a visaTypeKey
975     */
976    @WebMethod(operationName="addVisaToEntity")
977    @WebResult(name = "visa")
978    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
979    EntityVisa addVisaToEntity(@WebParam(name = "visa") EntityVisa visa)
980            throws RiceIllegalArgumentException, RiceIllegalStateException;
981
982    /**
983     * This will update a {@link org.kuali.rice.kim.api.identity.visa.EntityVisa} exactly like the visa passed in.
984     *
985     *
986     * @param visa the EntityVisa to update
987     * @return the updated EntityVisa object.
988     * @throws RiceIllegalArgumentException if the visa is null
989     * @throws RiceIllegalStateException if the visa does not exist in the system.
990     */
991    @WebMethod(operationName="updateVisa")
992    @WebResult(name = "visa")
993    @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
994    EntityVisa updateVisa(@WebParam(name = "visa") EntityVisa visa)
995            throws RiceIllegalArgumentException, RiceIllegalStateException;
996
997    /**
998     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityType code.
999     *
1000     * <p>
1001     *   This method will return null if the code does not exist.
1002     * </p>
1003     *
1004     * @param code the unique id to retrieve the Type by. Cannot be null.
1005     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1006     * @throws RiceIllegalArgumentException if the code is blank
1007     */
1008    @WebMethod(operationName = "getEntityType")
1009    @WebResult(name = "type")
1010    @Cacheable(value= CodedAttribute.Cache.NAME + "{EntityType}", key="'code=' + #p0")
1011    CodedAttribute getEntityType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
1012
1013    /**
1014     * Finds all EntityTypes
1015     *
1016     * @since 2.0.1
1017     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1018     */
1019    @WebMethod(operationName = "findAllEntityTypes")
1020    @WebResult(name = "types")
1021    @Cacheable(value= CodedAttribute.Cache.NAME + "{EntityType}", key="'all'")
1022    List<CodedAttribute> findAllEntityTypes();
1023
1024    /**
1025     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityAddressType code.
1026     *
1027     * <p>
1028     *   This method will return null if the code does not exist.
1029     * </p>
1030     *
1031     * @param code the unique id to retrieve the Type by. Cannot be null.
1032     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1033     * @throws RiceIllegalArgumentException if the code is blank
1034     */
1035    @WebMethod(operationName = "getAddressType")
1036    @WebResult(name = "type")
1037    @Cacheable(value= CodedAttribute.Cache.NAME + "{AddressType}", key="'code=' + #p0")
1038    CodedAttribute getAddressType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
1039
1040    /**
1041     * Finds all EntityAddressTypes
1042     *
1043     * @since 2.0.1
1044     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1045     */
1046    @WebMethod(operationName = "findAllAddressTypes")
1047    @WebResult(name = "types")
1048    @Cacheable(value= CodedAttribute.Cache.NAME + "{AddressType}", key="'all'")
1049    List<CodedAttribute> findAllAddressTypes();
1050
1051
1052    /**
1053     * Gets the {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType} for a given EntityAffiliationType code.
1054     *
1055     * <p>
1056     *   This method will return null if the code does not exist.
1057     * </p>
1058     *
1059     * @param code the unique id to retrieve the EntityAffiliationType by. Cannot be null.
1060     * @return a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType} or null
1061     * @throws RiceIllegalArgumentException if the code is blank
1062     */
1063    @WebMethod(operationName = "getAffiliationType")
1064    @WebResult(name = "affiliationType")
1065    @Cacheable(value= CodedAttribute.Cache.NAME + "{AffiliationType}", key="'code=' + #p0")
1066    EntityAffiliationType getAffiliationType( @WebParam(name="code") String code )  throws RiceIllegalArgumentException;
1067
1068    /**
1069     * Finds all EntityAffiliationTypes
1070     *
1071     * @since 2.0.1
1072     * @return a list of {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType}
1073     */
1074    @WebMethod(operationName = "findAllAffiliationTypes")
1075    @WebResult(name = "types")
1076    @Cacheable(value= CodedAttribute.Cache.NAME + "{AffiliationType}", key="'all'")
1077    List<EntityAffiliationType> findAllAffiliationTypes();
1078
1079    /**
1080     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityCitizenship status code.
1081     *
1082     * <p>
1083     *   This method will return null if the code does not exist.
1084     * </p>
1085     *
1086     * @param code the unique id to retrieve the Type by. Cannot be null.
1087     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1088     * @throws RiceIllegalArgumentException if the code is blank
1089     */
1090    @WebMethod(operationName = "getCitizenshipStatus")
1091    @WebResult(name = "type")
1092    @Cacheable(value= CodedAttribute.Cache.NAME + "{CitizenshipStatus}", key="'code=' + #p0")
1093    CodedAttribute getCitizenshipStatus( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
1094
1095    /**
1096     * Finds all EntityCitizenshipStatuses
1097     *
1098     * @since 2.0.1
1099     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1100     */
1101    @WebMethod(operationName = "findAllCitizenshipStatuses")
1102    @WebResult(name = "types")
1103    @Cacheable(value= CodedAttribute.Cache.NAME + "{CitizenshipStatus}", key="'all'")
1104    List<CodedAttribute> findAllCitizenshipStatuses();
1105
1106    /**
1107     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityEmployment type code.
1108     *
1109     * <p>
1110     *   This method will return null if the code does not exist.
1111     * </p>
1112     *
1113     * @param code the unique id to retrieve the Type by. Cannot be null.
1114     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1115     * @throws RiceIllegalArgumentException if the code is blank
1116     */
1117    @WebMethod(operationName = "getEmploymentType")
1118    @WebResult(name = "type")
1119    @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentType}", key="'code=' + #p0")
1120    CodedAttribute getEmploymentType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
1121
1122    /**
1123     * Finds all EntityEmploymentTypes
1124     *
1125     * @since 2.0.1
1126     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1127     */
1128    @WebMethod(operationName = "findAllEmploymentTypes")
1129    @WebResult(name = "types")
1130    @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentType}", key="'all'")
1131    List<CodedAttribute> findAllEmploymentTypes();
1132
1133    /**
1134     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityEmployment status code.
1135     *
1136     * <p>
1137     *   This method will return null if the code does not exist.
1138     * </p>
1139     *
1140     * @param code the unique id to retrieve the Type by. Cannot be null.
1141     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1142     * @throws RiceIllegalArgumentException if the code is blank
1143     */
1144    @WebMethod(operationName = "getEmploymentStatus")
1145    @WebResult(name = "type")
1146    @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentStatus}", key="'code=' + #p0")
1147    CodedAttribute getEmploymentStatus( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
1148
1149    /**
1150     * Finds all EntityEmploymentStatuses
1151     *
1152     * @since 2.0.1
1153     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1154     */
1155    @WebMethod(operationName = "findAllEmploymentStatuses")
1156    @WebResult(name = "types")
1157    @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentStatus}", key="'all'")
1158    List<CodedAttribute> findAllEmploymentStatuses();
1159
1160    /**
1161     * Gets the {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifierType} for a given type code.
1162     *
1163     * <p>
1164     *   This method will return null if the code does not exist.
1165     * </p>
1166     *
1167     * @param code the unique id to retrieve the EntityExternalIdentifierType by. Cannot be null.
1168     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1169     * @throws RiceIllegalArgumentException if the code is blank
1170     */
1171    @WebMethod(operationName = "getExternalIdentifierType")
1172    @WebResult(name = "type")
1173    @Cacheable(value= CodedAttribute.Cache.NAME + "{ExternalIdentifierType}", key="'code=' + #p0")
1174    EntityExternalIdentifierType getExternalIdentifierType( @WebParam(name="code") String code )  throws RiceIllegalArgumentException;
1175
1176    /**
1177     * Finds all ExternalIdentifierTypes
1178     *
1179     * @since 2.0.1
1180     * @return a list of {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifierType}
1181     */
1182    @WebMethod(operationName = "findAllExternalIdentifierTypeTypes")
1183    @WebResult(name = "types")
1184    @Cacheable(value= CodedAttribute.Cache.NAME + "{ExternalIdentifierType}", key="'all'")
1185    List<EntityExternalIdentifierType> findAllExternalIdendtifierTypes();
1186
1187    /**
1188     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityName type code.
1189     *
1190     * <p>
1191     *   This method will return null if the code does not exist.
1192     * </p>
1193     *
1194     * @param code the unique id to retrieve the Type by. Cannot be null.
1195     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1196     * @throws RiceIllegalArgumentException if the code is blank
1197     */
1198    @WebMethod(operationName = "getNameType")
1199    @WebResult(name = "type")
1200    @Cacheable(value= CodedAttribute.Cache.NAME + "{NameType}", key="'code=' + #p0")
1201    CodedAttribute getNameType(@WebParam(name = "code") String code) throws RiceIllegalArgumentException;
1202
1203    /**
1204     * Finds all EntityNameTypes
1205     *
1206     * @since 2.0.1
1207     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1208     */
1209    @WebMethod(operationName = "findAllNameTypes")
1210    @WebResult(name = "types")
1211    @Cacheable(value= CodedAttribute.Cache.NAME + "{NameType}", key="'all'")
1212    List<CodedAttribute> findAllNameTypes();
1213
1214    /**
1215     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityPhone type code.
1216     *
1217     * <p>
1218     *   This method will return null if the code does not exist.
1219     * </p>
1220     *
1221     * @param code the unique id to retrieve the Type by. Cannot be null.
1222     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1223     * @throws RiceIllegalArgumentException if the code is blank
1224     */
1225    @WebMethod(operationName = "getPhoneType")
1226    @WebResult(name = "type")
1227    @Cacheable(value= CodedAttribute.Cache.NAME + "{PhoneType}", key="'code=' + #p0")
1228    CodedAttribute getPhoneType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
1229
1230    /**
1231     * Finds all EntityPhoneTypes
1232     *
1233     * @since 2.0.1
1234     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1235     */
1236    @WebMethod(operationName = "findAllPhoneTypes")
1237    @WebResult(name = "types")
1238    @Cacheable(value= CodedAttribute.Cache.NAME + "{PhoneType}", key="'all'")
1239    List<CodedAttribute> findAllPhoneTypes();
1240
1241    /**
1242     * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityEmail type code.
1243     *
1244     * <p>
1245     *   This method will return null if the code does not exist.
1246     * </p>
1247     *
1248     * @param code the unique id to retrieve the Type by. Cannot be null.
1249     * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
1250     * @throws RiceIllegalArgumentException if the code is blank
1251     */
1252    @WebMethod(operationName = "getEmailType")
1253    @WebResult(name = "type")
1254    @Cacheable(value= CodedAttribute.Cache.NAME + "{EmailType}", key="'code=' + #p0")
1255    CodedAttribute getEmailType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
1256
1257    /**
1258     * Finds all EntityEmailTypes
1259     *
1260     * @since 2.0.1
1261     * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
1262     */
1263    @WebMethod(operationName = "findAllEmailTypes")
1264    @WebResult(name = "types")
1265    @Cacheable(value= CodedAttribute.Cache.NAME + "{EmailType}", key="'all'")
1266    List<CodedAttribute> findAllEmailTypes();
1267
1268    /**
1269     * This method finds Principals based on a query criteria.  The criteria cannot be null.
1270     *
1271     * @since 2.0.1
1272     * @param query the criteria.  Cannot be null.
1273     * @return query results.  will never return null.
1274     * @throws IllegalArgumentException if the queryByCriteria is null
1275     */
1276    @WebMethod(operationName = "findPrincipals")
1277    @WebResult(name = "results")
1278    PrincipalQueryResults findPrincipals(@WebParam(name = "query") QueryByCriteria query)  throws RiceIllegalArgumentException;
1279}
1280