|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
 Previous |
 Next |
|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
|
Previous |
Next |
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 thegetSession 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 with an Alternative Class Loader
Loading a Session from an Alternative Session Configuration File
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").
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. |
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()
);
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
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 );
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.
