The key to session management in Jaffa is the UserSession object. This contains all the data used to maintain state for a user logged onto jaffa.

The UserSession object is an object created by Jaffa to store all context for the current User's Session. Originally this was used prior to the use of Container Security, so storing the UserId was a key piece of information. Now with container security it can be obtained from getUserPrinciple.getName(). In all cases the UserId on the UserSession and the Principle name are the same thing, and there is a new Servlet Filter (UserSessionFilter) which guarantees this.

The other useful thing the UserSession does is allow a custom JavaBean to be stored in the UserSession. This is used to hold addition application specific information about the logged in user (i.e. Name, Company Id, etc). It is the job of a custom UserSessionFilter to acquire this data, create the JavaBean, and put it in the UserSession.

Here is an example below of a welcome JSP that uses this information on a page. It assumes your custom bean is called UserBean, and it uses the org.jaffa.util.StringHelper to convert any non-HTML characters to HTML.

Welcome <%=StringHelper.convertToHtml((UserBean)UserSession.getUserSession(request).getUserData()).getUserFullName())%>

As far as the other things that the UserSession does, these are all internal management and caching functions that various parts of Jaffa use. These features include...

• Managing User Info (Id, Variation, custom Objects)
• Managing the users component pool, and component garbage collection
• Managing widget caches
• Caching Images and Files for the <Portlet:Image> widget
• Registration with the SessionManager
• Killing Sessions and Releasing Resources

Upto Jaffa v1.1 we had a 'AuthenticationManager' in the package org.jaffa.presentation.portlet.security. Its job was to make sure that the authenticated user for a request was in-sync with the current UserSession object attached to the request.

New in Jaffa v1.2 is the UserSessionFilter. It has the same job of guarenteeing that the UserSession object associated with the current request thread is valid, and contains the correct contextual information about a user.

The difference with the new filter version is firstly it requires Servlet Spec 2.3 (the other worked with 2.2), and secondly, the prevoius version only did the UserSession check when an action was invoked via 'PortletServelt'. What this meant its that if the entry to the site is via JSP, they can't assume the UserSession has been set up, until the first *.do URL has been processed. This is not good if for example you expect after log on the UserSession to be initialized, so that you can display things like 'User Name' from a custom UserData object held in the UserSession.

What does this Filter do for me?

In a nut shell, if you want to initialize the UserSession to contain context about this user, you would create a 'javabean' to store these properties, that would be then stored in UserSession via setUserData(Object data). The default version of the UserSessionFilter (found in package org.jaffa.presentation.portlet.session) just makes sure the UserSession user stays in-sync with the UserPrinicipal associated to the session. If at anypoint the filter needs to re-build the UserSession information it called the method public void initUserInfo(UserSession us). By default this method does nothing.

Customizing The Log-On Process

It is expected that developers will want to extent the class org.jaffa.presentation.portlet.session.UserSessionFilter with there own filter, and overwrite the method public void initUserInfo(UserSession us).

If you are converting a earlier implementation where you already have a custom class that has been extending org.jaffa.presentation.portlet.security.WebContainerAuthenticationManager, they this will probably already have a method for public void initUserInfo(UserSession us). This code can now be re-used by inserting it in this new custom filter. The only real difference its that the method in the new filter can throw a UserSessionSetupException to report any initialization errors.