Page Comparison

...

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 new (as of uP 2.5) 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.

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.

The default personDirectoryContext.xml that ships with uPortal declares that the IPersonAttributeDao we want to use is the LegacyPersonAttributeDao, which parses and instantiates the "recipe" given in PersonDirs.xml.

...

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:

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.

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

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">
        <!-- the legacy implementation takes no configuration -->                  </bean> </beans>

JDBC Example

Here's an example of using Spring to wire together a JdbcPersonAttributeDaoImpl that implements IPersonAttributeDao by querying a JDBC attribute store. The database used is that managed by RDBMServices under the name "personDb". We configure also the SQL query we'll use to get attributes for the user and the mapping from column names to uPortal attribute names. Configuration supports mapping a column to multiple uPortal attribute names and using DataSources other than those configured in RDBMServices.

<beans>
    <!-- this is the key bean, with the special id "personAttributeDao" that PersonDirectory is looking for. -->
    <bean id="personAttributeDao"     <value>name</value>
                            </entry>
                            <entry key="shirt_color">
                                <value>shirtColor</value>
          class="org.jasig.portal.services.persondir.support.JdbcPersonAttributeDaoImpl">                  </entry>
      <!-- the JDBC implementation takes two arguments in its constructor.         </map>
                    </property>
the first is a DataSource -->         <constructor-arg>              <!-- here we're using the default DataSource from RDBMServices. --></bean>
                <bean
   <bean                 class="org.springframeworkjasig.portal.beansservices.factorypersondir.configsupport.MethodInvokingFactoryBeanLdapPersonAttributeDaoImpl">
                    <property name="staticMethod" value="org.jasig.portal.RDBMServices.getDataSource"/>ldapAttributesToPortalAttributes">
                   </bean>     <map>
   </constructor-arg>             <!-- the second constructor argument to the JDBC implementation is the SQL <entry key="name">
            query that will yield a single row.  The ? will be replaced with the      <value>name</value>
        userid about whom we are querying -->         <constructor-arg>     </entry>
       <value>SELECT name, shirt_color FROM someschema.sometable                 WHERE<entry uid = ?</value>key="shirt_color">
         </constructor-arg>             <!-- the JDBC implementation has one other requirement: a Map <value>shirtColor</value>
              from column names in the ResultSet to uPortal IPerson attribute names. -->   </entry>
     <property name="columnsToAttributes">             <map>     </map>
           <entry key="name">        </property>
            <value>name</value>        <property name="ldapServer">
       </entry>                 <entry key="shirt_color"><bean
                     <value>shirtColor</value>            class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
          </entry>                  <property name="staticMethod">
    </map>         </property>     </bean> </beans>

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>             <value>
                                    org.jasig.portal.ldap.LdapServices.getLdapServer</value>
     <bean id="personDirectory"         class="org.jasig.portal.services.persondir.support.LdapPersonAttributeDaoImpl">           <property name="ldapAttributesToPortalAttributes">
 </property>
           <map>                 <entry<property keyname="namearguments">
                    <value>name</value>            <list>
     </entry>                 <entry key="shirt_color">             <value>personLdap</value>
       <value>shirtColor</value>                 </entry>        </list>
    </map>         </property>         <property name="ldapServer">     </property>
       <bean class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">                 <property name="staticMethod"></bean>
                    <value>org.jasig.portal.ldap.LdapServices.getLdapServer</value></property>
                </property>                 <property name="arguments<property name="uidQuery">
                    <list>                         <value>personLdap<<value>(cn={0})</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>

Spring recap

Now, you might be thinking, "That makes perfect sense to me, I've seen this before because I use Spring for my other applications." If so, this way of configuration might be right for you.

LegacyPersonDirectoryToPersonAttributeDaoAdapter and PersonDirs.xml revisited

But you might be thinking, "That's really complicated. I don't like this. I'd be much happier using the old PersonDirs.xml approach to life." And if that's what you're thinking, LegacyPersonAttributeDao and the default personDirectory.xml configuration will probably be right for you.

Rolling your own

Or you might even be thinking, "I'd really rather just implement IPersonAttributeDao myself."
If you're thinking that, note that 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">/property>
                </bean>
            </list>
        </property>
    </bean>
</beans>

Custom Java implementation

...

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

As of uPortal 2.4.2, caching internal to PersonDirectory was removed. This was because the caching implementation leaked memory.