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 java.util.List;
019    import java.util.Map;
020    
021    import org.kuali.rice.krad.bo.BusinessObject;
022    
023    /**
024     * 
025     * This service acts as a facade on the entity information that is provided
026     * through the IdentityService and provides a "person-centric" view of that 
027     * entity data.
028     * 
029     * <p>In general, the Person object flattens out the various related pieces of
030     * entity data into a denormalized view on that data.  In many cases, that
031     * data will have a defined "default" value in the entity data model.  This
032     * default data is what the Person object will be constructed with.  For
033     * example, an entity can have more than one name, but one of those names
034     * is flagged as the default.
035     * 
036     * <p>This service will do it's best to construct valid Person objects even
037     * for entities that don't have an entity type of "PERSON".  In those cases
038     * not all of the attributes on the Person object will be populated.
039     * 
040     * @author Kuali Rice Team (rice.collab@kuali.org)
041     *
042     */
043    public interface PersonService {
044    
045            /**
046             * Retrieve a single Person object by Principal ID.
047             */
048            Person getPerson( String principalId );
049            
050            /**
051             * Retrieve a person by an arbitrary external identifier.  This method could
052             * potentially return multiple results as there is no guarantee of uniqueness
053             * for external identifiers.
054             * 
055             * @param externalIdentifierTypeCode Type of external identifier to search for.
056             * @param externalId The external identifier.
057             * @return List of Person objects.
058             */
059            List<Person> getPersonByExternalIdentifier( String externalIdentifierTypeCode, String externalId );
060            
061            /**
062             * Gets a single Person by their principal name (user ID).
063             */
064            Person getPersonByPrincipalName( String principalName );
065            
066            /**
067             * Gets a single Person by their employee id.
068             */
069            Person getPersonByEmployeeId( String employeeId ); 
070            
071            /**
072             * Perform an unbounded search for person records.
073             */
074            List<Person> findPeople( Map<String, String> criteria );
075    
076            /**
077             * Perform a Person lookup.  If bounded, it will follow the configured KNS lookup limit.
078             */
079            List<Person> findPeople( Map<String, String> criteria, boolean unbounded );
080            
081            /**
082             * Get the class object which points to the class used by the underlying implementation.
083             * 
084             * This can be used by implementors who may need to construct Person objects without wishing to bind their code
085             * to a specific implementation.
086             */
087            Class<? extends Person> getPersonImplementationClass();
088            
089            /**
090         * This method takes a map on its way to populate a business object and replaces all 
091         * user identifiers with their corresponding universal users
092             */
093            Map<String, String> resolvePrincipalNamesToPrincipalIds( BusinessObject businessObject, Map<String, String> fieldValues );
094            
095        /**
096         * Compares the Principal ID passed in with that in the Person object.  If they are the same, it returns the
097         * original object.  Otherwise, it pulls the Person from KIM based on the sourcePrincipalId.
098         */
099            Person updatePersonIfNecessary(String sourcePrincipalId, Person currentPerson );
100    
101    }