/**
    * Copyright 2005-2014 The Kuali Foundation
    *
    * Licensed under the Educational Community License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
    * http://www.opensource.org/licenses/ecl2.php
    *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.kuali.rice.kim.api.identity;
  
  import org.kuali.rice.core.api.criteria.QueryByCriteria;
  import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
  import org.kuali.rice.core.api.exception.RiceIllegalStateException;
  import org.kuali.rice.kim.api.KimConstants;
  import org.kuali.rice.kim.api.identity.address.EntityAddress;
  import org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation;
  import org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType;
  import org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship;
  import org.kuali.rice.kim.api.identity.email.EntityEmail;
  import org.kuali.rice.kim.api.identity.employment.EntityEmployment;
  import org.kuali.rice.kim.api.identity.entity.Entity;
  import org.kuali.rice.kim.api.identity.entity.EntityDefault;
  import org.kuali.rice.kim.api.identity.entity.EntityDefaultQueryResults;
  import org.kuali.rice.kim.api.identity.entity.EntityQueryResults;
  import org.kuali.rice.kim.api.identity.external.EntityExternalIdentifier;
  import org.kuali.rice.kim.api.identity.external.EntityExternalIdentifierType;
  import org.kuali.rice.kim.api.identity.name.EntityName;
  import org.kuali.rice.kim.api.identity.personal.EntityBioDemographics;
  import org.kuali.rice.kim.api.identity.personal.EntityEthnicity;
  import org.kuali.rice.kim.api.identity.phone.EntityPhone;
  import org.kuali.rice.kim.api.identity.principal.EntityNamePrincipalName;
  import org.kuali.rice.kim.api.identity.principal.Principal;
  import org.kuali.rice.kim.api.identity.principal.PrincipalQueryResults;
  import org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences;
  import org.kuali.rice.kim.api.identity.residency.EntityResidency;
  import org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo;
  import org.kuali.rice.kim.api.identity.visa.EntityVisa;
  import org.springframework.cache.annotation.CacheEvict;
  import org.springframework.cache.annotation.Cacheable;
  
  import javax.jws.WebMethod;
  import javax.jws.WebParam;
  import javax.jws.WebResult;
  import javax.jws.WebService;
  import javax.jws.soap.SOAPBinding;
  import java.util.List;
  import java.util.Map;
  
  /**
   * This service provides operations to query for principal and identity data.
   *
   * <p>A principal represents an identity that can authenticate.  In essence, a principal can be
   * thought of as an "account" or as an identity's authentication credentials.  A principal has
   * an id which is used to uniquely identify it.  It also has a name which represents the
   * principal's username and is typically what is entered when authenticating.  All principals
   * are associated with one and only one identity.
   *
   * <p>An identity represents a person or system.  Additionally, other "types" of entities can
   * be defined in KIM.  Information like name, phone number, etc. is associated with an identity.
   * It is the representation of a concrete person or system.  While an identity will typically
   * have a single principal associated with it, it is possible for an identity to have more than
   * one principal or even no principals at all (in the case where the identity does not actually
   * authenticate).
   *
   * <p>This service also provides operations for querying various pieces of reference data, such as
   * address types, affiliation types, phone types, etc.
   *
   *
   * @author Kuali Rice Team (rice.collab@kuali.org)
   *
   */
  @WebService(name = "identityService", targetNamespace = KimConstants.Namespaces.KIM_NAMESPACE_2_0)
  @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
  public interface IdentityService {
  
      /**
       * This method finds EntityDefault data based on a query criteria.  The criteria cannot be null.
       *
       * @param query the criteria.  Cannot be null.
       * @return query results.  will never return null.
       * @throws RiceIllegalArgumentException if the queryByCriteria is null
       */
      @WebMethod(operationName = "findEntityDefaults")
      @WebResult(name = "results")
  	EntityDefaultQueryResults findEntityDefaults(@WebParam(name = "query") QueryByCriteria query)  throws RiceIllegalArgumentException;
  
      /**
       * This method finds Entities based on a query criteria.  The criteria cannot be null.
       *
       * @param query the criteria.  Cannot be null.
       * @return query results.  will never return null.
       * @throws RiceIllegalArgumentException if the queryByCriteria is null
      */
     @WebMethod(operationName = "findEntities")
     @WebResult(name = "results")
 	EntityQueryResults findEntities(@WebParam(name = "query") QueryByCriteria query)  throws RiceIllegalArgumentException;
 
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from an id.
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param id the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
      * @throws RiceIllegalArgumentException if the id is blank
      */
     @WebMethod(operationName = "getEntity")
     @WebResult(name = "entity")
     @Cacheable(value= Entity.Cache.NAME, key="'id=' + #p0")
 	Entity getEntity( @WebParam(name="id") String id )  throws RiceIllegalArgumentException;
 
 	/**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from a principalId.
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param principalId the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
      * @throws RiceIllegalArgumentException if the principalId is blank
      */
     @WebMethod(operationName = "getEntityByPrincipalId")
     @WebResult(name = "entity")
     @Cacheable(value= Entity.Cache.NAME, key="'principalId=' + #p0")
 	Entity getEntityByPrincipalId(@WebParam(name = "principalId") String principalId)  throws RiceIllegalArgumentException;
 
 	/**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from a principalName.
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param principalName the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
      * @throws RiceIllegalArgumentException if the id is blank
      */
     @WebMethod(operationName = "getEntityByPrincipalName")
     @WebResult(name = "entity")
     @Cacheable(value= Entity.Cache.NAME, key="'principalName=' + #p0")
 	Entity getEntityByPrincipalName(@WebParam(name = "principalName") String principalName)  throws RiceIllegalArgumentException;
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.Entity} from a employeeId.
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param employeeId the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.Entity} or null
      * @throws RiceIllegalArgumentException if the employeeId is blank
      */
     @WebMethod(operationName = "getEntityByEmployeeId")
     @WebResult(name = "entity")
     @Cacheable(value= Entity.Cache.NAME, key="'employeeId=' + #p0")
     Entity getEntityByEmployeeId(@WebParam(name = "employeeId") String employeeId)  throws RiceIllegalArgumentException;
 
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.entity.Entity} exactly like the entity passed in.
      *
      * @param entity the entity to create
      * @return the newly created Entity object.
      * @throws RiceIllegalArgumentException if the entity is null
      * @throws RiceIllegalStateException if the entity already exists in the system
      */
     @WebMethod(operationName="createEntity")
     @WebResult(name = "entity")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     Entity createEntity(@WebParam(name = "entity") Entity entity)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.entity.Entity}.
      *
      * @param entity the entity to update
      * @return the updated Entity object.
      * @throws RiceIllegalArgumentException if the entity is null
      * @throws RiceIllegalStateException if the entity does not already exist in the system
      */
     @WebMethod(operationName="updateEntity")
     @WebResult(name = "entity")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
     Entity updateEntity(@WebParam(name = "entity") Entity entity)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.entity.Entity}.
      *
      * @param id the unique id of the entity to inactivate
      * @return the inactivated Entity object.
      * @throws RiceIllegalArgumentException if the entity is null
      * @throws RiceIllegalStateException if the entity does not already exist in the system
      */
     @WebMethod(operationName="inactivateEntity")
     @WebResult(name = "entity")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     Entity inactivateEntity(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
 
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an id.
      * {@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
      * default values of its subclasses
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param id the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
      * @throws RiceIllegalArgumentException if the id is blank
      */
     @WebMethod(operationName = "getEntityDefault")
     @WebResult(name = "entityDefault")
     @Cacheable(value= EntityDefault.Cache.NAME, key="'id=' + #p0")
 	EntityDefault getEntityDefault(@WebParam(name = "id") String id)  throws RiceIllegalArgumentException;
 
 	/**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an principalId.
      * {@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
      * default values of its subclasses
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param principalId the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
      * @throws RiceIllegalArgumentException if the principalId is blank
      */
     @WebMethod(operationName = "getEntityDefaultByPrincipalId")
     @WebResult(name = "entityDefault")
     @Cacheable(value= EntityDefault.Cache.NAME, key="'principalId=' + #p0")
 	EntityDefault getEntityDefaultByPrincipalId(@WebParam(name = "principalId") String principalId)  throws RiceIllegalArgumentException;
 
 	/**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an principalName.
      * {@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
      * default values of its subclasses
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param principalName the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
      * @throws RiceIllegalArgumentException if the principalId is blank
      */
     @WebMethod(operationName = "getEntityDefaultByPrincipalName")
     @WebResult(name = "entityDefault")
     @Cacheable(value= EntityDefault.Cache.NAME, key="'principalName=' + #p0")
 	EntityDefault getEntityDefaultByPrincipalName(@WebParam(name = "principalName") String principalName)  throws RiceIllegalArgumentException;
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} from an employeeId.
      * {@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
      * default values of its subclasses
      *
      * <p>
      *   This method will return null if the Entity does not exist.
      * </p>
      *
      * @param employeeId the unique id to retrieve the entity by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.entity.EntityDefault} or null
      * @throws RiceIllegalArgumentException if the employeeId is blank
      */
     @WebMethod(operationName = "getEntityDefaultByEmployeeId")
     @WebResult(name = "entityDefault")
     @Cacheable(value= EntityDefault.Cache.NAME, key="'employeeId=' + #p0")
     EntityDefault getEntityDefaultByEmployeeId(@WebParam(name = "employeeId") String employeeId)  throws RiceIllegalArgumentException;
 
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.principal.Principal} from an principalId.
      *
      * <p>
      *   This method will return null if the Principal does not exist.
      * </p>
      *
      * @param principalId the unique id to retrieve the principal by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.principal.Principal} or null
      * @throws RiceIllegalArgumentException if the principalId is blank
      */
     @WebMethod(operationName = "getPrincipal")
     @WebResult(name = "principal")
     @Cacheable(value= Principal.Cache.NAME, key="'principalId=' + #p0")
     Principal getPrincipal( @WebParam(name="principalId") String principalId )  throws RiceIllegalArgumentException;
 
 
     /**
      * Gets a list of {@link org.kuali.rice.kim.api.identity.principal.Principal} from a string list of principalId.
      *
      * <p>
      *   This method will only return principals that exist.
      * </p>
      *
      * @param principalIds the unique id to retrieve the principal by. cannot be null.
      * @return a list of {@link org.kuali.rice.kim.api.identity.principal.Principal}
      * @throws RiceIllegalArgumentException if the principalId is blank
      */
     @WebMethod(operationName = "getPrincipals")
     @WebResult(name = "ret")
     List<Principal> getPrincipals( @WebParam(name="principalIds") List<String> principalIds)  ;
 
     /**
      * Gets a list of {@link org.kuali.rice.kim.api.identity.principal.Principal} from an entityId.
      *
      * <p>
      *   This method will only return principals that exist.
      * </p>
      *
      * @param entityId the unique id to retrieve the principals by. cannot be null.
      * @return a list of {@link org.kuali.rice.kim.api.identity.principal.Principal}
      * @throws RiceIllegalArgumentException if the entityId is blank
      */
     @WebMethod(operationName = "getPrincipalsByEntityId")
     @WebResult(name = "principals")
     List<Principal> getPrincipalsByEntityId( @WebParam(name="entityId") String entityId)  ;
 
     /**
      * Gets a list of {@link org.kuali.rice.kim.api.identity.principal.Principal} from an employeeId
      *
      * <p>
      *   This method will only return principals that exist.
      * </p>
      *
      * @param employeeId the employee id to retrieve the principals by. cannot be null.
      * @return a list of {@link org.kuali.rice.kim.api.identity.principal.Principal}
      * @throws RiceIllegalArgumentException if the employeeId is blank
      */
     @WebMethod(operationName = "getPrincipalsByEmployeeId")
     @WebResult(name = "principals")
     List<Principal> getPrincipalsByEmployeeId( @WebParam(name="employeeId") String employeeId)  ;
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.principal.Principal} from an principalName.
      *
      * <p>
      *   This method will return null if the Principal does not exist.
      * </p>
      *
      * @param principalName the unique id to retrieve the principal by. cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.principal.Principal} or null
      */
     @WebMethod(operationName = "getPrincipalByPrincipalName")
     @WebResult(name = "principal")
     @Cacheable(value= Principal.Cache.NAME, key="'principalName=' + #p0")
     Principal getPrincipalByPrincipalName( @WebParam(name="principalName") String principalName )  throws RiceIllegalArgumentException;
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.principal.Principal} from an principalName and password.
      *
      * <p>
      *   This method will return null if the Principal does not exist or the password is incorrect.
      * </p>
      *
      * @param principalName the unique id to retrieve the principal by. cannot be null.
      * @param password the password for the principal
      * @return a {@link org.kuali.rice.kim.api.identity.principal.Principal} or null
      * @throws RiceIllegalArgumentException if the principalName is blank
      */
     @WebMethod(operationName = "getPrincipalByPrincipalNameAndPassword")
     @WebResult(name = "principal")
     @Cacheable(value= Principal.Cache.NAME, key="'principalName=' + #p0 + '|' + 'password=' + #p1")
     Principal getPrincipalByPrincipalNameAndPassword( @WebParam(name="principalName") String principalName,  @WebParam(name="password") String password )  throws RiceIllegalArgumentException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.principal.Principal} exactly like the principal passed in.
      *
      * The principal object passed in must be populated with an entityId and a principalName
      *
      * @param principal the principal to create
      * @return the newly created Principal object.
      * @throws RiceIllegalArgumentException if the principal is null
      * @throws RiceIllegalStateException if the principal already exists in the system or the principal object is not populated with entityId and principalName
      */
     @WebMethod(operationName="addPrincipalToEntity")
     @WebResult(name = "principal")
     @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     Principal addPrincipalToEntity(@WebParam(name = "principal") Principal principal)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.principal.Principal} exactly like the principal passed in.
      *
      *
      * @param principal the principal to update
      * @return the updated Principal object.
      * @throws RiceIllegalArgumentException if the principal is null
      * @throws RiceIllegalStateException if the principal does not exist in the system.
      */
     @WebMethod(operationName="updatePrincipal")
     @WebResult(name = "principal")
     @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
     Principal updatePrincipal(@WebParam(name = "principal") Principal principal)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.principal.Principal}.
      *
      *
      * @param principalId the unique id of the principal to inactivate
      * @return the inactivated Principal object.
      * @throws RiceIllegalArgumentException if the principal is null
      * @throws RiceIllegalStateException if the principal does not exist in the system.
      */
     @WebMethod(operationName="inactivatePrincipal")
     @WebResult(name = "principal")
     @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     Principal inactivatePrincipal(@WebParam(name = "principalId") String principalId)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.principal.Principal}.
      *
      *
      * @param principalName the unique principalName of the principal to inactivate
      * @return the inactivated Principal object.
      * @throws RiceIllegalArgumentException if the principal is null
      * @throws RiceIllegalStateException if the principal does not exist in the system.
      */
     @WebMethod(operationName="inactivatePrincipalByName")
     @WebResult(name = "principal")
     @CacheEvict(value = {Principal.Cache.NAME, Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     Principal inactivatePrincipalByName(@WebParam(name = "principalName") String principalName)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo} exactly like the entityTypeContactInfo passed in.
      *
      * The EntityTypeContactInfo object passed in must be populated with an entityId and a entityTypeCode
      *
      * @param entityTypeContactInfo the EntityTypeContactInfo to create
      * @return the newly created EntityTypeContactInfo object.
      * @throws RiceIllegalArgumentException if the entityTypeContactInfo is null
      * @throws RiceIllegalStateException if the entityTypeContactInfo already exists in the system or the EntityTypeContactInfo object is not populated with entityId and entityTypeCode
      */
     @WebMethod(operationName="addEntityTypeContactInfoToEntity")
     @WebResult(name = "entityTypeContactInfo")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityTypeContactInfo addEntityTypeContactInfoToEntity(
             @WebParam(name = "entityTypeContactInfo") EntityTypeContactInfo entityTypeContactInfo)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo} exactly like the entityTypeContactInfo passed in.
      *
      *
      * @param entityTypeContactInfo the EntityTypeContactInfo to update
      * @return the updated EntityTypeContactInfo object.
      * @throws RiceIllegalArgumentException if the entityTypeContactInfo is null
      * @throws RiceIllegalStateException if the entityTypeContactInfo does not exist in the system.
      */
     @WebMethod(operationName="updateEntityTypeContactInfo")
     @WebResult(name = "entityTypeContactInfo")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityTypeContactInfo updateEntityTypeContactInfo(@WebParam(name = "entityTypeContactInfo") EntityTypeContactInfo entityTypeContactInfo)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.type.EntityTypeContactInfo} with the passed in parameters.
      *
      *
      * @param entityId the entityId of the EntityTypeContactInfo to inactivate
      * @param entityTypeCode the entityTypeCode of the EntityTypeContactInfo to inactivate
      * @return the inactivated EntityTypeContactInfo object.
      * @throws RiceIllegalArgumentException if the entityId or entityTypeCode passed in is null
      * @throws RiceIllegalStateException if the EntityTypeContactInfo does not exist in the system.
      */
     @WebMethod(operationName="inactivateEntityTypeContactInfo")
     @WebResult(name = "entityTypeContactInfo")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityTypeContactInfo inactivateEntityTypeContactInfo(@WebParam(name = "entityId") String entityId,
             @WebParam(name = "entityTypeCode") String entityTypeCode)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.address.EntityAddress} exactly like the address passed in.
      *
      * The EntityAddress object passed in must be populated with an entityId and a entityTypeCode
      *
      * @param address the EntityAddress to create
      * @return the newly created EntityAddress object.
      * @throws RiceIllegalArgumentException if the address is null
      * @throws RiceIllegalStateException if the address already exists in the system or address is not populated with entityId and entityTypeCode
      */
     @WebMethod(operationName="addAddressToEntity")
     @WebResult(name = "address")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityAddress addAddressToEntity(@WebParam(name = "address") EntityAddress address)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.address.EntityAddress} exactly like the address passed in.
      *
      *
      * @param address the EntityAddress to update
      * @return the updated EntityAddress object.
      * @throws IllegalArgumentException if the address is null
      * @throws RiceIllegalArgumentException if the address does not exist in the system.
      */
     @WebMethod(operationName="updateAddress")
     @WebResult(name = "address")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityAddress updateAddress(@WebParam(name = "address")EntityAddress address)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.address.EntityAddress} with the id passed in.
      *
      *
      * @param id the unique id of the EntityAddress to inactivate
      * @return the updated EntityAddress object.
      * @throws RiceIllegalArgumentException if the id is null
      * @throws RiceIllegalStateException if the address does not exist in the system.
      */
     @WebMethod(operationName="inactivateAddress")
     @WebResult(name = "address")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityAddress inactivateAddress(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.email.EntityEmail} exactly like the email passed in.
      *
      * The EntityEmail object passed in must be populated with an entityId and a entityTypeCode
      *
      * @param email the EntityEmail to create
      * @return the newly created EntityEmail object.
      * @throws RiceIllegalArgumentException if the email is null
      * @throws RiceIllegalStateException if the email already exists in the system or email is not populated with entityId and entityTypeCode
      */
     @WebMethod(operationName="addEmailToEntity")
     @WebResult(name = "email")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEmail addEmailToEntity(@WebParam(name = "email") EntityEmail email)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.email.EntityEmail} exactly like the email passed in.
      *
      *
      * @param email the EntityEmail to update
      * @return the updated EntityEmail object.
      * @throws RiceIllegalArgumentException if the email is null
      * @throws RiceIllegalStateException if the email does not exist in the system.
      */
     @WebMethod(operationName="updateEmail")
     @WebResult(name = "email")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEmail updateEmail(@WebParam(name = "email") EntityEmail email)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate the {@link org.kuali.rice.kim.api.identity.email.EntityEmail} with the passed in id.
      *
      *
      * @param id the unique id of the EntityEmail to inactivate
      * @return the inactivated EntityEmail object.
      * @throws RiceIllegalArgumentException if the id is null
      * @throws RiceIllegalStateException if the email does not exist in the system.
      */
     @WebMethod(operationName="inactivateEmail")
     @WebResult(name = "email")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEmail inactivateEmail(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.phone.EntityPhone} exactly like the phone passed in.
      *
      * The EntityPhone object passed in must be populated with an entityId and a entityTypeCode
      *
      * @param phone the EntityPhone to create
      * @return the newly created EntityPhone object.
      * @throws RiceIllegalArgumentException if the phone is null
      * @throws RiceIllegalStateException if the phone already exists in the system or phone is not populated with entityId and entityTypeCode
      */
     @WebMethod(operationName="addPhoneToEntity")
     @WebResult(name = "phone")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityPhone addPhoneToEntity(@WebParam(name = "phone") EntityPhone phone)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.phone.EntityPhone} exactly like the phone passed in.
      *
      *
      * @param phone the EntityPhone to update
      * @return the updated EntityPhone object.
      * @throws RiceIllegalArgumentException if the phone is null
      * @throws RiceIllegalStateException if the phone does not exist in the system.
      */
     @WebMethod(operationName="updatePhone")
     @WebResult(name = "phone")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityPhone updatePhone(@WebParam(name = "phone") EntityPhone phone)
             throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate the {@link org.kuali.rice.kim.api.identity.phone.EntityPhone} with the passed in id.
      *
      *
      * @param id the unique id of the EntityPhone to inactivate
      * @return the inactivated EntityPhone object.
      * @throws RiceIllegalArgumentException if the id is null
      * @throws RiceIllegalStateException if the phone does not exist in the system.
      */
     @WebMethod(operationName="inactivatePhone")
     @WebResult(name = "phone")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityPhone inactivatePhone(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifier} exactly like the externalId passed in.
      *
      * The EntityExternalIdentifier object passed in must be populated with an entityId and a externalIdentifierTypeCode
      *
      * @param externalId the EntityExternalIdentifier to create
      * @return the newly created EntityExternalIdentifier object.
      * @throws RiceIllegalArgumentException if the externalId is null
      * @throws RiceIllegalStateException if the externalId already exists in the system or externalId is not populated with entityId and externalIdentifierTypeCode
      */
     @WebMethod(operationName="addExternalIdentifierToEntity")
     @WebResult(name = "externalId")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityExternalIdentifier addExternalIdentifierToEntity(@WebParam(name = "externalId") EntityExternalIdentifier externalId)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifier} exactly like the externalId passed in.
      *
      *
      * @param externalId the EntityExternalIdentifier to update
      * @return the updated EntityExternalIdentifier object.
      * @throws RiceIllegalArgumentException if the externalId is null
      * @throws RiceIllegalStateException if the externalId does not exist in the system.
      */
     @WebMethod(operationName="updateExternalIdentifier")
     @WebResult(name = "externalId")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityExternalIdentifier updateExternalIdentifier(@WebParam(name = "externalId") EntityExternalIdentifier externalId)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation} exactly like the affiliation passed in.
      *
      * The EntityAffiliation object passed in must be populated with an entityId and a affiliationType
      *
      * @param affiliation the EntityAffiliation to create
      * @return the newly created EntityAffiliation object.
      * @throws RiceIllegalArgumentException if the affiliation is null
      * @throws RiceIllegalStateException if the affiliation already exists in the system or affiliation is not populated with entityId and affiliationType
      */
     @WebMethod(operationName="addAffiliationToEntity")
     @WebResult(name = "affiliation")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityAffiliation addAffiliationToEntity(@WebParam(name = "affiliation") EntityAffiliation affiliation)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation} exactly like the affiliation passed in.
      *
      *
      * @param affiliation the EntityAffiliation to update
      * @return the updated EntityAffiliation object.
      * @throws RiceIllegalArgumentException if the affiliation is null
      * @throws RiceIllegalStateException if the affiliation does not exist in the system.
      */
     @WebMethod(operationName="updateAffiliation")
     @WebResult(name = "affiliation")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityAffiliation updateAffiliation(@WebParam(name = "affiliation") EntityAffiliation affiliation)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliation} with the id passed in.
      *
      *
      * @param id the unique id of the  EntityAffiliation to inactivate
      * @return the updated EntityAffiliation object.
      * @throws RiceIllegalArgumentException if the affiliation is null
      * @throws RiceIllegalStateException if the affiliation does not exist in the system.
      */
     @WebMethod(operationName="inactivateAffiliation")
     @WebResult(name = "affiliation")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityAffiliation inactivateAffiliation(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This returns the display name information for the given principal
      * without loading the full person object.
      *
      * @param principalId The principal ID to find the name information for
      * @return The default name information for the principal
      */
     @WebMethod(operationName="getDefaultNamesForPrincipalId")
     @WebResult(name="entityNamePrincipalName")
     @Cacheable(value = EntityNamePrincipalName.Cache.NAME, key = "'principalId=' + #p0")
     public EntityNamePrincipalName getDefaultNamesForPrincipalId(@WebParam(name = "principalId") String principalId);
 
     /**
      * This returns the display name information for the given principals without loading the full person object.
      *
      * @param principalIds A list of principal IDs to find the name information for
      * @return A Map which is keyed by principal ID and the value is the default
      *         name for that principal.  If an active, default name cannot be
      *         found for a principal in the list it will be in the map with a null value.
      */
     @WebMethod(operationName="getDefaultNamesForPrincipalIds")
     @WebResult(name="entityNamePrincipalNames")
     public Map<String, EntityNamePrincipalName> getDefaultNamesForPrincipalIds(@WebParam(name = "principalIds") List<String> principalIds);
 
     /**
      * Returns the privacy preferences for the given principal id or null if the principal id is not valid.  Note method
      *   converts list to a <code>HashSet</code> to ensure no duplicate look ups occur.
      * @param principalId the principal id
      * @return The privacy preferences for the given principal id, or null if the principal id is invalid.
      */
     @WebMethod(operationName="getPrivacyPreferencesForPrincipalId")
     @WebResult(name="entityPrivacyPreferences")
     @Cacheable(value = EntityPrivacyPreferences.Cache.NAME, key = "'principalId=' + #p0")
     public EntityPrivacyPreferences getPrivacyPreferencesForPrincipalId(@WebParam(name = "principalId")String principalId);
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.name.EntityName} exactly like the name passed in.
      *
      * The EntityName object passed in must be populated with an entityId and a nameType
      *
      * @param name the EntityName to create
      * @return the newly created EntityName object.
      * @throws RiceIllegalArgumentException if the name is null
      * @throws RiceIllegalStateException if the name already exists in the system or name is not populated with entityId and nameType
      */
     @WebMethod(operationName="addNameToEntity")
     @WebResult(name = "name")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
     EntityName addNameToEntity(@WebParam(name = "name") EntityName name)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.name.EntityName} exactly like the name passed in.
      *
      *
      * @param name the EntityName to update
      * @return the updated EntityName object.
      * @throws RiceIllegalArgumentException if the name is null
      * @throws RiceIllegalStateException if the name does not exist in the system.
      */
     @WebMethod(operationName="updateName")
     @WebResult(name = "name")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityNamePrincipalName.Cache.NAME}, allEntries = true)
     EntityName updateName(@WebParam(name = "name") EntityName name)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.name.EntityName} with the passed in id.
      *
      *
      * @param id the unique id of the EntityName to inactivate
      * @return the inactivated EntityName object.
      * @throws RiceIllegalArgumentException if the id is null
      * @throws RiceIllegalStateException if the name with the id does not exist in the system.
      */
     @WebMethod(operationName="inactivateName")
     @WebResult(name = "name")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityName inactivateName(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.employment.EntityEmployment} exactly like the employment passed in.
      *
      * The EntityEmployment object passed in must be populated with an entityId and a employmentType
      *
      * @param employment the EntityEmployment to create
      * @return the newly created EntityName object.
      * @throws RiceIllegalArgumentException if the employment is null
      * @throws RiceIllegalStateException if the employment already exists in the system or employment is not populated with entityId and employmentType
      */
     @WebMethod(operationName="addEmploymentToEntity")
     @WebResult(name = "employment")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEmployment addEmploymentToEntity(@WebParam(name = "employment") EntityEmployment employment)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.employment.EntityEmployment} exactly like the employment passed in.
      *
      *
      * @param employment the EntityEmployment to update
      * @return the updated EntityEmployment object.
      * @throws RiceIllegalArgumentException if the employment is null
      * @throws RiceIllegalStateException if the employment does not exist in the system.
      */
     @WebMethod(operationName="updateEmployment")
     @WebResult(name = "employment")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEmployment updateEmployment(@WebParam(name = "employment") EntityEmployment employment)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.employment.EntityEmployment} with the passed in id.
      *
      *
      * @param id the unique id of the EntityEmployment to inactivate
      * @return the inactivated EntityEmployment object.
      * @throws RiceIllegalArgumentException if the id is null
      * @throws RiceIllegalStateException if the employment with the id does not exist in the system.
      */
     @WebMethod(operationName="inactivateEmployment")
     @WebResult(name = "employment")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEmployment inactivateEmployment(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.personal.EntityBioDemographics} exactly like the bioDemographics passed in.
      *
      * The EntityBioDemographics object passed in must be populated with an entityId
      *
      * @param bioDemographics the EntityBioDemographics to create
      * @return the newly created EntityBioDemographics object.
      * @throws RiceIllegalArgumentException if the bioDemographics is null
      * @throws RiceIllegalStateException if the bioDemographics already exists in the system or bioDemographics is not populated with entityId
      */
     @WebMethod(operationName="addBioDemographicsToEntity")
     @WebResult(name = "bioDemographics")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityBioDemographics addBioDemographicsToEntity(@WebParam(name = "bioDemographics") EntityBioDemographics bioDemographics)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.personal.EntityBioDemographics} exactly like the bioDemographics passed in.
      *
      *
      * @param bioDemographics the EntityBioDemographics to update
      * @return the updated EntityBioDemographics object.
      * @throws RiceIllegalArgumentException if the bioDemographics is null
      * @throws RiceIllegalStateException if the bioDemographics does not exist in the system.
      */
     @WebMethod(operationName="updateBioDemographics")
     @WebResult(name = "bioDemographics")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityBioDemographics updateBioDemographics(@WebParam(name = "bioDemographics") EntityBioDemographics bioDemographics)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * Gets a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} for a given id.
      *
      * <p>
      *   This method will return null if the EntityPrivacyPreferences does not exist.
      * </p>
      *
      * @param id the unique id to retrieve the EntityPrivacyPreferences by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} or null
      * @throws RiceIllegalArgumentException if the entityId is blank
      */
     @WebMethod(operationName = "getEntityPrivacyPreferences")
     @WebResult(name = "privacyPreferences")
     @Cacheable(value= EntityPrivacyPreferences.Cache.NAME, key="'id=' + #p0")
 	EntityPrivacyPreferences getEntityPrivacyPreferences( @WebParam(name="id") String id )  throws RiceIllegalArgumentException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} exactly like the privacyPreferences passed in.
      *
      * The EntityPrivacyPreferences object passed in must be populated with an entityId
      *
      * @param privacyPreferences the EntityPrivacyPreferences to create
      * @return the newly created EntityPrivacyPreferences object.
      * @throws RiceIllegalArgumentException if the privacyPreferences is null
      * @throws RiceIllegalStateException if the privacyPreferences already exists in the system or privacyPreferences is not populated with entityId
      */
     @WebMethod(operationName="addPrivacyPreferencesToEntity")
     @WebResult(name = "privacyPreferences")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityPrivacyPreferences.Cache.NAME}, allEntries = true)
     EntityPrivacyPreferences addPrivacyPreferencesToEntity(@WebParam(name = "privacyPreferences") EntityPrivacyPreferences privacyPreferences)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.privacy.EntityPrivacyPreferences} exactly like the privacyPreferences passed in.
      *
      *
      * @param privacyPreferences the EntityPrivacyPreferences to update
      * @return the updated EntityPrivacyPreferences object.
      * @throws RiceIllegalArgumentException if the privacyPreferences is null
      * @throws RiceIllegalStateException if the privacyPreferences does not exist in the system.
      */
     @WebMethod(operationName="updatePrivacyPreferences")
     @WebResult(name = "privacyPreferences")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME, EntityPrivacyPreferences.Cache.NAME}, allEntries = true)
     EntityPrivacyPreferences updatePrivacyPreferences(@WebParam(name = "privacyPreferences") EntityPrivacyPreferences privacyPreferences)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship} exactly like the citizenship passed in.
      *
      * The EntityCitizenship object passed in must be populated with an entityId and a status
      *
      * @param citizenship the EntityCitizenship to create
      * @return the newly created EntityCitizenship object.
      * @throws RiceIllegalArgumentException if the citizenship is null
      * @throws RiceIllegalStateException if the citizenship already exists in the system or citizenship is not populated with entityId and status
      */
     @WebMethod(operationName="addCitizenshipToEntity")
     @WebResult(name = "citizenship")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityCitizenship addCitizenshipToEntity(@WebParam(name = "citizenship") EntityCitizenship citizenship)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship} exactly like the citizenship passed in.
      *
      *
      * @param citizenship the EntityCitizenship to update
      * @return the updated EntityCitizenship object.
      * @throws RiceIllegalArgumentException if the citizenship is null
      * @throws RiceIllegalStateException if the citizenship does not exist in the system.
      */
     @WebMethod(operationName="updateCitizenship")
     @WebResult(name = "citizenship")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityCitizenship updateCitizenship(@WebParam(name = "citizenship") EntityCitizenship citizenship)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will inactivate a {@link org.kuali.rice.kim.api.identity.citizenship.EntityCitizenship} with the unique id passed in.
      *
      *
      * @param id the id of the EntityCitizenship to inactivate
      * @return the inactivated EntityCitizenship object.
      * @throws RiceIllegalArgumentException if the citizenship is null
      * @throws RiceIllegalStateException if the citizenship does not exist in the system.
      */
     @WebMethod(operationName="inactivateCitizenship")
     @WebResult(name = "citizenship")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityCitizenship inactivateCitizenship(@WebParam(name = "id") String id)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link EntityEthnicity} exactly like the ethnicity passed in.
      *
      * The EntityEthnicity object passed in must be populated with an entityId and a ethnicity code
      *
      * @param ethnicity the EntityEthnicity to create
      * @return the newly created EntityEthnicity object.
      * @throws RiceIllegalArgumentException if the ethnicity is null
      * @throws RiceIllegalStateException if the ethnicity already exists in the system or ethnicity is not populated with entityId and ethnicity code
      */
     @WebMethod(operationName="addEthnicityToEntity")
     @WebResult(name = "ethnicity")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEthnicity addEthnicityToEntity(@WebParam(name = "ethnicity") EntityEthnicity ethnicity)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link EntityEthnicity} exactly like the ethnicity passed in.
      *
      *
      * @param ethnicity the EntityEthnicity to update
      * @return the updated EntityEthnicity object.
      * @throws RiceIllegalArgumentException if the ethnicity is null
      * @throws RiceIllegalStateException if the ethnicity does not exist in the system.
      */
     @WebMethod(operationName="updateEthnicity")
     @WebResult(name = "ethnicity")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityEthnicity updateEthnicity(@WebParam(name = "ethnicity") EntityEthnicity ethnicity)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.residency.EntityResidency} exactly like the residency passed in.
      *
      * The EntityResidency object passed in must be populated with an entityId
      *
      * @param residency the EntityResidency to create
      * @return the newly created EntityResidency object.
      * @throws RiceIllegalArgumentException if the residency is null
      * @throws RiceIllegalStateException if the residency already exists in the system or residency is not populated with entityId
      */
     @WebMethod(operationName="addResidencyToEntity")
     @WebResult(name = "residency")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityResidency addResidencyToEntity(@WebParam(name = "residency") EntityResidency residency)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.residency.EntityResidency} exactly like the residency passed in.
      *
      *
      * @param residency the EntityResidency to update
      * @return the updated EntityResidency object.
      * @throws RiceIllegalArgumentException if the residency is null
      * @throws RiceIllegalStateException if the residency does not exist in the system.
      */
     @WebMethod(operationName="updateResidency")
     @WebResult(name = "residency")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityResidency updateResidency(@WebParam(name = "residency") EntityResidency residency)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
 
     /**
      * This will create a {@link org.kuali.rice.kim.api.identity.visa.EntityVisa} exactly like the visa passed in.
      *
      * The EntityVisa object passed in must be populated with an entityId and a visaTypeKey
      *
      * @param visa the EntityVisa to create
      * @return the newly created EntityVisa object.
      * @throws RiceIllegalArgumentException if the visa is null
      * @throws RiceIllegalStateException if the visa already exists in the system or visa is not populated with entityId and a visaTypeKey
      */
     @WebMethod(operationName="addVisaToEntity")
     @WebResult(name = "visa")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityVisa addVisaToEntity(@WebParam(name = "visa") EntityVisa visa)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * This will update a {@link org.kuali.rice.kim.api.identity.visa.EntityVisa} exactly like the visa passed in.
      *
      *
      * @param visa the EntityVisa to update
      * @return the updated EntityVisa object.
      * @throws RiceIllegalArgumentException if the visa is null
      * @throws RiceIllegalStateException if the visa does not exist in the system.
      */
     @WebMethod(operationName="updateVisa")
     @WebResult(name = "visa")
     @CacheEvict(value={Entity.Cache.NAME, EntityDefault.Cache.NAME}, allEntries = true)
     EntityVisa updateVisa(@WebParam(name = "visa") EntityVisa visa)
         throws RiceIllegalArgumentException, RiceIllegalStateException;
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityType code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getEntityType")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EntityType}", key="'code=' + #p0")
 	CodedAttribute getEntityType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllEntityTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EntityType}", key="'all'")
     List<CodedAttribute> findAllEntityTypes();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityAddressType code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getAddressType")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{AddressType}", key="'code=' + #p0")
 	CodedAttribute getAddressType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityAddressTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllAddressTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{AddressType}", key="'all'")
     List<CodedAttribute> findAllAddressTypes();
 
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType} for a given EntityAffiliationType code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the EntityAffiliationType by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getAffiliationType")
     @WebResult(name = "affiliationType")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{AffiliationType}", key="'code=' + #p0")
 	EntityAffiliationType getAffiliationType( @WebParam(name="code") String code )  throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityAffiliationTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.affiliation.EntityAffiliationType}
      */
     @WebMethod(operationName = "findAllAffiliationTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{AffiliationType}", key="'all'")
     List<EntityAffiliationType> findAllAffiliationTypes();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityCitizenship status code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getCitizenshipStatus")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{CitizenshipStatus}", key="'code=' + #p0")
 	CodedAttribute getCitizenshipStatus( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityCitizenshipStatuses
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllCitizenshipStatuses")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{CitizenshipStatus}", key="'all'")
     List<CodedAttribute> findAllCitizenshipStatuses();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityEmployment type code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getEmploymentType")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentType}", key="'code=' + #p0")
 	CodedAttribute getEmploymentType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityEmploymentTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllEmploymentTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentType}", key="'all'")
     List<CodedAttribute> findAllEmploymentTypes();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityEmployment status code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getEmploymentStatus")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentStatus}", key="'code=' + #p0")
 	CodedAttribute getEmploymentStatus( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityEmploymentStatuses
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllEmploymentStatuses")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EmploymentStatus}", key="'all'")
     List<CodedAttribute> findAllEmploymentStatuses();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifierType} for a given type code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the EntityExternalIdentifierType by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getExternalIdentifierType")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{ExternalIdentifierType}", key="'code=' + #p0")
 	EntityExternalIdentifierType getExternalIdentifierType( @WebParam(name="code") String code )  throws RiceIllegalArgumentException;
 
     /**
      * Finds all ExternalIdentifierTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.external.EntityExternalIdentifierType}
      */
     @WebMethod(operationName = "findAllExternalIdentifierTypeTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{ExternalIdentifierType}", key="'all'")
     List<EntityExternalIdentifierType> findAllExternalIdendtifierTypes();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityName type code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getNameType")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{NameType}", key="'code=' + #p0")
 	CodedAttribute getNameType(@WebParam(name = "code") String code) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityNameTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllNameTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{NameType}", key="'all'")
     List<CodedAttribute> findAllNameTypes();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityPhone type code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getPhoneType")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{PhoneType}", key="'code=' + #p0")
 	CodedAttribute getPhoneType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityPhoneTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllPhoneTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{PhoneType}", key="'all'")
     List<CodedAttribute> findAllPhoneTypes();
 
     /**
      * Gets the {@link org.kuali.rice.kim.api.identity.CodedAttribute} for a given EntityEmail type code.
      *
      * <p>
      *   This method will return null if the code does not exist.
      * </p>
      *
      * @param code the unique id to retrieve the Type by. Cannot be null.
      * @return a {@link org.kuali.rice.kim.api.identity.CodedAttribute} or null
      * @throws RiceIllegalArgumentException if the code is blank
      */
     @WebMethod(operationName = "getEmailType")
     @WebResult(name = "type")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EmailType}", key="'code=' + #p0")
 	CodedAttribute getEmailType( @WebParam(name="code") String code ) throws RiceIllegalArgumentException;
 
     /**
      * Finds all EntityEmailTypes
      *
      * @since 2.0.1
      * @return a list of {@link org.kuali.rice.kim.api.identity.CodedAttribute}
      */
     @WebMethod(operationName = "findAllEmailTypes")
     @WebResult(name = "types")
     @Cacheable(value= CodedAttribute.Cache.NAME + "{EmailType}", key="'all'")
     List<CodedAttribute> findAllEmailTypes();
 
     /**
      * This method finds Principals based on a query criteria.  The criteria cannot be null.
      *
      * @since 2.0.1
      * @param query the criteria.  Cannot be null.
      * @return query results.  will never return null.
      * @throws IllegalArgumentException if the queryByCriteria is null
      */
     @WebMethod(operationName = "findPrincipals")
     @WebResult(name = "results")
     PrincipalQueryResults findPrincipals(@WebParam(name = "query") QueryByCriteria query)  throws RiceIllegalArgumentException;
 }