1 /**
2 * Copyright 2005-2011 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 /**
102 * Checks whether the given set of search criteria contain any non-blank properties which need to be applied against
103 * a related Person object. This would be used by the lookup service to determine if special steps need
104 * to be taken when performing a search.
105 */
106 boolean hasPersonProperty(Class<? extends Person> businessObjectClass, Map<String,String> fieldValues);
107 }