Session Management in DFC 5.x and WDK

Introduction

Session management is an integral aspect of most client-server toolsets. Connections to remote machines are expensive to setup and teardown and operations over client-server connections are typically expensive. As a result it makes a lot of sense to limit the number of times a connection need be made and to perform data caching wherever possible to reduce communication overhead. This “extended” connection is modeled in most systems using sessions. The concept of sessions have existed in the Documentum client libraries starting with the basic DMCL and continues forth in each layer built on top of DMCL (including DFC).

Sessions in Documentum are a valuable and scarce resource. Each session requires memory on the client and the server and therefore there are a limited number of them. Historically this hasn’t been a very large issue as clients were typically single-user native applications. With the proliferation of content-based web applications, however, much larger numbers of users are connecting to docbases with each web application server servicing hundreds or thousands of users. Allocating a session to each of these users is an inefficient use of precious resources. The changes to session management in DFC 5.x aim to provide a mechanism for managing sessions that is convenient to the user of the client library while alleviating some of the burden on the server.

The DFC 4.x Mechanisms for Session Management

In DFC 4.x, session lifetime is very long. For single-user native applications this is not typically an issue. The user acquires a session and only after it has gone unused for a (relatively) long time is it collected to make system resources available for another user. A reference to the session object is typically held globally for the application. For web applications this isn’t acceptable. With tens or hundreds of users connecting to a web application server in a short period of time, system resources were rapidly exhausted. In most cases this isn’t necessary as each of these users is performing docbase activity for only brief moments (during the processing of their HTTP request).

The following example code shows a brief example of how a session (IDfSession) is acquired and used to retrieve an object from the docbase in DFC 4.x.

                
import com.documentum.fc.client.DfClient;
import com.documentum.fc.client.IDfClient;
import com.documentum.fc.client.IDfDocument;
import com.documentum.fc.client.IDfSession;
import com.documentum.fc.common.DfException;
import com.documentum.fc.common.DfLoginInfo;
import com.documentum.fc.common.IDfLoginInfo;

....

try {
	
	IDfClient dfClient = new DfClient();
	IDfLoginInfo loginInfo = new DfLoginInfo();
	loginInfo.setUser("myUserName");
	loginInfo.setDomain("myDomain");
	loginInfo.setPassword("myPassword");
	IDfSession dfSession = dfClient.newSession("myDocbase", loginInfo);
	
	IDfDocument myDocument = (IDfDocument) dfSession.getObjectByPath("/My Cabinet/My Document");
	
} catch (DfException dfe) {
	// log the error and/or do something useful
}

            

In the example, the client and the session are local to the block of code. Typically, they would be maintained globally to the application or in the case of a J2EE web application probably maintained in the HttpSession. Documentum provided no means for handling the sessions more efficiently.

Session Management in DFC 5.x

The IDfSessionManager

DFC 5.x introduced a way to more efficiently manage sessions. In order to do this, a session management abstraction was necessary and Documentum introduced the IDfSessionManager to fill this void.

The most important aspects of the IDfSessionManager are its facilities to act as an IDfSession factory and its ability to reclaim the sessions that it manufactures. This is accomplished through the methods newSession and release.

The example below is the equivalent (sanctioned) way to acquire a session and retrieve an object from the docbase using this session. The code above for DFC 4.x continues to work in DFC 5.x (ie DFC 5.x is backward compatible with respect to sessions) but this example demonstrates the correct way to do this in DFC 5.x.

                
import com.documentum.fc.client.DfClient;
import com.documentum.fc.client.IDfClient;
import com.documentum.fc.client.IDfDocument;
import com.documentum.fc.client.IDfSession;
import com.documentum.fc.client.IDfSessionManager;
import com.documentum.fc.common.DfException;
import com.documentum.fc.common.DfLoginInfo;
import com.documentum.fc.common.IDfLoginInfo;

...

IDfClient dfClient = null;
IDfSessionManager dfSessionManager = null;
IDfSession dfSession = null;
try {
	dfClient = new DfClient();
	dfSessionManager = dfClient.newSessionManager();
	
	IDfLoginInfo loginInfo = new DfLoginInfo();
	loginInfo.setUser("myUserName");
	loginInfo.setDomain("myDomain");
	loginInfo.setPassword("myPassword");
	dfSessionManager.setIdentity("myDocbase", loginInfo);
	
	dfSession = dfSessionManager.newSession("myDocbase");
	
	IDfDocument myDocument = (IDfDocument) dfSession.getObjectByPath("/My Cabinet/My Document");
	
} catch (DfException dfe) {
	// log the error and/or do something useful
} finally {
	if (dfSession != null) dfSessionManager.release(dfSession);
}

            

