The <session> Element

The <session> element contains configuration information for a TopLink session. It includes several tags that specify the options for the session. The Sessions XML file normally contains at least one <session> element, and can include several if required by the application.

The <session> supports the configuration tags listed in Table B-1.

Table B-1 Tags within the <session> Element

Tag	Description
<name>	Specifies the name of the session. You must assign each session in the Sessions XML file a unique name to enable the SessionManager to retrieve them correctly.The <name> tag is mandatory.
<project-class>	Specifies the name of the class that contains the TopLink project metadata. Use this tag (and not the <project-xml> tag) to deploy a project that uses exported and compiled Java code.Specify the fully qualified Java class name, but do not include the .class or .java extension.
<project-xml>	Specifies the name of the XML file that contains the TopLink project metadata. Use this tag (and not the <project-class> tag) to deploy your project that uses an exported XML file. Specify the fully qualified file name, including the .xml extension.

Example B-2 Using a Project Class

<toplink-configuration>
    <session>
        <name>mysession</name>
        <project-class>com.mycompany.MyProject</project-class>
        ...
    </session>
</toplink-configuration>

Example B-3 Using Project XML

<toplink-configuration>
    <session>
        <name>mysession</name>
        <project-xml>C:/myproject/myproject.xml</project-xml>
        ...
    </session>
</toplink-configuration>

In addition to these tags, the <session> element includes several tags that contain session configuration information. These include:

The <session-type> Element

The <session-type> element appears inside of a <session> element, and specifies the session type with the following tags:

Table B-2 Tags within the <session-type> Element

Tag	Description
<session-type>	Specifies the type of TopLink session the SessionManager will instantiate. Valid options include <server-session/> and <database-session/>.The <session-type> tag is mandatory.
<server-session/>	Used in the project-type element to indicate that the SessionManager should instantiate and return the named session as a ServerSession (Server).
<database-session/>	Used in the project-type element to indicate that the SessionManager should instantiate and return the named session as a DatabaseSession.

Example B-4 Defining a ServerSession

Example B-5 Defining a DatabaseSession

<session>
    <name>myDatabaseSession</name>
    <project-class>com.mycompany.MyProject</project-class>
    <session-type>
        <database-session/>
    </session-type>
    ...
</session>

The <login> Element

The <login> element is optional for the session. If you do not include the <login> element in the Sessions XML file, you must set a default login in the TopLink Mapping editor.

Table B-3 Basic Configuration Tags Within the <login> Element

Tag	Description
<driver-class>	Specifies the JDBC driver class to log in to the database. The <driver-class> tag is optional, and is not required when you implement the <data-source> tag.
<connection-url>	Specifies the JDBC connection URL for the database. This tag is optional. Do not use the <connection-url> tag if you implement the <data-source> tag.
<data-source>	Specifies the DataSource name if you are using a JNDI DataSource.This tag is optional. Do not use the <data-source> tag if you implement the <connection-url> and <driver-class> tag.
<platform-class>	Specifies the TopLink platform class for the session. This tag is optional.
<user-name>	The username to log into the database. The <user-name> tag is optional, and is not required if you use a DataSource.
<password>	The password to log into the database. The <password> tag is optional, and is not required if you use a DataSource.

Example B-6 Basic Configuration Using JDBC

<session>
  <name>myServerSession</name>
  <project-class>com.mycompany.MyProject</project-class>
  <session-type>
    <server-session/>
  </session-type>
  <login>
    <license-path>C:/myproject/license/</license-path>
    <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
    <connection-url>jdbc:oracle:thin@dbserver:1521:dbname</connection-url>
    <platform-class>oracle.toplink.internal.databaseaccess.OraclePlatform</platform-class>
    <user-name>scott</user-name>
    <password>tiger</password>
  </login>
...
</session>

Example B-7 Basic Configuration Using a DataSource

<session>
  <name>myServerSession</name>
  <project-class>com.mycompany.MyProject</project-class>
  <session-type>
    <server-session/>
  </session-type>
  <login>
    <data-source>jdbc/MyApplicationDS</data-source>
    <platform-class>oracle.toplink.internal.databaseaccess.OraclePlatform</platform-class>
  </login>
...
</session>

Optional <login> tags

The <login> element offers several optional tags that enable you to customize your session login. Optional <login> tags typically accept TRUE or FALSE as valid values. Table B-4 describes these tags.

Table B-4 Optional Tags Within the <login> Element

