Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Acquiring a Session from the Session Manager

When the session manager loads a session that is not yet in its cache, the session manager creates an instance of the appropriate session type and configures it according to the `sessions.xml` file configuration.

Note: To best use 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.

This section explains the following:

- Loading a Session from sessions.xml Using Defaults

- Loading a Session from sessions.xml with an Alternative Class Loader

- Loading a Session from an Alternative Session Configuration File

- Loading a Session Without Logging In

- Reloading and Refreshing Session Configuration

- Refreshing a Session when the Class Loader Changes

## Loading a Session from sessions.xml Using Defaults

If you have a single sessions configuration file (`sessions.xml`) that contains all the session instances created from by TopLink Workbench, then you can load a session by name, as Example 78-2 illustrates.

Example 78-2 Acquiring a Named Session from Session Manager Using Defaults

    /* Load a named session (mysession) defined in the sessions.xml file. */
    SessionManager manager = SessionManager.getManager();
    Session session = manager.getSession("mysession");

In this example, the following session manager default configuration applies:

- Class loader–The thread-based class loader is used to find and load the `sessions.xml` resource and resolve any classes referenced in the `sessions.xml` and `project.xml` files.

  If you acquire the session in an application class, this will typically be the application's class loader, which is correct. In a J2EE application, it is best to specify this as the class loader from a class in the same JAR file that the `sessions.xml` file is deployed in.

- File–By default, the file named `sessions.xml` in the root directory relative to the class loader is used.

  If the file is named differently, or not in the root directory, the relative path must be specified. Relative resource paths in Java must use `/`, not `\`.

- Session name–The name passed into the `getSession` call.

  This name must be unique for the entire application server, not just unique within the application.

- Login–`true`. The session will be connected by default.

  If you must manually configure the session before login, set this option to `false` (see "Loading a Session Without Logging In").

- Refresh–`false`. If already loaded, the same session will be returned.

  Refresh should only be used, if it is known that the existing session is not being used, and the configuration has changed, such as in a J2EE environment redeployment scenario.

- Verify class loader–false. The session manager will not refresh the session if the class loader changes.

  This should normally be set to `true`. It must be set to `true` in a J2EE environment, if hot deployment or redeployment to a running application server is required (see "Refreshing a Session when the Class Loader Changes").

## Loading a Session from sessions.xml with an Alternative Class Loader

You can use an alternative class loader to load sessions. This is common when your TopLink application integrates with a J2EE container. The session manager uses the class loader to find and load the `sessions.xml` resource and resolve any classes referenced in the `sessions.xml` and `project.xml` files.

In most cases, you use the class loader from the current thread context, as Example 78-3 illustrates. In this example, the session named `mysession` is loaded from the first file in the application classpath named `sessions.xml` using the class loader associated with the current thread context.

Example 78-3 Loading a Session Using the Current Thread Context Class Loader

    /* Use the specified ClassLoader to load a session (mysession) defined in the sessions.xml file */
    SessionManager manager = SessionManager.getManager();
    Session session = manager.getSession(
        "mysession",  // session name to load
        Thread.current().getContextClassLoader() // ClassLoader instance to use
    );

However, if your J2EE container does not support using the current thread context class loader, you can use the class loader from the current class, as Example 78-4 illustrates.

Example 78-4 Loading a Session Using the Current Class's Class Loader

    /* Use the specified ClassLoader to load a session (mysession) defined in the sessions.xml file */
    SessionManager manager = SessionManager.getManager();
    Session session = manager.getSession(
        "mysession",  // session name to load
        this.getClass().getClassLoader() // ClassLoader instance to use
    );

Note: Oracle Containers for J2EE supports the use of the class loader from the current thread.

## Loading a Session from an Alternative Session Configuration File

If your session instances are contained in multiple, uniquely named session configuration files (`sessions.xml` files), then you must explicitly create an `XMLSessionConfigLoader` object initialized with the name of the `sessions.xml` file and pass that `XMLSessionConfigLoader` into the `SessionManager` method `getSession`, as Example 78-5 illustrates.

The file path you specify is relative to the class loader root directory. Relative resource paths in Java must use the forward slash ( `/` ), not back slash ( `\ )`.

In this example, the session named `mysession` is loaded by the specified class loader from the first file in the application classpath named `toplink-sessions.xml`.

Example 78-5 Loading a Session from an Alternative Configuration File

    /* XMLSessionConfigLoader loads the toplink-sessions.xml file */
    SessionManager manager = SessionManager.getManager();
    manager.getSession(
        new XMLSessionConfigLoader("toplink-sessions.xml"),
        "mysession",
        this.class.getClassLoader()
    );

## Loading a Session Without Logging In

The `XMLSessionConfigLoader` (see "Loading a Session from an Alternative Session Configuration File") lets you call a session using the `SessionManager` method `getSession`, without invoking the `Session` method `login`, as Example 78-6 shows. This lets you prepare a session for use and leave login to the application.

Example 78-6 Open Session with No Login

    SessionManager manager = SessionManager.getManager();
    Session session = manager.getSession(
        new XMLSessionConfigLoader(), // XMLSessionConfigLoader (sessions.xml file)
        "mysession", // session name
        YourApplicationClass.getClassLoader(), // class loader
        false, // do not log in session
        false); // do not refresh session

## Reloading and Refreshing Session Configuration

You can tell the session manager to refresh an existing session from the `sessions.xml` file. Typically, this would only ever be used in a J2EE environment at redeployment time, or after a reset of a running server. You should only use this option when you know that the existing session is not being used.

Example 78-7 Forcing a Reparse of the sessions.xml File

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

## Refreshing a Session when the Class Loader Changes

In a non-CMP J2EE environment, if you require hot deployment or redeployment to a running application server, you must tell the session manager to refresh your session if the class loader changes, as Example 78-8 shows. This option makes the session manager refresh the session if the class loader changes, which occurs when the application is redeployed. When this option is set to `true`, the same class loader must always be used to retrieve the session.

Example 78-8 Forcing a Reparse of the sessions.xml File

    //In this example, XMLSessionConfigLoader loads sessions.xml from the classpath
    SessionManager manager = SessionManager.getManager();
    Session session = manager.getSession(
        new XMLSessionConfigLoader(), // XMLSessionConfigLoader (sessions.xml file)
        "mysession", // session name
        YourApplicationClass.getClassLoader(), // class loader
        true,   // log in session
        false,  // do not refresh session when loaded
        true    // do refresh session if class loader changes
    );

In a CMP J2EE environment, the TopLink runtime and CMP integration handles this for you automatically.