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.
The public IPersonAttributeDao interface methods, in turn, provide an API whereby uPortal components access user attributes.
To get the attributes into an IPerson object use the new (as of uP 2.5) setAttributes method:
PersonFactory now offers the service of RestrictedPerson creation.
An example of how to get a standard IPerson and attributes for it:
PersonDirectory as configurable facility
PersonDirectory is a uPortal customization point.
You have three basic options for configuring PersonDirectory:
You can configure purely by editing PersonDirs.xml, perhaps leveraging your existing skills with that file format. And you have a good deal of flexibility there, using LDAP and JDBC to get your attributes.
The uPortal 2.5 PersonDirectory continues to support PersonDirs.xml to configure your person attribute sources. The PersonDirs.xml language allows you to specify in the PersonDirs.xml the configuration parameters for LDAP or JDBC queries as sources of attributes, with the server configuration (database URL, username, password, driver, etc.) being configured right there. It also lets you configure queries against databases or LDAP servers that are managed by RDBMServices or LdapServices. So there's quite a bit of flexibility right there.
This means of configuration is supported in 2.5 – the new implementation even provides additional validation of PersonDirs.xml configuration data to catch problems and provide more helpful logging and exception messages.
This is a recommended approach if the PersonDirs.xml language supports everything you need.
uPortal 2.5 implements uPortal 2.4-style PersonDirs.xml-driven configuration by means of LegacyPersonAttributeDao.
Custom Java implementation
If you're most comfortable editing Java and don't want to be working with Spring XML, you can 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 can then write the custom implementation that does exactly the queries, caching, and any other behavior you need.
If you're customizing PersonDirectory behavior, Spring likely has something to offer you in terms of configuring your custom IPersonAttributeDao implementation. However, if you really want to, you can code all of your configuration directly in Java, compile it, and simply reference your implementation.
Using Spring to configure an IPersonAttributeDao implementation
You can use Spring to wire together a Java object that implements IPersonAttributeDao. This facility was added in uPortal 2.5. The remainder of this Wiki page provides further information on how this works. We expect that the provided implementations of IPersonAttributeDao will be sufficient for most uPortal deployments.
Spring and PersonDirectory
PersonDirectory is implemented using Spring. Currently a Spring beans.dtd-compliant XML file named personDirectory.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 personDirectory.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.
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.
For more examples, visit the page dedicated to JdbcPersonAttributeDaoImpl.
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.
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.
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.
As of uPortal 2.4.2, caching internal to PersonDirectory was removed in uPortal 2.4 and 2.HEAD. This was because the caching implementation leaked memory.
If you want to re-introduce caching, one way you could accomplish that would be with a caching wrapper. Such a wrapper would implement IPersonAttributeDao and be dependent upon an implementation of the same interface it implements. It would delegate to the underlying implementation, caching the results from its delegate and responding from its cache when possible. This can be a way to trade memory for performance in the case where you know exactly when your underlying attribute store (infrequently) updates.