Tag	Description
<should-bind-all-parameters>	Enables parameter binding for all parameters. Use parameter binding with statement caching. The default value is FALSE.
<should-cache-all-statements>	Enables statement caching. The default value is FALSE.Statement caching requires you to set the.<should-bind-all-parameters> tag to TRUE.
<uses-byte-array-binding>	Specifies whether TopLink uses binding for byte arrays. The default value is FALSE.
<uses-string-binding>	Specifies whether TopLink uses binding for String objects. The default value is FALSE.
<uses-streams-for-binding>	Specifies whether TopLink uses streams for binding byte array parameters. The default value is FALSE.
<should-force-field-names-to-uppercase>	Specifies whether TopLink converts field names to uppercase when generating SQL. The default value is FALSE.
<should-optimize-data-conversion>	Specifies whether the session should optimize driver-level data conversion. The default value is TRUE.
<should-trim-strings>	Specifies whether TopLink removes any trailing white spaces from the end of strings. The default value is TRUE.
<uses-batch-writing>	Specifies whether the session uses batch writing to write to the database. The default value is FALSE.
<uses-jdbc20-batch-writing>	Specifies whether the sessions database connection(s) uses JDBC 2.0 batch writing or TopLink batch writing. The default value is TRUE.If you enable this option, you must enable the <uses-batch-writing> option as well.
<uses-external-connection-pool>	Specifies whether the session uses external connection pooling. The default value is FALSE.
<uses-native-sql>	Specifies whether the session uses database-specific SQL grammar. The default value is FALSE.
<uses-external-transaction-controller>	Specifies whether the session uses an external transaction controller. The default value is FALSE.
<non-jts-connection-url	Specifies the URL for sequencing connection pooling. Used in conjunction with the <non-jts-datasource> tag when you set the <uses-sequence-connection-pool> tag to TRUE.
<non-jts-datasource>	Specifies the non-JTS DataSource for the sequencing connection pool. Used in conjunction with the <non-jts-connection-url> tag when you set the <uses-sequence-connection-pool> tag to TRUE.
<uses-sequence-connection-pool>	Specifies whether the session should create and use a separate connection pool for sequencing. The default value is FALSE. If you set this element to TRUE, you must also configure the <non-jts-connection-url> and <non-jts-datasource> tags.

The Login element offers two other optional tags:

<encryption-class-name> - Specifies the name of the custom class used to encrypt and decrypt the password.
<encrypted-password> - Specifies the encrypted password.

Sequencing Elements

You can configure sequencing as part of the session login, although it is not a requirement. If you do not configure sequencing in the Sessions XML file, the application uses the configuration specified in the TopLink Mapping editor.

Configure sequencing in Sessions XML when you want to use custom sequencing for a given session.

Table B-5 lists the elements you use to configure sequencing in the Sessions XML file. All of these elements are optional.

Table B-5 Optional Sequencing Configuration Tags Within <login>

Tag	Description
<uses-native-sequencing>	Specifies whether the session uses native sequencing. This tag accepts TRUE or FALSE as values. The default is FALSE. Note that not all database platforms support native sequencing.
<sequence-preallocation-size>	Specifies the sequence preallocation size. If you use native sequencing, This value must match the sequence preallocation size set on your database. The default value is 50
<sequence-table>	For table sequencing, specifies the name of the sequencing table. The default name is SEQUENCE.
<sequence-name-field>	For table sequencing, specifies the column in the sequencing table that contains the names of the sequenced objects.The default name is SEQ_NAME.
<sequence-counter-field>	For table sequencing, specifies the column in the sequence table that stores the current sequence count for each sequenced object.The default name is SEQ_COUNT.

See "Sequencing" for more information.

Example B-8 Configuring Native Sequencing

<session>
    <login>
...
        <uses-native-sequencing>true</uses-native-sequencing>
        <sequence-preallocation-size>50</sequence-preallocation-size>
    </login>
...
</session>

Example B-9 Configuring Table-Based Sequencing

<session>
...
    <login>
        <uses-native-sequencing>false</uses-native-sequencing>
        <sequence-table>SEQUENCE</sequence-table>
        <sequence-name-field>SEQ_NAME</sequence-name-field>
        <sequence-counter-field>SEQ_COUNT</sequence-counter-field>
    </login>
...
</session>

The <cache-synchronization-manager> Element

You configure cache synchronization as part of the <login>. Use the <cache-synchronization-manager> element and the tags listed in Table B-6 to configure cache-synchronization for your application.

