View Javadoc
1   /**
2    * Copyright 2005-2015 The Kuali Foundation
3    *
4    * Licensed under the Educational Community License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.opensource.org/licenses/ecl2.php
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.kuali.rice.kim.api.identity;
17  
18  import java.util.List;
19  import java.util.Map;
20  
21  import org.kuali.rice.krad.bo.BusinessObject;
22  
23  /**
24   * 
25   * This service acts as a facade on the entity information that is provided
26   * through the IdentityService and provides a "person-centric" view of that 
27   * entity data.
28   * 
29   * <p>In general, the Person object flattens out the various related pieces of
30   * entity data into a denormalized view on that data.  In many cases, that
31   * data will have a defined "default" value in the entity data model.  This
32   * default data is what the Person object will be constructed with.  For
33   * example, an entity can have more than one name, but one of those names
34   * is flagged as the default.
35   * 
36   * <p>This service will do it's best to construct valid Person objects even
37   * for entities that don't have an entity type of "PERSON".  In those cases
38   * not all of the attributes on the Person object will be populated.
39   * 
40   * @author Kuali Rice Team (rice.collab@kuali.org)
41   *
42   */
43  public interface PersonService {
44  
45  	/**
46  	 * Retrieve a single Person object by Principal ID.
47  	 */
48  	Person getPerson( String principalId );
49  	
50  	/**
51  	 * Retrieve a person by an arbitrary external identifier.  This method could
52  	 * potentially return multiple results as there is no guarantee of uniqueness
53  	 * for external identifiers.
54  	 * 
55  	 * @param externalIdentifierTypeCode Type of external identifier to search for.
56  	 * @param externalId The external identifier.
57  	 * @return List of Person objects.
58  	 */
59  	List<Person> getPersonByExternalIdentifier( String externalIdentifierTypeCode, String externalId );
60  	
61  	/**
62  	 * Gets a single Person by their principal name (user ID).
63  	 */
64  	Person getPersonByPrincipalName( String principalName );
65  	
66  	/**
67  	 * Gets a single Person by their employee id.
68  	 */
69  	Person getPersonByEmployeeId( String employeeId ); 
70  	
71  	/**
72  	 * Perform an unbounded search for person records.
73  	 */
74  	List<Person> findPeople( Map<String, String> criteria );
75  
76  	/**
77  	 * Perform a Person lookup.  If bounded, it will follow the configured KNS lookup limit.
78  	 */
79  	List<Person> findPeople( Map<String, String> criteria, boolean unbounded );
80  	
81  	/**
82  	 * Get the class object which points to the class used by the underlying implementation.
83  	 * 
84  	 * This can be used by implementors who may need to construct Person objects without wishing to bind their code
85  	 * to a specific implementation.
86  	 */
87  	Class<? extends Person> getPersonImplementationClass();
88  	
89  	/**
90       * This method takes a map on its way to populate a business object and replaces all 
91       * user identifiers with their corresponding universal users
92  	 */
93  	Map<String, String> resolvePrincipalNamesToPrincipalIds( BusinessObject businessObject, Map<String, String> fieldValues );
94  	
95      /**
96       * Compares the Principal ID passed in with that in the Person object.  If they are the same, it returns the
97       * original object.  Otherwise, it pulls the Person from KIM based on the sourcePrincipalId.
98       */
99  	Person updatePersonIfNecessary(String sourcePrincipalId, Person currentPerson );
100 
101 }