01: /* Copyright 2004 The JA-SIG Collaborative. All rights reserved.
02: * See license distributed with this file and
03: * available online at http://www.uportal.org/license.html
04: */
05:
06: package org.jasig.portal.services.persondir;
07:
08: import java.util.Map;
09: import java.util.Set;
10:
11: /**
12: * Data access object which, for a given {@link Map} of query
13: * data, returns a {@link Map} from attribute names to attribute
14: * values.
15: *
16: * @author andrew.petro@yale.edu
17: * @author Eric Dalquist <a href="mailto:edalquist@unicon.net">edalquist@unicon.net</a>
18: * @version $Revision: 35855 $ $Date: 2005-05-25 10:13:00 -0700 (Wed, 25 May 2005) $
19: * @since uPortal 2.5
20: */
21: public interface IPersonAttributeDao {
22:
23: /**
24: * Obtains a mutable {@link Map} from attribute names to values for
25: * the given query seed which is an immutable Map. The values may be mutable objects but it is
26: * recommended that they be immutable.<br>
27: *
28: * For the returned {@link Map}; Keys must be {@link String}, Values
29: * can be any {@link Object}, they are typically {@link String}s.<br>
30: *
31: * Values may also be multi-valued, in this case they are of type
32: * {@link java.util.List} and the list contents are the values of the
33: * attribute.<br>
34: *
35: * This method returns according to the following rules:<br>
36: * <ul>
37: * <li>If the user exists and has attributes a populated {@link Map} is returned.</li>
38: * <li>If the user exists and has no attributes an empty {@link Map} is returned.</li>
39: * <li>If the user doesn't exist <code>null</code> is returned.</li>
40: * <li>If an error occurs while getting the attributes the appropriate exception will be propagated.</li>
41: * </ul>
42: * <br>
43: * Unless otherwise specified by an implementation the returned {@link Map}
44: * will not be a union of the seed and query results. If your are given a
45: * {@link Map} that includes the attribute "phone" and value "555-1212" and
46: * the returned {@link Map} contains the attribute "phone" with the value
47: * "555-1212", this means that your implementation also believes that the
48: * "phone" attribute should have this value.
49: *
50: * @param seed immutable Map of attributes to values to seed the query
51: * @return Map from attribute names to values
52: * @throws IllegalArgumentException If <code>seed</code> is <code>null.</code>
53: */
54: public Map getUserAttributes(final Map seed);
55:
56: /**
57: * This method uses a single attribute to get a {@link Map} of user
58: * attributes.
59: * <br>
60: * This methods follows the same return rules as {@link #getUserAttributes(Map)}
61: *
62: * @param uid The string to use as the value in the seed
63: * @return Map from attribute names to values
64: * @see #getUserAttributes(Map)
65: */
66: public Map getUserAttributes(final String uid);
67:
68: /**
69: * Gets a {@link Set} of attribute names that may be returned by the
70: * {@link #getUserAttributes(Map)}. The names returned represent all
71: * possible names {@link #getUserAttributes(Map)} could return. If the
72: * dao doesn't have a way to know all possible attribute names this
73: * method should return <code>null</code>.
74: * <br>
75: * Returns an immutable {@link Set}.
76: *
77: * @return A {link Set} of possible attribute names for user queries.
78: */
79: public Set getPossibleUserAttributeNames();
80: }
|