Table B-6 Cache Synchronization Manager Configuration Tags

Tag	Description
<clustering-service>	Specifies the class name of the clustering service. This tag is required for cache synchronization.
<multicast-port>	Specifies the port for listening for connection messages over IP multicast. Ensure that all servers in your TopLink cache synchronization group use the same multicast port. This tag is required only if you also use the <multicast-group-address> element. The default value is 6018.
<multicast-group-address>	Specifies the IP address for sending connection messages over IP multicast. Ensure that all servers in your TopLink cache synchronization group use the same multicast address.This tag is required only if you also use the <multicast-port> element. The default value is 226.18.6.18.
<packet-time-to-live>	Specifies the number of network hops that cache synchronization discovery packets traverse.This optional tag defaults to 2.
<is-asynchronous>	Specifies whether cache synchronization is performed asynchronously (TRUE) or synchronously (FALSE). This optional tag defaults to TRUE.
<should-remove-connection-on-error>	Specifies whether TopLink removes a remote connection if a communications exception occurs with a remote server. This optional tag defaults to FALSE.
<jndi-user-name>	Specifies the username to use for binding the Cache Synchronization Manager into JNDI. Use this tag to support JNDI in non-application server applications. This optional tag requires the <jndi-password> tag.
<jndi-password>	Specifies the password used for binding the Cache Synchronization Manager into JNDI. Use this tag to support JNDI in non-application server applications. This optional tag requires the <jndi-user-name> tag.
<jms-topic-connection-factory-name>	Specifies the topic connection factory name for JMS cache synchronization. This tag is required only when you use JMS cache synchronization.
<jms-topic-name>	Specifies the topic name for JMS cache synchronization. This tag is required only when you use JMS cache synchronization.
<naming-service-initial-context-factory-name>	Specifies the initial context factory for accessing JNDI. Use this tag only if TopLink encounters difficulties connecting to JNDI or JMS.
<naming-service-url>	Specifies the URL of the naming service that supports cache synchronization. The value for this element depends on how you implement cache synchronization: For JNDI clustering services, this is the scheme, host IP address and port of the JNDI service. For the RMI clustering service, this is the host IP address and port of the RMI registry. This optional tag may resolve problems that occur when you implement cache synchronization inside an application server with a JNDI clustering service. If you do not encounter any problems, do not use this tag.

Example B-10 Using the Cache Synchronization Manager

<session>
...
  <login>
    <cache-synchronization-manager>
      <clustering-service>oracle.toplink.remote.rmi.RMIClusteringService</clustering-service>
      <multicast-port>6020</multicast-port>
      <multicast-group-address>226.18.6.18</multicast-group-address>
      <is-asynchronous>true</is-asynchronous>
      <should-remove-connection-on-error>true</should-remove-connection-on-error>
      <naming-service-url>localhost:1099</naming-service-url>
    </cache-synchronization-manager>
  </login>
...
</session>

The <event-listener-class> Element

If your applications needs to know when session events take place, you can use event listeners to register for event notification. You can configure event listeners in the Sessions XML file.

The <event-listener-class> tag enables you to configure listener classes that either implement the oracle.toplink.sessions.SessionEventListener interface, or extend the oracle.toplink.sessions.SessionEventAdapter class. You can configure multiple event listener classes by including multiple <event-listener-class> tags, and specifying the implementing class name for each tag.

Example B-11 Setting the Event Listener Class in Code

package examples;
import oracle.toplink.sessions.*;
public class MyEventListener extends SessionEventAdapter {
    public void preLogin(SessionEvent event) {
        Session session = event.getSession();
        /* custom code goes here */
    }
}

Example B-12 Setting the Event Listener Class in Sessions XML:

<session>
    ...
    <event-listener-class>examples.MyEventListener</event-listener-class>
    ...
</session>

TopLink registers the examples.MyEventListener class with the SessionEventManager for the session. TopLink invokes the MyEventListener class preLogin method when the preLogin event occurs on the session.

The <profiler-class> Element

TopLink provides a profiler that you can use to optimize your application and identify performance bottlenecks. To implement the performance profiler, use the <profiler-class> tag to include the performance profiler in your session.

Example B-13 Implementing the Performance Profiler in Sessions XML

<session>
    ...
    <profiler-class>oracle.toplink.tools.profiler.PerformanceProfiler</profiler-class>
    ...
</session>

The <profiler-class> tag supports any class that implements the oracle.toplink.sessions.SessionProfiler interface. Because of this, you can build your own profiler and add it to your session, provided your profiler implements the oracle.toplink.sessions.SessionProfiler interface.

