Session Manager

The OracleAS TopLink session manager enables you to build a series of sessions that are maintained under a single entity. The session manager is a static utility class that loads OracleAS TopLink sessions from the sessions.xml file, caches the sessions by name in memory, and provides a single access point for OracleAS TopLink sessions.

The session manager supports the following session types:

ServerSession (see "Server Session and Client Session" )
DatabaseSession (see "Database Session" )
SessionBroker (see "Session Broker" )

The session manager has two main functions: It creates instances of these sessions, and it ensures that only a single instance of each named session exists for any instance of a session manager.

Instantiate the session manager as follows:

SessionManager.getManager()

This section describes techniques for working with the session manager and includes discussions of the following topics:

Retrieving a Session from a Session Manager
Storing Sessions in the Session Manager Instance
Destroying Sessions in the Session Manager Instance

Retrieving a Session from a Session Manager

OracleAS TopLink maintains only one instance of the session manager class. The singleton session manager maintains all the named OracleAS TopLink sessions at runtime. When an application requests a session by name, the session manager retrieves the specified session from the configuration file.

To access the session manager instance, invoke the static getManager() method on the oracle.toplink.tools.sessionmanagement.SessionManager class. You can then use the session manager instance to load OracleAS TopLink sessions.

Example 4-23 Loading a Session Manager Instance

import oracle.toplink.tools.sessionmanagement.SessionManager;
SessionManager sessionManager = SessionManager.getManager();

OracleAS TopLink uses a class loader to load the session manager. The session manager, in turn, uses that same class loader to load named sessions that are not already initialized in the session manager cache.

Note:

To fully leverage the methods associated with the session type that is being instantiated, cast the session that is returned from the getSession() method. This type must match the session type that is defined in the sessions.xml file for the named session.

Example 4-24 Loading a Named Session from Session Manager Using Defaults

/* This example loads a named session (mysession) defined in the sessions.xml file. */
SessionManager manager = SessionManager.getManager();
Server server = (Server) manager.getSession("myserversession");

Loading a Session with an Alternative Class Loader

You can use an alternative class loader to load sessions. This is common when your OracleAS TopLink application integrates with a J2EE container. If the session is not already in the session manager in-memory cache of sessions, the session manager creates the session and logs in.

Example 4-25 Loading a Session Using an Alternative Class Loader

/* This example uses the specified ClassLoader to load a session (mysession) defined in the sessions.xml file. */
ClassLoader classLoader = YourApplicationClass.getClassLoader();
SessionManager manager = SessionManager.getManager();
Session session = manager.getSession("mysession", // session nameclassLoader);
// classloader

Loading an Alternative Session Configuration File

You can use the XML Loader to load any XML configuration file on the application classpath. This enables you to use files other than the standard sessions.xml file to load sessions.

You can use the XML loader to load different sessions, and even different class loaders, from configuration files. The XMLLoader class defines two constructors:

The zero-argument constructor loads the default sessions.xml file.
The single argument constructor includes a parameter (a String) that specifies an alternative configuration file.

Example 4-26 Loading an Alternative Configuration File

/* XMLLoader loads the toplink-sessions.xml file */
XMLLoader xmlLoader = new XMLLoader("toplink-sessions.xml");
ClassLoader classLoader = YourApplicationClass.getClassLoader();
SessionManager manager = SessionManager.getManager();
Session session = manager.getSession(
    xmlLoader, // XML Loader
    "mysession", // session name
    classLoader); // classloader

Reusing the Configuration File

If your application maintains the XML loader instance, then OracleAS TopLink reads sessions from the configuration file with the first getsession(), but does not reparse the file with each subsequent getsession() calls. If OracleAS TopLink uses a different XML loader to call a session, or if you invoke the API to refresh the configuration file, then OracleAS TopLink reparses the configuration file, but sessions already in the session manager do not change.

Opening Sessions without Logging In

The XML loader enables you to call a session using getSession(), without invoking the login() method. This enables you to prepare a session for use and leave login to the application.

Example 4-27 Open Session with No Login

SessionManager manager = SessionManager.getManager();
Session session = manager.getSession(
    new XMLLoader(), // XML Loader (sessions.xml file)
    "mysession", // session name
    YourApplicationClass.getClassLoader(), // classloader
    false, // log in session
    false); // refresh session

Reparsing the Session Configuration File

The XML loader can force OracleAS TopLink to reparse the session configuration file for sessions that do not exist in its in-memory cache. This function is useful when you want to add a session to an in-production sessions.xml file that already exists in the session manager cache. When the session manager attempts to load a session that is not in its in-memory cache, it reparses the XML file.

Example 4-28 Forcing a Reparse of the sessions.xml File

//In this example, the XML loader loads the sessions.xml file from the classpath. 
SessionManager manager = SessionManager.getManager();
Session session = manager.getSession(
    new XMLLoader(), // XML Loader (sessions.xml file)
    "mysession", // session name
    YourApplicationClass.getClassLoader(), // classloader
    true, // log in session
    true); // refresh session

Storing Sessions in the Session Manager Instance

You can manually create a session in your application, rather than loading a preconfigured session from the session configuration file. Use the SessionManager class as a singleton to store the manually created session. Use the getSession() API with the single String [session name] argument on session manager to load the session.

Note:

The getSession() API is not necessary if you are loading sessions from a session configuration file.

Example 4-29 Storing Sessions Manually in the Session Manager

// create and log in session programmatically
Session theSession = project.createDatabaseSession();
theSession.login();
// store the session in the SessionManager instance
SessionManager manager = SessionManager.getManager();
manager.addSession("mysession", theSession);
// retrieve the session
Session session = SessionManager.getManager().getSession("mysession");

Destroying Sessions in the Session Manager Instance

The Session Manager offers two utility methods for destroying stored sessions.

Example 4-30 Destroying Sessions in the Session Manager

// create and log in session programmatically
Session theSession = project.createDatabaseSession();
theSession.login();
// store the session in the SessionManager instance
SessionManager manager = SessionManager.getManager();
manager.addSession(ÒmysessionÓ, theSession);
…
// destroying the session
// this will throw a validation exception if the session name
// is not found
manager.destroySession(ÒmySessionÓ);

OR

// if multiple sessions have been stored and all need to be 
// destroyed, then use the destroyAllSessions API
manager.destroyAllSessions();