C
TopLink Session Configuration File

The TopLink session configuration file, called sessions.xml, is a Java ResourceBundle that is read in using the locale. It may be necessary to rename the sessions.xml file to a locale specific name. For example TopLink_en_US.properties instead of sessions.xml.

Each TopLink project belongs to a TopLink session. To deploy beans that belong to different projects, add an appropriate TopLink session information section in the sessions.xml file as demonstrated in the Account Demo's sample

Contents of the sessions.xml file

# The XML Jar Location
XMLJarLocation = SPECIFY_JAR_LOCATION_HERE
# The TopLink session information for the beans in the Account Demo
session.YOUR_SESSION_NAME.projectClass = examples.ejb.cmp.account.AccountProject
session.YOUR_SESSION_NAME.platform = 
oracle.toplink.internal.databaseaccess.OraclePlatform
session.YOUR_SESSION_NAME.profile = false
session.YOUR_SESSION_NAME.logProfile = false
session.YOUR_SESSION_NAME.logMessages = true
session.YOUR_SESSION_NAME.logDebug = true
session.YOUR_SESSION_NAME.logExceptions = true
session.YOUR_SESSION_NAME.useExternalConnectionPooling = true
session.YOUR_SESSION_NAME.useExternalTransactionController = true
session.YOUR_SESSION_NAME.externalTransactionController = 
oracle.toplink.jts.was.WebSphereJTSExternalTransactionController
session.YOUR_SESSION_NAME.writePoolMax = 1
session.YOUR_SESSION_NAME.writePoolMin = 1
session.YOUR_SESSION_NAME.readPoolMax = 1
session.YOUR_SESSION_NAME.readPoolMin = 1
session.YOUR_SESSION_NAME.amendmentClass = 
examples.ejb.cmp.order.SessionAmendment
session.YOUR_SESSION_NAME.amendmentMethod = configureSession

This code contains the following variables:

YOUR_SESSION_NAME

The toplink_session_name environment variable set in the bean's deployment descriptor.

XMLJarLocation

The property XMLJarLocation points to the directory in which your .jar files have been saved.

projectClass

It is necessary to have a TopLink project class file. You can generate a project class file using the TopLink Session Console.

platform

The database platform. This can also be specified in the TopLink project.

• For Oracle databases set this to oracle.toplink.internal.databaseaccess.OraclePlatform

• For DB2 databases set this to oracle.toplink.internal.databaseaccess.DB2Platform

• For Sybase databases set this to oracle.toplink.internal.databaseaccess.SybasePlatform

• For SQL Server databases set this to oracle.toplink.internal.databaseaccess.SQLServerPlatform

logProfile

This flag indicates whether or not to use the profiler. The profiler can be used to log a summary of each query that is executed. This may be used during development but for optimized performance it is recommended that this be disabled during production.

logDebug

Set debug messages logging. Debug messages will be dumped through TopLink to the session's log. By default this is System.out, but can be set to any Writer.

logExceptions

Toggle exception logging.

useExternalConnectionPooling

If set to true then a DataSource must be set for the bean. This DataSource is used for all database connections. If this is set to false then TopLink uses its own internal connection pooling.

useExternalTransactionController

If set to true then TopLink database calls are synchronized with the container's "Transaction Manager".

externalTransactionController

This is specific to your application server and coordinates with the appropriate JTS. For example, for IBM WebSphere set this to oracle.toplink.jts.was
.WebSphereJTSExternalTransactionController

writePoolMax

This is set only when an external transaction controller is not being used. It indicates the maximum number of write connections in the TopLink connection pool.

writePoolMin

This is set only when an external transaction controller is not being used. It indicates the minimum/initial number of write connections in the TopLink connection pool.

readPoolMax

This is set only when an external transaction controller is not being used. It indicates the maximum number of read connections in the TopLink connection pool.

readPoolMin

This is set only when an external transaction controller is not being used. It indicates the minimum/initial number of read connections in the TopLink connection pool.

amendmentClass

The class that contains the public class that amends the session.

amendmentMethod

A public static method that takes a oracle.toplink.threetier.ServerSession as a parameter. This method is run when the TopLink session is created during bean deployment.

Converting from TOPLink.properties file to sessions.xml

The sessions.xml file is similar in function to the TOPLink.properties files from previous version of TopLink. If you are upgrading from a version of TopLink hat used the TOPLink.properties file, the following table, which identifies settings in the TopLink.properties file and their equivalents in the sessions.xml file, will be of use to you.

Table C-1 TopLink.properties and sessions.xml equivalents  

Element	TopLink.properties	sessions.xml
Session name		<toplink-configuration> <session> <name>YOUR_SESSION_NAME </name>
xml.jar location	XMLJarLocation=[INSTALL_DIR}\TopLink\core\lib\xerces.jar	not required Use SessionManager and XMLLoader API to specify the parser JAR location and options such as classloader, etc.
Project class and session name	session.YOUR_SESSION_NAME .projectClass=examples.ejb .cmp.account.AccountProject	<session> <project-class> examples.ejb.cmp.account .AccountProject </project-class> </session>
Platform class	session.YOUR_SESSION_NAME .platform=TOPLink.Private .DatabaseAccess .OraclePlatform	<login> <platform-class> oracle.toplink.internal.databaseaccess .OraclePlatform </platform-class> Note: You will need to change the existing platform class name to the new oracle.toplink.* class name. This can be done by running the package rename tool on the TOPLink.properties file.
Profiling	session.YOUR_SESSION_NAME .profile=true session.YOUR_SESSION_NAME .logProfile=true	<session> <profiler-class> oracle.toplink .profiler.PerformanceProfiler</profiler-class>
Message logging	session.YOUR_SESSION_NAME .logMessages=true session.YOUR_SESSION_NAME .logDebug=true session.YOUR_SESSION_NAME .logExceptions=true	<session> <log-messages>true </log-messages> <logging-options>    <log-debug>true </log-debug>    <log-exceptions>true    </log-exceptions> </logging-options>
External connection pooling	session.YOUR_SESSION_NAME.useExternalConnectionPooling=true	<login> <uses-external-connection-pool> true</uses-external-connection-pool>
External transaction collector	session.YOUR_SESSION_NAME .useExternalTransactionController=true session.YOUR_SESSION_NAME .externalTransactionController=oracle.toplink.jts.was.WebSphereJTSExternalTransactionController	<session> <login> <uses-external-transaction-controller>true </uses-external-transaction-controller> </login> <external-transaction-controller-class> oracle.toplink.jts.was.WebSphereJTSExternalTransactionController </external-transaction-controller-class>
Connection pooling	session.YOUR_SESSION_NAME .writePoolMax=1 session.YOUR_SESSION_NAME .writePoolMin=1 session.YOUR_SESSION_NAME .readPoolMax=1 session.YOUR_SESSION_NAME. readPoolMin=1	<session> ... <connection-pool> <is-read-connection-pool>true </is-read-connection-pool> <name>sampleReadConnectionPool</name> <min-connections>1 </min-connections> <max-connections>1 </max-connections> </connection-pool>
Amendment class and amendment method	session.YOUR_SESSION_NAME.amendmentClass=examples.ejb .cmp.order.SessionAmendment session.YOUR_SESSION_NAME.amendmentMethod= configureSession	These options are not present in the Sessions.xml for TopLink, as the Sessions.xml allows for a greater degree of control over session configuration. If you wish to customize your session in code the you may use the Session 'preLogin' event. A session event class can be specified in the Sessions.xml file to register a listener for the preLogin, and other session events. For more information on using this API, please consult your TopLink documentation.