Note: You can implement only one profiler per session.

The <external-transaction-controller-class> Element

If your system includes external transactions (under JTA, for example), specify a TopLink external transaction controller using the <external-transaction-controller-class> tag.

To use an external transaction controller, you must specify the following in the session login:

The external transaction controller
A DataSource on the session
An external connection pool
Example B-14 Configuring the External Transaction Controller
<session>
    ...
    <login>
        ...
        <uses-external-transaction-controller>true</uses-external-transaction-controller>
        <data-source>jdbc/MyApplicationDS</data-source>
        <uses-external-connection-pool>true</uses-external-connection-pool>
        ...
    </login>
    <external-transaction-controller-class>oracle.toplink.jts.oracle9i.Oracle9iJTSExternalTransactionController</external-transaction-controller-class>
    ...
</session>

The <exception-handler-class> Element

The <exception-handler-class> tag specifies a class that handles exceptions for the session. This tag accepts any class that implements the oracle.toplink.exceptions.ExceptionHandler.

Example B-15 Configuring the Exception Handler in Code

package examples;
import oracle.toplink.exceptions.*;
public class MyExceptionHandler implements ExceptionHandler {
   public Object handleException(RuntimeException exception) {
      /*custom code goes here */
   }
}

Example B-16 Configuring the Exception Handler in the Session XML File

<session>
  ...
  <exception-handler-class>examples.MyExceptionHandler</exception-handler-class>
  ...
</session>

The <connection-pool> Element

You can explicitly configure a single connection pool or multiple connection pools for your TopLink application with the <connection-pool> element in the Sessions XML file. If you do not configure a connection pool for a session, the session uses the default connection pool you defined for the project.

For more information on configuring the connection pool for the project, see "Working with Connection Pools" .

You must define a login for each <connection-pool> you define manually. For information on configuring a login, see "The <login> Element" .

Table B-7 <connection-pool> Element Tags

Tag	Description
<is-read-connection-pool>	Specify if the connection pool contains read connections (true) - (non-transactional) or for write connections (false) - (transactional). The <is-read-connection-pool> tag is mandatory, and accepts TRUE or FALSE as values.
<name>	Specify the name of the connection pool. If the name is the same as another existing TopLink connection pool (such as the default TopLink read pool), the existing connection pool will be replaced with the new one. The <name> tag is mandatory.
<max-connections>	Specify the maximum number of database connections that the connection pool can use. This optional tag accepts integer values, and defaults to 10.
<min-connections>	Specify the minimum number of database connections that the connection pool should use at startup. This optional tag accepts integer values, and defaults to 5.

Example B-17 Configuring the Connection Pool Element

<session>
...
    <connection-pool>
        <is-read-connection-pool>true</is-read-connection-pool>
        <name>additionalReadPool</name>
        <max-connections>20</max-connections>
        <min-connections>10</min-connections>
        <login>
        ...
        </login>
    </connection-pool>
...
</session>

The <enable-logging> Element

TopLink does not automatically enable logging for a session unless you explicitly request it. To enable logging in a sessions, include the <enable-logging> element as part of your session definition in the Sessions XML file.

To enable logging, include the <enable-logging> element, and set it to TRUE. After you enable logging, you can customize the logging behavior on the session by including one or more logging options in the Sessions XML file. The available logging options appear in Table B-8, and accept TRUE or FALSE as arguments.

Table B-8 <enable-logging> Option Tags

Tag	Description
<log-debug>	Specifies whether the session logs debug information in addition to standard log entries.
<log-exceptions>	Specifies whether the session logs uncaught exception messages.
<log-exception-stacktrace>	Specifies whether the session logs exception stack traces.
<print-session>	Specifies whether the session logs session identifiers.
<print-thread>	Specifies whether the session logs thread identifiers.
<print-connection>	Specifies whether the session logs connection identifiers.
<print-date>	Specifies whether the session logs the date and time of each log entry.

Example B-18 Configuring Logging and Logging Options

<session>
    ...
    <enable-logging>true</enable-logging>
    <logging-options>
        <log-debug>false</log-debug>
        <log-exceptions>true</log-exceptions>
        <log-exception-stacktrace>true</log-exception-stacktrace>
        <print-session>true</print-session>
        <print-thread>false</print-thread>
        <print-connection>true</print-connection>
        <print-date>true</print-date>
    </logging-options>
    ...
</session>