8
Understanding the OracleAS TopLink Sessions Editor

Use the Oracle Application Server TopLink Sessions Editor to easily manage your sessions.xml file information. You can work with this file outside of the OracleAS TopLink Mapping Workbench, if necessary.

Use the sessions.xml file to configure one or more sessions for the OracleAS TopLink project, and associate the sessions with the project. This approach allows you to configure the following elements for each project:

• Database (JDBC) login information different from that used during development (for example, external data sources for the host application server's connection pools).

• JTA/JTS transaction usage

• Cache synchronization

• Session Broker (multiple databases appearing as a single OracleAS TopLink session)

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

Starting the OracleAS TopLink Sessions Editor

Use one of the following methods to start the OracleAS TopLink Sessions Editor:

• For Windows environments: From the Start menu, choose Program Files > OracleAS TopLink > Sessions Editor.

• For non-Windows environments: Execute the <ORACLE_HOME>\toplink\
bin\sessionsEditor.sh file.

The splash screen appears, followed by the OracleAS TopLink Sessions Editor window.

Working with the OracleAS TopLink Sessions Editor

The OracleAS TopLink Sessions Editor window contains similar parts as the OracleAS TopLink Mapping Workbench window (see Figure 1-2). The Navigator pane contains the project tree for all open projects (see "Using the Navigator Pane"). Click the plus or minus ( + or - ) symbol next to an object (or double-click the object) to expand and collapse the tree. When you select an object in the Navigator pane, its properties appear in the Editor pane.

Using the Navigator Pane

The OracleAS TopLink Sessions Editor displays each configuration's session and connection pool information in the Navigator pane on the left side of the editor.

Figure 8-1 Sample Navigator Pane

Text description of the illustration navpane.gif

Figure 8-1 calls out the following user-interface components:

1. Navigator toolbar (see "Using the Toolbars")

2. Configuration (refers to the <toplink-configuration> tag)

3. Session (refers to the <session> tag)

4. Connection pool (refers to the <connection-pool> tag)

5. Change indicator ( > ) - Appears beside elements that have been changed, but not yet saved.

Click the + or - symbol next to the item, or double-click the item name, to expand and collapse an item.

When you select an item in the Navigator pane, its properties appear in the Editor pane (see "Using the Editor Pane").

You can perform specific functions for an item by right-clicking the item in the Navigator pane and choosing the function from the pop-up menu. (see "Pop-Up Menus").

If a session element contains an error, a warning icon

Text description of the illustration catnicon.gif

appears beside the descriptor's icon in the Navigator pane, and a message displays in the status bar detailing the error.

Renaming Elements

To rename an element, select the element in the Navigator pane, then click the Rename

Text description of the illustration renambtn.gif

button. The Rename dialog box appears.

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 book 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:

1. Click the Create New Configuration button

   Text description of the illustration newsesbt.gif

   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

   

   Text description of the illustration creatses.gif

2. 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.

3. Select the configuration element in the Navigator pane. The session's General tab appears in the Editor pane (see Figure 8-5).

Opening Existing Configurations

Use this procedure to open an existing session configuration.

To Open an Existing Configuration:

Click the Open Configuration button

Text description of the illustration openbtn.gif

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):

Click the Save button

Text description of the illustration savebtn.gif

or Save All button

Text description of the illustration saveall.gif

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:

1. Click the Save As button

   Text description of the illustration saveasbt.gif

   or choose File > Save As. The Save As dialog box appears.

2. 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

1. 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

   

   Text description of the illustration confgen.gif

2. Click the Sessions Broker tab. The Session Broker tab of the Session property sheet appears.

   If the Session Broker tab is not visible for the session, click the Session Broker button

   Text description of the illustration sesbkbtn.gif

   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

   

   Text 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)

3. 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.

4. 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.

• Select a configuration element in the Navigator pane and click the Session 

  Text description of the illustration sessbtn.gif

  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

1. Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.

2. Click the General tab. The General property sheet appears.

   Figure 8-5 Session -- General Property Sheet

   

   Text description of the illustration sesgen.gif

3. 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

1. Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.

2. Click the Logging tab. The Logging property sheet appears.

   Figure 8-6 Session -- Logging Property Sheet

   

   Text description of the illustration sescls.gif

3. 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.

• Select the session in the Navigator pane and click Login

  Text description of the illustration loginbtn.gif

  or Clustering

  Text description of the illustration cachbtn.gif

  on the Navigator pane toolbar.

Setting Login Properties

1. Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.

2. Click the Login tab. The General tab of the Login property sheet appears.

   If the Login advanced property is not visible for the session, click the Login button

   Text description of the illustration loginbtn.gif

   on the Navigator toolbar.

   Figure 8-7 Login Property Sheet--General Tab

   

   Text description of the illustration logingen.gif

3. 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).

4. Click the Sequencing tab. The Sequencing tab appears.

   Figure 8-8 Login Property Sheet--Sequencing Tab

   

   Text description of the illustration loginseq.gif

5. 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).

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

   Figure 8-9 Login Property Sheet - Options Tab

   

   Text description of the illustration loginopt.gif

7. 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

1. Select the session element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the session's properties in the Editor pane.

2. Click the Clustering tab. The Clustering property sheet appears.

   If the Clustering advanced property is not visible for the session, click the Clustering button

   Text description of the illustration cachbtn.gif

   in the Navigator toolbar.

   Figure 8-10 Clustering Property Sheet

   

   Text description of the illustration sescach.gif

3. 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.

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

Text description of the illustration conpolbt.gif

button.

Setting General Properties

1. Select the connection pool element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the connection pool's properties in the Editor pane.

2. Click the General tab. The General property sheet appear.

   Figure 8-11 Connection Pool--General Property Sheet

   

   Text description of the illustration cpgen.gif

3. 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

1. Select the connection pool element in the Navigator pane. The OracleAS TopLink Sessions Editor displays the connection pool's properties in the Editor pane.

2. Click the Login tab. The General tab of the Login property sheet appears. See "Setting Login Properties"

Working with the Source

Use this procedure to display the source code in the sessions.xml configuration at any time.

To View the Source:

Select a configuration in the Navigator pane and choose View > Source from the menu. The Sessions Configuration Editor opens the configuration in your editor.

If you have not selected a text editor (see "General Preferences" ), the OracleAS TopLink Sessions Editor prompts you select a text editor.