Session API Connection Management

The Session API’s SessionManager is ultimately responsible for overseeing connection pool management. Connections may be reused across sessions, and in most cases, you should not need to worry about directly creating, caching, or closing connections to Cyc servers.

Normally, you should only need to close individual sessions when you are done with them; the SessionManager will close the underlying connection once there are no resources which rely upon it. However, it is possible to close the SessionManager, which will force it to close all connections.

Closing sessions

Closing a CycSession is straightforward. By default, the Cyc APIs all shall the same session within the local thread, so you can simply close the current session via the SessionManager when you are done.

In Java 7 and later, sessions implement java.lang.AutoCloseable and can be wrapped within try-with-resources statements:

try (CycSession session = CycSessionManager.getCurrentSession()) {
  // Some calls to KB API, Query API, etc...
}

// The session has been automatically closed. The next call will return a new session:
CycSession newSession = CycSessionManager.getCurrentSession();

Alternately, the current session can be manually closed via the SessionManager:

try {
  // Some calls to KB API, Query API, etc...
} finally {
  CycSessionManager.getCurrentSession().close();
}

Of course, if you happen to have a pointer to a CycSession, you can close it directly:

CycSession session = null;
try {
  session = CycSessionManager.getCurrentSession();
  // Some calls to KB API, Query API, etc...
} finally {
  if (session != null) {
    session.close();
  }
}

All of these approaches close the current session and release it from the local thread.

Once a session has been closed, the next call to CycSessionManager.getCurrentSession() will create and return a new session.

Important note: Closing a session ensures that that the SessionManager will no longer return it for the current thread, but will not necessarily close the underlying connection to the Cyc server. Such details are handled by the SessionManager, which may allow resources to be shared between sessions; closing a particular session allows the SessionManager to make better decisions about resource management.

SessionListeners

To be notified when a CycSession is closed, you can register a SessionListener:

session.addListener(new SessionListener() {
  @Override
  public void onClose(Thread closingThread) {
    // Do something
  }
});

Closing and reloading the SessionManager

When your application is about to exit, you should close the current SessionManager; this will cause it to close all CycSessions it has created, as well as all Cyc server connections which were underlying those sessions.

In Java 7 and later, SessionManagers implement java.lang.AutoCloseable and can be wrapped within try-with-resources statements:

public static void main(String[] args) throws IOException {
  try (SessionManager sessionMgr = CycSessionManager.getInstance()) {
    // Some calls to KB API, Query API, etc...
  }
}

Alternately, the SessionManager can be closed manually:

try {
  // Some calls to KB API, Query API, etc...
} finally {
  CycSessionManager.getInstance().close();
}

You may check whether a SessionManager instance is closed:

boolean closed = CycSessionManager.getInstance().isClosed();

Once a SessionManager instance has been closed, it can no longer be used to create or retrieve sessions. However, you may instruct the CycSessionManager to load a new SessionManager instance:

CycSessionManager.getInstance().close();
CycSessionManager.getInstance().isClosed(); // true
CycSessionManager.reloadInstance();
CycSessionManager.getInstance().isClosed(); // false