There are three differences between the DFC 5.x example and the previous DFC 4.x example.

1. Authentication information is set on the IDfSessionManager before the session is acquired by calling setIdentity.
2. Acquisition of a session (via newSession) requires only the name of the docbase.
3. The IDfSessionManager is used to release the session at the end of the example.

We’ll look at each of these in a bit more detail in the following sections.

Note: Although it is possible to use sessions as they were used in DFC 4.x, it is highly recommended to utilize the more efficient mechanisms provided in DFC 5.x. Mixing session management techniques in the same application is cause for heart ache. Don’t do it.

IDfSessionManager.setIdentity()

The session manager maintains a mapping of docbase name to authentication information. Sessions are acquired much more frequently in DFC 5.x than they were in previous versions since sessions are only kept for as long as they are needed to perform a specific operation. In the past, a reference to the session was kept for the duration of a running program so providing authentication information when acquiring the session was quite natural. With frequent session acquisition (which is promoted with the new session management techniques in DFC 5.x), it would be quite burdensome to have to provide this information each time a session is acquired.

Each docbase to which the application connects may require different authentication information. IDfSessionManager.setIdentity() may be called multiple times to build the map of docbase name to authentication information.

It’s often the case for an individual to have the same authentication information for multiple docbases within an organization. A default set of authentication information may be provided by specifying the docbase name as "*". When acquiring a new session, the specified docbase name is used to look up authentication information in the map. If no matching authentication information is found, the session manager, looks for an entry for the docbase “*” and if found, attempts to acquire a session using that authentication information.

This is shown in the following example.

                
...

dfSessionManager = dfClient.newSessionManager();

// Set the default login info
IDfLoginInfo loginInfo = new DfLoginInfo();
loginInfo.setUser("defaultUserName");
loginInfo.setDomain("defaultDomain");
loginInfo.setPassword("defaultPassword");
dfSessionManager.setIdentity("*", loginInfo);

// Set the login info for docbase "myDocbase"
loginInfo = new DfLoginInfo();
loginInfo.setUser("myDocbaseUserName");
loginInfo.setDomain("myDocbaseDomain");
loginInfo.setPassword("myDocbasePassword");
dfSessionManager.setIdentity("myDocbase", loginInfo);

// uses the specific login info provided for myDocbase
dfSession = dfSessionManager.newSession("myDocbase");

// uses the default login info provided for "*"
dfSession = dfSessionManager.newSession("otherDocbase");

...

            

The astute observer may have noticed that in order to acquire a session using newSession, you must specify the name of a docbase. Typically, the session manager is maintained globally in an application (or in the HttpSession in a web application). Along with the session manager, the application developer will need to maintain the name of the docbase to which the application is connecting. In most applications this would be managed in the same manner that the session manager is managed (global or in the HttpSession).

If the docbase name is not conveniently available in a “global” area it will need to be provided along with the session manager in order to acquire a session. It’s not unusual to pass a session manager as a method argument. This might happen if you are calling a piece of code from your web application that is not web application aware. In this case, you wouldn’t want the non-web application aware code to attempt to retrieve the session manager from the HttpSession so you would probably pass the session manager as an argument. Remember in cases like this, that you must also pass the name of the docbase.

Note: In the author’s experience, when developing interface specifications for services called from web applications, the docbase name is often forgotten from the method signatures.

IDfSessionManager.release()

The pattern of session usage is quite different in DFC 5.x than in previous versions. It follows three steps:

1. Acquire session
2. Perform operation
3. Release session (in a finally block)

With this pattern, sessions are released frequently. DFC utilizes session pooling to make the acquisition and release of sessions inexpensive but in order for session pooling to work correctly, sessions must always be released back to the pool. It is important to always release the session in a finally block to prevent an unexpected Exception or Error from leaking a session.

Note: IDfSessionManager.release() throws a java.lang.NullPointerException if you attempt to release a null session so it’s important to always check to make sure that the session is not null before you release it.

                
...

IDfSession dfSession = null;
try {
	// Step 1: Acquire session
	dfSession = dfSessionManager.newSession("myDocbase");

	// Step 2: Perform operation
	// Do some work using dfSession
	
} catch (DfException dfe) {
	// log the error and/or do something useful
} finally {
	// Step 3: Release session (in finally)
	if (dfSession != null) dfSessionManager.release(dfSession);
}

            

