This is a proposal to add a new dimension of functionality to Person Directory. Currently Person Directory provides the IPersonAttributeDao, which allows for looking up attributes for a user based on some other attributes. Very useful finding out about a user that has just logged into your system, but you have to know who the user is first.
The opposite side of this problem is looking for a set of users based on some of their attributes. The University of Wisconsin - Madison has implemented a small API for doing this that follows the Person Directory approach as much as possible. I would like to propose that this Person Lookup API be incorporated into the next release of Person Directory. We have a 1.0.0 version of the project available for review here: https://mywebspace.wisc.edu/dalquist/web/JA-SIG/PersonLookup/ The directory includes an archive of the project along with JavaDocs.
Please leave comments on this page related to if this should be included or not in the projectLookup functionality has been added and is pending to be released with version 1.5.0 of Person Directory. The addition of searching required some front-end API changes to allow for multiple attribute sets to be returned in a sane manner. The four existing methods that return a Map (getMultivaluedUserAttributes(Map), getMultivaluedUserAttributes(String), getUserAttributes(Map), getUserAttributes(String)) have all been deprecated. In their place are three new methods:
| Code Block |
|---|
/**
* Searches for a single {@link IPerson} using the specified uid (userName).<br>
*
* This method returns according to the following rules:<br>
* <ul>
* <li>If the user exists and has attributes a populated {@link IPerson} is returned.</li>
* <li>If the user exists and has no attributes an {@link IPerson} with an empty attributes Map is returned.</li>
* <li>If the user doesn't exist <code>null</code> is returned.</li>
* <li>If an error occurs while find the person an appropriate exception will be thrown.</li>
* </ul>
*
* @param uid The userName of the person to find.
* @return The populated {@link IPerson} for the specified uid, null if no person could be found for the uid.
* @throws IllegalArgumentException If <code>uid</code> is <code>null.</code>
*/
public IPerson getPerson(String uid);
/**
* Searches for {@link IPerson}s that match the set of attributes provided in the query {@link Map}. Each
* implementation is free to define what qualifies as a 'match' is on its own. The provided query Map contains
* String attribute names and single values which may be null.
* <br>
* If the implementation can not execute its query for an expected reason such as not enough information in the
* query {@link Map} null should be returned. For unexpected problems throw an exception.
*
* @param query A {@link Map} of name/value pair attributes to use in searching for {@link IPerson}s
* @return A {@link Set} of {@link IPerson}s that match the query {@link Map}. If no matches are found an empty {@link Set} is returned. If the query could not be run null is returned.
* @throws IllegalArgumentException If <code>query</code> is <code>null.</code>
*/
public Set<IPerson> getPeople(Map<String, Object> query);
/**
* Searches for {@link IPerson}s that match the set of attributes provided in the query {@link Map}. Each
* implementation is free to define what qualifies as a 'match' is on its own. The provided query Map contains
* String attribute names and single values which may be null.
* <br>
* If the implementation can not execute its query for an expected reason such as not enough information in the
* query {@link Map} null should be returned. For unexpected problems throw an exception.
*
* @param query A {@link Map} of name/value pair attributes to use in searching for {@link IPerson}s
* @return A {@link Set} of {@link IPerson}s that match the query {@link Map}. If no matches are found an empty {@link Set} is returned. If the query could not be run null is returned.
* @throws IllegalArgumentException If <code>query</code> is <code>null.</code>
*/
public Set<IPerson> getPeopleWithMultivaluedAttributes(Map<String, List<Object>> query);
|
Notice they all return an IPerson or a Set of IPersons. To allow for more manageable return signatures of the methods. An IPerson represents an immutable set of user attributes with an associated user name. It implements the Java Principal interface for added compatibility and is Serializable.
The old APIs still function and all just assume single-user lookups. Some configuration has changed as well, primarily for the JDBC and LDAP DAOs. The new Person Directory Manual outlines how to configure the updated classes.