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