Objects and Sessions

With all of this session acquisition and release, how do I hang on to docbase objects if I need them for a long time? The simple answer is not to do that. With one exception, you must always have a valid session to use an object acquired from that session. Releasing a session makes that session invalid. So if you get an object from a session and then release that session, the object you have is no longer valid.

That all seems simple enough but it’s easy to get lazy and hang on to a reference to an object that you shouldn’t be using anymore. This is especially the case if you’re used to keeping long-term references to objects since that’s perfectly acceptable in DFC 4.x and before. The trickiest aspect of this deviant coding behavior is that your application may run perfectly fine written in this incorrect style.

Thankfully, there’s a way to force this bad style to break so you can catch it before it catches you. Setting the DebugSessionManager Java system property (provide -DDebugSessionManager as an argument when starting your VM) forces sessions to become invalid when they are released. Running with this flag is much less efficient because DFC can’t reuse sessions (which it normally does and is the reason the incorrect code you wrote still worked) so you don’t want to use this switch on a production system. It is highly recommended to always use this switch on development platforms, however, so you will find problems early on with the way sessions are being used.

As the author of this article it’s easy to tell you not to hang on to object references for long periods of time. As a DFC developer, it’s often not quite that easy. It’s very common to need to refer to an object over and over throughout the lifetime of your application.

Consider a simple web application that enables the updating of object attributes. The application validates the information and sets the attributes on the object. If a validation fails (trying to set a string on a numeric attribute for example), the application should display this failure to the user. The user may set attributes a couple of times before she successfully saves the changes.

If you have been reading between the lines a little, you have probably realized that to implement this simple little application, you need to maintain state across HTTP requests. Coming from a DFC 4.x world, your first though may be to get a reference to the object when the application initializes and keep a reference to it across HTTP requests. This isn’t a valid approach in DFC 5.x because you should be acquiring the session via a session manager and releasing it (at the very least) at the end of each HTTP request. As described above, a reference to an object obtained using one of these “transient” sessions is not valid once the session has been released.

The application developer must therefore retrieve the object on each request. Typically this would be done via object ID. Each time you retrieve an object this way from a new session, the information is loaded from the docbase. Any state set on the object during a previous HTTP request which was not saved (via IDfPersistentObject.save() or IDfSysObject.checkin()) will not exist on the newly retrieved object.

This makes the application somewhat more complicated to write than in the DFC 4.x world in which you can use the DFC object to store state that hasn’t been saved across HTTP requests. This inconvenience is the price you pay for better scalability.

IDfTypedObject.setSessionManager()

This poorly named method provides an optional solution to the transient state problem described above. This method dissociates a DFC object from its session. This method copies all of the state associated with the underlying DMCL object into the Java object (DFC usually operates in a pass-through mode in which all methods are delegated to the underlying DMCL object). The DFC object is now valid without a valid session. When an operation is performed which requires a session (such as save()), the DFC object uses the associated session manager to acquire a session and perform the operation.

Note: This is an expensive operation as it copies all state to the Java object. The method has a peculiar name because it was never really intended to be a feature of DFC. It was added as a convenience for an internal Documentum application developer and ended up becoming part of the published DFC API. Whether to manage an application-specific state mechanism across calls or to use the dissociative IDfTypedObject.setSessionManager() method depends on what the application is doing. In many cases, it’s probably fine to use IDfTypedObject.setSessionManager(). The author typically shies from this approach in lieu of a more application-specific state management technique based upon the recommendation of the DFC development team.

WDK Session Mangement

The changes to session management in DFC 5.x were made primarily to improve the scalability of web applications supporting hundreds or thousands of concurrent users. The development of the WDK application toolkit was the primary driver for this feature and as such WDK makes use of the new DFC 5.x session management features. The specifics of what is going on inside WDK are hidden from the application developer by a couple of simple-to-use interfaces but it’s often useful to understand what is going on under the covers in order to make sense of what is happening in your application.

WDK bahaves just as the theoretical web application that was described earlier. An IDfSessionManager is stored in the HttpSession. Although the session manager is not meant to be retieved from the HttpSession directly by the user (it should be retrieved via the com.documentum.web.formext.session.SessionManagerHttpBinding interface), it works just like the simple web application described above. If a session is needed for an HTTP request, it is acquired from the IDfSessionManager and released at the end of the request (unless it is acquired for the entire session as we’ll see in Component.getDfSession).

