...
| Note | ||||
|---|---|---|---|---|
| ||||
PersonDirectory was refactored for uPortal 2.5 to be backed by Spring to wire together its implementation. However, documentation exists for PersonDirectory in uPortal 2.4 and earlier. |
PersonDirectory as API
In keeping with the uPortal 2 static service class model (often these static services are factories, e.g. ChannelManagerFactory, but sometimes they are merely static services such as RDBMServices, LdapServices, and PersonDirectory), PersonDirectory now provides a public static method whereby you can get an instance of IPersonAttributeDao.
| Code Block |
|---|
IPersonAttributeDao dao = PersonDirectory.getPersonAttributeDaoInstance();
|
The public IPersonAttributeDao interface methods, in turn, provide an API whereby uPortal components access user attributes.
| Code Block |
|---|
/**
* Obtains a mutable {@link Map} from attribute names to values for
* the given query seed. The values may be mutable objects but it is
* recommended they are immutable.<br>
*
* For the returned {@link Map}; Names must be {@link String}, Values
* can be any {@link Object}, they are typically {@link String}<br>
*
* Values may also be multi-valued, in this case they are of type
* {@link java.util.List} and the lists contents are the values of the
* attribute.<br>
*
* The return of this method uses the following rules:<br>
* <ul>
* <li>If the user exists and has attributes a populated {@link Map} is returned.</li>
* <li>If the user exists and has no attributes an empty {@link Map} is returned.</li>
* <li>If the user doesn't exist <code>null</code> is returned.</li>
* <li>If an error occurs while getting the attributes the appropriate exception will be propagated.</li>
* </ul>
*
* @param seed Map of attributes and values to use for the query
* @return Map from attribute names to values
* @throws IllegalArgumentException If <code>seed</code> is <code>null</code>
*/
public Map getUserAttributes(final Map seed);
/**
* This method uses the default attribute to construct a seed
* {@link Map} and call the {@link #getUserAttributes(Map)} method
* with.
*
* @param uid The string to use as the value in the seed
* @return The same value as returned by {@link #getUserAttributes(Map)}
* @see #getUserAttributes(Map)
*/
public Map getUserAttributes(final String uid);
/**
* Gets a {@link Set} of attribute names that may be returned by the
* {@link #getUserAttributes(Map)}. The names returned represent all
* possible names {@link #getUserAttributes(Map)} could return. If the
* dao doesn't have a way to know all possible attribute names this
* method should return <code>null</code>
* <br>
* An immutable {@link Set} is returned.
*
* @return A {link Set} of possible attribute names for user queries.
*/
public Set getPossibleUserAttributeNames();
|
To get the attributes into an IPerson object use the setAttributes method:
| Code Block |
|---|
/**
* Associates attributes with the user
* @param attrs
*/
public void setAttributes (Map attrs);
|
PersonFactory now offers the service of RestrictedPerson creation.
| Code Block |
|---|
/**
* Creates a <i>restricted</i> user.
* @return <i>restricted</i> user
*/
public static RestrictedPerson createRestrictedPerson() {
...
}
|
An example of how to get a standard IPerson and attributes for it:
| Code Block |
|---|
IPersonAttributeDao dao = PersonDirectory.getPersonAttributeDaoInstance();
Map userAttributes = dao.getUserAttributes(UserID);
IPerson person = PersonFactory.createPerson();
person.setAttributes(userAttributes);
|
PersonDirectory as configurable facility
PersonDirectory is a uPortal customization point.
The standard recommended approach to customizing PersonDirectory is to modify the PersonDirectory Spring context. It is also still possible to replace the name of the class in personDirectoryContext.xml and supply an entirely custom implementation. If you have a legacy implementation from a previous version of uPortal, this may be an attractive option.
| Note | ||
|---|---|---|
| ||
The legacy xml configuration PersonDirs.xml is not supported in uPortal 3.0 and later. |
Using Spring to configure an IPersonAttributeDao implementation
The recommended approach is to use Spring to wire together a Java object that implements IPersonAttributeDao. This facility was added in uPortal 2.5. We expect that the provided implementations of IPersonAttributeDao will be sufficient for most uPortal deployments, however you can also develop a custom IPersonAttributeDao to meet additional needs.
Spring and PersonDirectory
PersonDirectory is implemented using Spring. Currently a Spring beans.dtd-compliant XML file named personDirectoryContext.xml declares the configuration of an instance of IPersonAttributeDao. The class PersonDirectory delegates to this Spring-configured IPersonAttributeDao instance to actually implement the PersonDirectory behavior. PersonDirectory uses PortalApplicationContextFacade to access the the uPortal Spring application context.
JDBC Example
The default personDirectoryContext.xml includes JDBC beans to retrieve attributes for local uPortal usres such as fragment owners. Below is an example of merging in additional attributes via the PersonDb DataSource. Configuration supports mapping a column to multiple uPortal attribute names and using DataSources other than those configured in RDBMServices.
...
<bean id="myunivCachingPersonDbJdbcAttributeSource">
<property name="usernameAttributeProvider" ref="usernameAttributeProvider" />
<property name="cacheNullResults" value="true" />
<property name="userInfoCache">
<bean>
<property name="cacheFactory" ref="cacheFactory" />
<property name="cacheName"
value="org.jasig.services.persondir.USER_INFO.myuniv_person_dir" />
</bean>
</property>
<property name="cacheKeyGenerator" ref="userAttributeCacheKeyGenerator" />
<property name="cachedPersonAttributesDao">
<bean class="org.jasig.services.persondir.support.jdbc.SingleRowJdbcPersonAttributeDao"> >
<constructor-arg index="0" ref="PersonDB" />
<constructor-arg>
<value>
SELECT DISTINCT first_name||' '||Last_name first_last, role,
contentGroup, person_type, first_name, last_name, middle_name,
email_alias, college, class_year, student_status, alias,
work_phone, netid
FROM person_directory_view where {0}
</value>
</constructor-arg>
<property name="usernameAttributeProvider" ref="usernameAttributeProvider" />
<!-- Map the table fields to P3P attribute names -->
<property name="queryAttributeMapping">
<map>
<entry key="displayName" value="FIRST_LAST" />
<entry key="sn" value="LAST_NAME" />
<entry key="contentGroup" value="CONTENT_GROUP" />
<entry key="mail" value="EMAIL_ALIAS" />
<entry key="givenName" value="FIRST_NAME" />
<entry key="alias" value="ALIAS" />
<entry key="personType" value="PERSON_TYPE" />
<entry key="College" value="COLLEGE" />
<entry key="ClassYear" value="CLASS_YEAR" />
<entry key="StudentStatus" value="STUDENT_STATUS" />
<entry key="username" value="NETID" />
<entry key="WorkPhone" value="WORK_PHONE" />
</map>
</property>
<!-- Map the table fields to P3P attribute names -->
<property name="resultAttributeMapping">
<map>
<entry key="FIRST_LAST">
<value>displayName</value>
</entry>
<entry key="LAST_NAME">
<set>
<value>sn</value>
<value>user.name.family</value>
</set>
</entry>
<entry key="ROLE">
<value>uPortalAffiliation</value>
</entry>
<entry key="CONTENTGROUP">
<set>
<value>contentGroup</value>
</set>
</entry>
<entry key="EMAIL_ALIAS">
<set>
<value>mail</value>
<value>user.home-info.online.email</value>
</set>
</entry>
<entry key="FIRST_NAME">
<value>givenName</value>
</entry>
<entry key="ALIAS">
<value>alias</value>
</entry>
<entry key="PERSON_TYPE">
<value>personType</value>
</entry>
<entry key="COLLEGE">
<value>College</value>
</entry>
<entry key="CLASS_YEAR">
<value>ClassYear</value>
</entry>
<entry key="STUDENT_STATUS">
<value>StudentStatus</value>
</entry>
<entry key="NETID">
<set>
<value>uid</value>
<value>netid</value>
<value>username</value>
<value>eduPersonPrincipalName</value>
<value>user.login.id</value>
</set>
</entry>
<entry key="WORK_PHONE">
<value>WorkPhone</value>
</entry>
</map>
</property>
</bean>
</property>
</bean>
For more examples, visit the page dedicated to JdbcPersonAttributeDaoImpl.
LDAP example
In this example we implement IPersonAttributeDao using an LdapPersonAttributeDaoImpl.
Here we use the ILdapServer named "personLdap" managed by LdapServices. We configure the map from LDAP attribute names to uPortal attribute names and the query we'll use to look up the user. Advanced configuration allows mapping LDAP attribute names to multiple uPortal attribute names.
...
The basic class for a uPotal user is an implementation of the IPerson object. The uPortal Person Directory Service is used to populate and retrieve user attributes. Person Directory is maintained as a separate source project PersonDirectory. uPortal 3.2 provides the single class, PersonDirectory, to obtain an instance of IPersonAttributeDao. This class is currently deprecated and will no longer be needed in a future version of uPortal that is entirely Spring configured. Attributes can be acquired from multiple sources via LDAP, JDBC or other sources as required.
An example of how to get a standard IPerson and attributes for it:
| Code Block |
|---|
IPersonAttributeDao dao = PersonDirectory.getPersonAttributeDaoInstance();
Map userAttributes = dao.getUserAttributes(UserID);
IPerson person = PersonFactory.createPerson();
person.setAttributes(userAttributes);
|
Below is a description of the default Person Directory configuration. See JDBC User Attribute Sources and LDAP User Attribute Sources for examples of setting additional attributes via JDBC and LDAP.
Configuring PersonDirectory
PersonDirectory is a uPortal customization point.
The standard recommended approach to customizing PersonDirectory is to modify the PersonDirectory Spring context. It is also still possible to replace the name of the class in personDirectoryContext.xml and supply an entirely custom implementation. If you have a legacy implementation from a previous version of uPortal, this may be an attractive option.
| Note | ||
|---|---|---|
| ||
The legacy xml configuration PersonDirs.xml is not supported in uPortal 3.0 and later. |
Using Spring to configure an IPersonAttributeDao implementation
The recommended approach is to use Spring to wire together a Java object that implements IPersonAttributeDao. This facility was added in uPortal 2.5. We expect that the provided implementations of IPersonAttributeDao will be sufficient for most uPortal deployments, however you can also develop a custom IPersonAttributeDao to meet additional needs.
Spring and PersonDirectory
Currently a Spring beans.dtd-compliant XML file named personDirectoryContext.xml declares the configuration of an instance of IPersonAttributeDao. The class PersonDirectory delegates to this Spring-configured IPersonAttributeDao instance to actually implement the PersonDirectory behavior.
JDBC Example
For examples, visit the page dedicated to JDBC User Attribute Sources.
LDAP example
For examples, visit the page dedicated to LDAP User Attribute Sources.
Request Attribute Filter Example
...