Child pages
  • Person Lookup Proposal
Skip to end of metadata
Go to start of metadata

Lookup 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:

/**
 * Searches for a single {@link IPersonAttributes} 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 IPersonAttributes} is returned.</li>
 *  <li>If the user exists and has no attributes an {@link IPersonAttributes} 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 IPersonAttributes} 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 IPersonAttributes getPerson(String uid);

/**
 * Searches for {@link IPersonAttributes}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 IPersonAttributes}s
 * @return A {@link Set} of {@link IPersonAttributes}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<IPersonAttributes> getPeople(Map<String, Object> query);

/**
 * Searches for {@link IPersonAttributes}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 IPersonAttributes}s
 * @return A {@link Set} of {@link IPersonAttributes}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<IPersonAttributes> getPeopleWithMultivaluedAttributes(Map<String, List<Object>> query);

Notice they all return an IPersonAttributes or a Set of IPersonAttributess. To allow for more manageable return signatures of the methods. An IPersonAttributes 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.

  • No labels