Session management. Misconceptions

In 2011 EMC published a funny whitepaper about session management, actually, this whitepaper is full of misconceptions and was already outdated at the moment of publishing, some examples:

Original quote:

It is not recommended to use the IDfSession.disconnect() method to disconnect a session. A session must always be released with the same session manager release() method through which the session was acquired. The IDfSessionManager.release() method performs additional tasks such as closing related sessions or sub-connections, aborting unfinished session transactions, and so on.


com.documentum.fc.client.IDfSessionManager#release calls com.documentum.fc.client.IDfSession#disconnect, so there is no difference between release() and disconnect() calls.

Original quote:

A Session Listener allows a developer to execute customized code during session creation and release. The developer must write a custom listener class that implements the IDfSessionManagerEventListener interface and defines the onSessionCreate() and onSessionDestroy() methods. The developer can then register the custom listener class with the session manager using the IDfSessionManager.setListener() method.


If you are going to use this capability (for example I like to do something like:

public static final String APPLICATION_CODE_ATTR = "application_code";

public void onSessionCreate(IDfSession session) throws DfException {
    setApplicationCode(session, "some value");
private void setApplicationCode(IDfSession session, String value) throws DfException {
    IDfTypedObject sessionConfig = session.getSessionConfig();
    if (StringUtils.isNotBlank(value)) {
        value = value.replaceAll("-", "_").replaceAll(
                "[^A-Za-z0-9_]", "");

    if (StringUtils.isBlank(value)) {

    boolean needAdd = true;
    for (int n = sessionConfig.getValueCount(APPLICATION_CODE_ATTR), i = n; i > 0; i--) {
        if (value.equals(sessionConfig.getRepeatingString(
                APPLICATION_CODE_ATTR, i - 1))) {
            needAdd = false;
    if (needAdd) {
        sessionConfig.appendString(APPLICATION_CODE_ATTR, value);

to force content server to store some extra information in dm_aduittrail.application_code), note that com.documentum.fc.client.IDfSessionManagerEventListener#onSessionDestroy is never being called.

Original quote:

Consider a scenario where Web-based developers create a session manager for each http request and use level-1 pooling. This is an incorrect usage because level-1 pooling is scoped for every session manager but each request uses its own session manager. In addition, this approach introduces problems because requests to create a new session using a new session manager create a new socket connection and session. This approach does not reuse previous sessions created by the previous session manager. The sessions created by previous requests defined by the dfc.session.pool.expiration_interval property remain as they are, until the Session Worker Thread cleans up the sessions. As a result, the code may reach the maximum session limit when there is a heavy load of requests.


EMC forgot to say that if you are constructing new session manager on every request (currently it’s the only option to make your application thread-safe) then the only correct pattern is (note flushSessions() call):

IDfSession session = null;
IDfSessionManager sessionManager = null;
try {
	sessionManager = _dfClient.newSessionManager();
	IDfLoginInfo loginInfo = new DfLoginInfo(_userName, _password);
	sessionManager.setIdentity(_docbase, loginInfo);
	session = sessionManager.getSession(_docbase);

	// some logic

} finally {
	if (session != null) {

In this case all sessions assigned to session manager will be forcibly returned to level-2 pool or disconnected (if usage of level-2 pool is turned off, so the point “requests to create a new session using a new session manager create a new socket connection and session” is wrong too).

Original quote:

You are recommended to use the getSession() method in multithread applications that perform short-lived activities… A private session cannot be shared. Private sessions give complete control of the session state for a specific task. A private session is commonly used for a long running task.


There are no “short-lived activities” or “long running tasks” – all Documentum operations are extremely slow by design. Moreover, acquiring session by calling newSession() call is not safe if you don’t know what happens behind the scenes, for example, the usage of docbase modules derived from com.documentum.fc.client.DfSingleDocbaseModule class causes inconsistent behaviour – see how EMC completely broke session management in BPM 6.7SP1. Moreover, in general, sharing session manager instance between threads is not a good idea too – the only correct way to acquire “private” session is construct new session manager instance and call getSession().

4 thoughts on “Session management. Misconceptions

  1. Pingback: Q & A. XI | Documentum in a (nuts)HELL
  2. Hi,

    I always try to follow up your posts and most of the times it just leaves me confused because some of the conclusions drawn here are contradictory from what EMC guides say. I was currently looking into an issue where the application throws “No more available sessions” error. One of the approach that I was thinking of suggesting was using session manager to release session instead of session.disconnect that we have seen caused some issues in the past for one of our applications. Can you throw some light on this?

    Further, from what I see above – Is this always the recommended approach of getting session?
    IDfSessionManager sMgr = client.newSessionManager();
    Session = sMgr.getSession();

    Do we have any particular scenario where private session is used using “IDfSessionManager.newSession()”?
    A video from EMC architect that uses this code –


  3. Pingback: Q & A. XII | Documentum in a (nuts)HELL
  4. Pingback: Why you need dfc.session.keepalive.enable | Documentum in a (nuts)HELL

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s