Understanding Configurations

The OracleAS TopLink sessions configuration file (named sessions.xml, by default) is an XML (extensible markup language) file that contains all sessions associated with a project. Each OracleAS TopLink project belongs to an OracleAS TopLink session. To deploy beans that belong to different projects, add an appropriate OracleAS TopLink session (see "Working with Sessions") to the configuration.

Refer to the Oracle Application Server TopLink Application Developer's Guide for a sample sessions.xml configuration file.

Working with Configurations

The OracleAS TopLink Sessions Editor displays configurations and their contents in the Navigator pane. When you select a configuration, its attributes display in the Editor pane.

Creating New Configurations

Use this procedure to create a new OracleAS TopLink session configuration.

To Create a New Configuration:

Description of the illustration newsesbt.gif

Click the Create New Configuration button on the toolbar. The Create New Session Configuration dialog box appears.

You can also choose File > New from the menu.

Figure 8-2 New Sessions File

Description of the illustration creatses.gif

Enter the configuration Name (sessions.xml by default), select a directory Location in which to save the file, enter a default Session Name, and click OK.

The OracleAS TopLink Sessions Editor appears, showing the configuration name in the Navigator pane.
Select the configuration element in the Navigator pane. The session's General tab appears in the Editor pane (see Figure 8–5 on page 8-8.

Opening Existing Configurations

Use this procedure to open an existing session configuration.

To Open an Existing Configuration:

Open Configuration button.
Description of the illustration openbtn.gif

Click the Open Configuration button on the toolbar. The Create New Session Configuration dialog box appears.

You can also choose File > Open from the menu.

Saving Configurations

The OracleAS TopLink Sessions Editor does not automatically save your project. Be sure to save your project often to avoid losing data.

To Save Your Configuration(s):

Save button.
Description of the illustration savebtn.gif

Save All button.
Description of the illustration saveall.gif

Click the Save button or Save All button to save your project(s).

You can also choose File > Save, or File > Save All from the menu.

To Save Your Configuration with a Different Name or Location:

Description of the illustration saveasbt.gif

Click the Save As button or choose File > Save As. The Save As dialog box appears.
Browse to the directory in which to save the project. In the File Name field, type the name of the project and click Save.

Caution:
Do not rename the .xml file outside of the OracleAS TopLink Sessions Editor. Always rename a project by using the Save As option.

Working with Session Brokers

Use session brokers to allow OracleAS TopLink to access multiple databases. With a session broker, you can store the objects within one application on multiple databases.

To Create a Session Broker

Select the configuration element in the Navigator pane. The session's General tab appears in the Editor pane.

Figure 8-3 Configuration — General Property Sheet

Description of the illustration confgen.gif
Click the Sessions Broker tab. The Session Broker tab of the Session property sheet appears.

Description of the illustration sesbkbtn.gif

If the Session Broker tab is not visible for the session, click the Session Broker button on the Navigator toolbar. You can also create brokers by right-clicking on the configuration element in the Navigator pane and selecting Advanced > Session Brokers from the pop-up menu.

Figure 8-4 Configuration – Session Broker Property Sheet

Description of the illustration sesbrok.gif

Figure 8–4 calls out the following user-interface components:
1. Session Broker area
2. Sessions area (for currently selected session broker)
Click Add in the Session Broker area to create a new session broker.
To delete a session broker, select the session broker and click Remove. To rename a session broker, select the session broker and click Rename (see "Renaming Elements").

Note:
Each session broker must contain at least one session.
To create a new session, select a session broker, then click Add in the Session area to create a new session for the selected session broker.

To delete a session, select the session and click Remove. To rename a session, select the session and click Rename (see "Renaming Elements").

Working with Sessions

A OracleAS TopLink session describes how OracleAS TopLink communicates with the datasource at runtime. When using the OracleAS TopLink Sessions Editor to configure the session options, choose Default to use the values specified in the Oracle Application Server TopLink Foundation Library. Refer to the Oracle Application Server TopLink Application Developer's Guide for more information.

To create a new session:

Use one of the following methods to create a new session:

Right-click on a configuration element in the Navigator pane and choose New > Session from the pop-up menu.
Description of the illustration sessbtn.gif

Select a configuration element in the Navigator pane and click the Session button.
Create a new session for the session broker (see "Working with Session Properties").

Working with Session Properties

Each session contains tabs and specific properties. By default, sessions contain the following properties:

General
Logging