com.documentum.web.formext.session.SessionManagerHttpBinding

SessionManagerHttpBinding is the mechanism used to retrieve the session manager in a WDK application. In components there is a convenience method as we’ll see below but in actions or other non-component WDK code, SessionManagerHttpBinding is the mechanism to get the session manager and the docbase name which are used to acquire a session.

Note: Remember that the session acquired using the session manager obtained from SessionManagerHttpBinding.getSessionManager() must be released back to the session manager as soon as possible. Do not retain it across Http requests.

You may have noticed that SessionManagerHttpBinding has static methods for obtaining the session manager and the docbase name. You may have also noticed that these methods do not take an HttpSession as an argument. That’s a convenience since you may not have access to an HttpSession (such as from within a WDK action). Behind the scenes, the SessionManagerHttpBinding is pulling the session manager from the HttpSession. It accomplishes this by mapping the current thread to a particular HTTP request which it uses to get the HttpSession.

This solves the common case nicely but it is problematic if you are executing multi-threaded code within your request processing code (unusual) as the SessionManagerHttpBinding only works for the request servicing thread. This isn’t typically an issue and you can always obtain the session manager using the SessionManagerHttpBinding and pass it to any thread you spawn but there’s nothing in the interface that indicates that you need to do this so it’s something to be aware of.

Note: The author has also run across code that was originally written for use in a WDK application which later migrated to a non-WDK environment (ie. into a docbase method running in the method server). This code which was attempting to obtain a session manager using the SessionManagerHttpBinding obviously failed but there is nothing in the interface that requires an HttpSession so it’s possible to unknowingly use SessionManagerHttpBinding to retrieve a session manager from an HttpSession that is non-existent (of course it fails at runtime but the code will compile). You wouldn’t normally have WDK libraries on your method server but the author has seen it done so it’s something to watch out for. As a rule, obtain your session manager as close to components, actions, etc as possible and pass it on to other code rather than having that other code use the SessionManagerHttpBinding.

Component.getDfSession()

Much of the code written in WDK applications is in the implementation of components. And here, more than any other place is where sessions are needed. Conveniently, com.documentum.web.formext.component.Component provides Component.getDfSession() and Component.getDfSession(int sessionLifetime) to facilitate acquiring a session. Internally to Component, the session manager and docbase name is obtained using the SessionManagerHttpBinding class. As an added bonus, sessions obtained via calls to Component.getDfSession() are automatically released when the component completes rendering so there is no need to explicitly release the session. Sweet!

Of course that convenience comes at the expense of obscuring what is happening behind the scenes so it’s important to remember when calling the Component.getDfSession() methods that you must not hang on to objects obtained from those sessions for longer than the session’s lifetime.

Session’s lifetime? The authors of WDK realized that it is not uncommon for application developers to want to get a session for longer than a request. Component.getDfSession(int sessionLifetime) may take Component.REQUEST_LIFETIME or Component.COMPONENT_LIFETIME as an argument. REQUEST_LIFETIME is just what you would expect and is how you would typically write a web application. The session is good for that request only at which time it is released. This is the most efficient mechanism but is unfortunately not the default behavior.

COMPONENT_LIFETIME stores the session on the component and it is not released until the component’s lifetime ends (which could be a long time). This has the added benefit of allowing the application developer to store references to objects obtained from that session on the component and utilize them across requests but that’s a heavy price to pay indeed. Consider managing your own state or using IDfTypedObject.setSessionManager if you need to do this because sessions are very expensive in a multi-user web application environment.

Note: Component.getDfSession() calls Component.getDfSession(Component.COMPONENT_LIFETIME) so always use Component.getDfSession(Component.REQUEST_LIFETIME) whenever possible. The convenience method in this case is convenient indeed, but leads to inefficient code. Specifying the extra argument is easy to forget but the little bit of extra thought required to get a request-scoped session will be effort well spent when it comes time to performance test and tune your application.

Conclusion

This article covered the basics of session management in DFC 5.x and how those changes are exposed for use in the WDK toolkit. Follow these simple rules and your applications will behave correctly and be far more scalable than in DFC 4.x:

• Always release your sessions (in a finally)
• Don’t use objects obtained from a session which has been released
• Use the DebugSessionManager Java system property in development environments
• Always call Component.getDfSession(Component.REQUEST_LIFETIME) whenever possible instead of Component.getDfSession()