In uPortal 3.0, by default user attribute collection is configured in a properties files named /uportal-impl/src/main/resources/properties/contexts/personDirectoryContext.xml in the language of Spring beans.
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.
IPersonAttributeDao dao = PersonDirectory.getPersonAttributeDaoInstance();
The public IPersonAttributeDao interface methods, in turn, provide an API whereby uPortal components access user attributes.
/**
* 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:
/** * Associates attributes with the user * @param attrs */ public void setAttributes (Map attrs);
PersonFactory now offers the service of RestrictedPerson creation.
/**
* 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:
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.
PersonDirs.xml is not supported
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.
<beans>
<bean id="personDirectory"
class="org.jasig.portal.services.persondir.support.LdapPersonAttributeDaoImpl">
<property name="ldapAttributesToPortalAttributes">
<map>
<entry key="name">
<value>name</value>
</entry>
<entry key="shirt_color">
<value>shirtColor</value>
</entry>
</map>
</property>
<property name="ldapServer">
<bean class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
<property name="staticMethod">
<value>org.jasig.portal.ldap.LdapServices.getLdapServer</value>
</property>
<property name="arguments">
<list>
<value>personLdap</value>
</list>
</property>
</bean>
</property>
<property name="uidQuery">
<value>(cn={0})</value>
</property>
</bean>
</beans>
Request Attribute Filter Example
The Request Attribute Filter is designed for use with Shibboleth. For a complete discussion of configuring uPortal for Shibboleth, see Shibboleth. The following example shows a use of the RequestAttributeSourceFilter to retrieve the serverName attribute. In a real life scenario you would want to retrieve person attributes provided in the request.
<!--
| Servlet filter that creates an attribute for the serverName
+-->
<bean id="requestAttributeSourceFilter" class="org.jasig.services.persondir.support.web.RequestAttributeSourceFilter">
<property name="additionalDescriptors" ref="requestAdditionalDescriptors" />
<property name="serverNameAttribute" value="serverName" />
<property name="processingPosition" value="BOTH" />
</bean>
Merging example
This would get pretty boring if we could only ever have one source of user attributes at a time. MergingPersonAttributeDaoImpl merges attributes from multiple sources.
Here we're merging together attributes from a JDBCPersonAttributeDaoImpl and from an LdapPersonAttributeDaoImpl. Here we've accepted the default merge strategy, but MergingPersonAttributeDaoImpl is configurable to accept alternative merge strategies. MergingPersonAttributeDaoImpl can also be configured as to how it should handle exceptions thrown by the DAOs it is merging.
<beans>
<bean id="personAttributeDao"
class="org.jasig.portal.services.persondir.support.MergingPersonAttributeDaoImpl">
<property name="personAttributeDaos">
<list>
<bean
class="org.jasig.portal.services.persondir.support.JdbcPersonAttributeDaoImpl">
<constructor-arg>
<bean
class="org.springframework.jdbc.datasource.DriverManagerDataSource">
<property name="driverClassName"><value>${jdbc.driverClassName}</value></property>
<property name="url"><value>${jdbc.url}</value></property>
<property name="username"><value>${jdbc.username}</value></property>
<property name="password"><value>${jdbc.password}</value></property>
</bean>
</constructor-arg>
<constructor-arg>
<value>SELECT name, shirt_color FROM
someschema.sometable WHERE uid = ?</value>
</constructor-arg>
<property name="columnsToAttributes">
<map>
<entry key="name">
<value>name</value>
</entry>
<entry key="shirt_color">
<value>shirtColor</value>
</entry>
</map>
</property>
</bean>
<bean
class="org.jasig.portal.services.persondir.support.LdapPersonAttributeDaoImpl">
<property name="ldapAttributesToPortalAttributes">
<map>
<entry key="name">
<value>name</value>
</entry>
<entry key="shirt_color">
<value>shirtColor</value>
</entry>
</map>
</property>
<property name="ldapServer">
<bean
class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
<property name="staticMethod">
<value>
org.jasig.portal.ldap.LdapServices.getLdapServer</value>
</property>
<property name="arguments">
<list>
<value>personLdap</value>
</list>
</property>
</bean>
</property>
<property name="uidQuery">
<value>(cn={0})</value>
</property>
</bean>
</list>
</property>
</bean>
</beans>
Rolling your own
If you have special requirements not handled by the Person Directory implementations you can still use the provided IPersonAttributeDao support classes where they fit in with the particular attribute retrieval strategy you're trying to implement.
<beans>
<bean id="personAttributeDao"
class="edu.youruniv.portal.persondir.CustomPersonAttributeDaoImpl">
</bean>
</beans>
Custom Java implementation
Not Recommended
Although not recommended it is possible to change the class name in the personDirectory.xml beans declaration to be a custom class of your choice, so long as it implements IPersonAttributeDao. You could then write a custom implementation that does exactly the queries, caching, and any other behavior you need.
<beans>
<!- notice that the bean's class has changed ->
<bean id="personAttributeDao">
<!-- if you're implementing all your configuration directly in the Java, you need not
add any properties here -->
</bean>
</beans>