In addition, you can specify advanced properties (see "Working with Advanced Session Properties") for each session.

Setting General Properties

Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.
Click the General tab. The General property sheet appears.

Figure 8-5 Session — General Property Sheet

Description of the illustration sesgen.gif
Use this table to enter data in each field:

Field	Description
Session Type	Specify whether this is a Database or Server session (the `<session-type>` tag).
Project Type	Specify whether this is a Class or XML project (the `<project-class>` or `<project-xml>` tag).
Profiler	Specify the profiler class (the `<profiler-class>` tag).
Exception Handler	Specify the exception handler class (the `<exception-handler-class>` tag).
External Transaction Controller	Specify whether OracleAS TopLink database calls are synchronized with the container's transaction manager (the `<uses-external-transaction-controller>` tag).
Event Listeners	Name of the event listener(s) registered with the session (the `<event-listener-class>` tag). Click Add to add a new event listener.

Refer to the Oracle Application Server TopLink Application Developer's Guide for more information.

Setting Logging Properties

Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.
Click the Logging tab. The Logging property sheet appears.

Figure 8-6 Session — Logging Property Sheet

Description of the illustration seslog.gif

Use this table to enter data in each field:

Field	Description
Logging	Use these fields to specify the session logging properties. Select Default to use the logging properties specified by OracleAS TopLink.
Enable Logging	Specify whether the session logs messages (the `<enable-logging>` tag).
Logging Options	Specify whether the session logs individual message types (such as the `<log-debug>` tag).

Refer to the Oracle Application Server TopLink Application Developer's Guide for more information.

Working with Advanced Session Properties

OracleAS TopLink sessions may contain advanced properties to specify login and clustering (cache synchronization) information. Select one of the following methods to display the advanced properties:

Right-click the session in the Navigator pane and choose Advanced > Login or Clustering from the pop-up menu.
Description of the illustration loginbtn.gif

Description of the illustration cachbtn.gif

Select the session in the Navigator pane and click Login or Clustering on the Navigator pane toolbar.

Setting Login Properties

Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.
Click the Login tab. The General tab of the Login property sheet appears.

Description of the illustration loginbtn.gif

If the Login advanced property is not visible for the session, click the Login button on the Navigator toolbar.

Figure 8-7 Login Property Sheet—General Tab

Description of the illustration logingen.gif

Use this table to enter data in each field:

Field	Description
Database Driver	Name of the database driver (the `<driver-class>` tag).
Database Platform	Name of the database platform (the `<platform-class>` tag).
Username	Name used to log into the database (the `<user-name>` tag).
Encrypted Password	Password of the Username used to log into the database (the `<encrypted-password>` tag).
Encryption Class Name	When using an Encrypted Password, select the specific encryption class (the `<encryption-class-name>` tag).
Data Source Location
Data Source	Name of the data source used by the session to connect to the database (the `<datasource>` tag).
Connection URL	URL used by the session to connect to the database (the `<connection-url>` tag).
Use Non-JTS for	Specify if the session requires a non-JTS connection. Note: Normally, use this option for an application server when using cache synchronization.
Data Source	Name of the non-JTS connection (the `<non-jts-datasource>` tag).
Connection URL	URL used by the non-JTS connection (the `<non-jts-connection-url>` tag).

Click the Sequencing tab. The Sequencing tab appears.

Figure 8-8 Login Property Sheet—Sequencing Tab

Description of the illustration loginseq.gif

Use this table to enter data in each field:

Field	Description
Use Native Sequencing	Specify whether the login uses the database's native sequencing (the `<uses-native-sequencing>` tag).
Preallocation Size	Number of sequences retrieved from the database (the `<sequence-preallocation-size>` tag).
Table	Name of the sequence table (the `<sequence-table>` tag).
Name Field	Field in the sequence Table that contains the sequence name (the `<sequence-name-field>` tag).
Counter Field	Field in the sequence Table that contains the sequence counter (the `<sequence-counter-field>` tag).

Click the Options tab. The Options Login property sheet appears.

Figure 8-9 Login Property Sheet – Options Tab

Description of the illustration loginopt.gif

Use this table to enter data in each field:

Field	Description
Queries Should Bind All Parameters	Specify whether all queries should bind all parameters (the `<should-bind-all-parameters>` tag).
Cache All Statements	Specify whether OracleAS TopLink caches all statements (the `<should-cache-all-statements>` tag).
Use
Byte Array Binding	Specify whether OracleAS TopLink binds byte arrays (the `<uses-byte-array-binding>` tag).
String Binding	Specify whether OracleAS TopLink binds strings (the `<uses-string-binding>` tag).
Streams for Binding	Specify whether OracleAS TopLink uses streams when binding byte arrays (the `<uses-streams-for-binding>` tag).
Native SQL	Specify whether OracleAS TopLink uses native SQL for the connection (the `<uses-native-sql>` tag).
Batch Writing	Specify whether the connection batches statements for writing (the `<uses-batch-writing>` tag).
JDBC 2.0 Batch Writing	Specify whether the connection uses JDBC 2.0 batch writing for statements (the `<uses-jdbc20-batch-writing>` tag).
External Connection Pool	Specify whether the connection uses external connection pooling (the `<uses-external-connection-pool>` tag).
External Transaction Controller	Specify whether the session uses an external transaction controller (the `<uses-external-transaction-controller-pool>` tag).
Other Options
Force Field Name to Uppercase	Specify whether OracleAS TopLink converts all field names to uppercase when generating SQL (the `<should-force-field-names-to-uppercase>` tag).
Optimize Data Conversion	Specify whether OracleAS TopLink optimizes data conversions (the `<should-optimize-data-conversion>` tag). Note: Selecting this option may affect the how OracleAS TopLink converts dates.
Trim Strings	Specify whether OracleAS TopLink removes white space (blanks) from strings (the `<should-trim-strings>` tag).

Setting Clustering Properties

Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.
Click the Clustering tab. The Clustering property sheet appears.

Description of the illustration cachbtn.gif

If the Clustering advanced property is not visible for the session, click the Clustering button in the Navigator toolbar.

Figure 8-10 Clustering Property Sheet

Description of the illustration sescach.gif
Use this table to enter data in each field:

Field	Description
Clustering Service	Name of the clustering service used for cache synchronization (the `<clustering-service>` tag).
Multicast Port	Multicast port used by the clustering service to listen for new sessions (the `<multicast-port>` tag).
Multicast Group Address	IP address used by the clustering service to listen for new sessions (the `<multicast-group-address>` tag).
Packet Time to Live	The maximum number of hops a packet will be broadcast (the `<packet-time-to-live>` tag).
Asynchronous	Specify whether the cache manager does not require that all sessions be synchronized before returning (the `<is-asynchronous>` tag).
Remove Connection on Error	Specify whether OracleAS TopLink removes the connection from the session in case of a configuration error (the `<should-remove-on-error>` tag).
JMS Topic
Name	Specify the name of the JMS topic (the `<jms-topic-name>` tag).
Connection Factory Name	Specify the name of the JMS topic connection factory (the `<jms-topic-connection-factory-name>` tag).
Naming Service
URL	URL of the global namespace for the cache synchronization (the `<naming-service-url>` tag). Note: Normally, this is the URL of the JNDI service.
Initial Context Factory Name	Name of the element used for synchronization (the `<naming-service-initial-context-factory-name>` tag).
Use JNDI Login	Specify whether cache synchronization uses a JNDI service.
Username	Name used to log into the JNDI service (the `<jndi-user-name>` tag).
Password	Password used to log into the JNDI service (the `<jndi-password>` tag).

Refer to the Oracle Application Server TopLink Application Developer's Guide for more information.

Working with Connection Pools

OracleAS TopLink uses connection pools to manage and share the connections used by the server and client sessions among multiple clients. This feature reduces the number of connections required by the application server and allows the server to support many clients.

Description of the illustration conpolbt.gif

To create a new connection pool, right-click a session element in the Navigator pane and choose New > Connection Pool from the pop-up menu, or click the Connection Pool button.

Setting General Properties

Select the connection pool element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the connection pool's properties in the Editor pane.
Click the General tab. The General property sheet appear.

Figure 8-11 Connection Pool—General Property Sheet

Description of the illustration cpgen.gif

Use this table to enter data in each field:

Field	Description
Read Connection Pool	Specifies whether OracleAS TopLink uses a read connection pool (the `<is-read-connection-pool>` tag).
Connection Count	Specify the Minimum and Maximum read connections in the OracleAS TopLink connection pool (the `<min-connections>` and `<max connections>` tags).

Refer to the Oracle Application Server TopLink Application Developer's Guide for more information.

Setting Login Properties

Select the connection pool element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the connection pool's properties in the Editor pane.
Click the Login tab. The General tab of the Login property sheet appears. See "Setting Login Properties"