Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Session Broker and Client Sessions

The TopLink session broker is a mechanism that enables client applications to transparently access multiple databases through a single TopLink session.

The TopLink session broker enables client applications to access two or more databases through a single session. If your application stores objects in multiple databases, the session broker, which provides seamless communication for client applications, enables the client to view multiple databases as if they were a single database.

When a three-tier session broker application uses server sessions to communicate with the database, clients require a client session to access the database. Similarly, when you implement a session broker, the client requires a client session broker to access the database.

A client session broker is a collection of client sessions, one from each server session associated with the session broker. When a client acquires a client session broker, the session broker collects one client session from each associated server session, and wraps the client sessions so that they appear to be a single client session to the client application.

As Figure 75-7 illustrates, a session broker connects to the databases through two or more server sessions or database sessions.

Figure 75-7 TopLink Session Broker with Server Session Architecture

Description of "Figure 75-7 TopLink Session Broker with Server Session Architecture"

This section explains the following:

- Session Broker Architecture

- Committing a Transaction with a Session Broker

- Session Broker Session Limitations

- Session Broker Alternatives

For information, see:

- "Creating Session Broker and Client Sessions"

- "Configuring Session Broker and Client Sessions"

- "Acquiring a Session from the Session Manager"

- "Acquiring a Client Session"

## Session Broker Architecture

As Figure 75-7 illustrates, a session broker contains a broker object that acts as an intermediary between the application and the multiple sessions added to the session broker.

To construct a session broker, use TopLink Workbench to modify your `sessions.xml` file as follows:

1. Define two or more sessions (of the same type, either server sessions or database sessions).

2. Define a session broker.

3. Add the sessions to the session broker.

When you use `SessionManager` method `getSession(sessionBrokerName)` where `sessionBrokerName` is the name of the session broker you defined, the session manager returns the corresponding session broker session (call it `mySessionBroker`) that contains an instance of each of the sessions you added to it. When you use `mySessionBroker` method `login`, it logs into each defined session. Thereafter, you use `mySessionBroker` as you would any other session: TopLink transparently handles access to the multiple databases.

In the case of a three-tier architecture where the session broker contains two or more server sessions, you use session broker method `acquireClientSessionBroker` to acquire a single client session that lets you query across all the data sources managed by the various server sessions. You use this client session as you would any other client session.

## Committing a Transaction with a Session Broker

By default, when you commit a transaction with a session broker session, a two-stage commit is performed.

Ideally, you should incorporate a JTA external transaction controller in order to benefit from its two-phase commit.

### Committing a Session with a JTA Driver: Two-Phase Commits

If you use a session broker, incorporate a JTA external transaction controller wherever possible. The external transaction controller provides a two-phase commit, which passes the SQL statements that are required to commit the transaction to the JTA driver. The JTA driver handles the entire commit process.

JTA guarantees that the transaction commits or rolls back completely, even if the transaction involves more than one database. If the commit operation to any one database fails, then all database transactions roll back. The two-phase commit operation is the safest method available to commit a transaction to the database.

Two-phase commit support requires integration with a compliant JTA driver.

### Committing a Session Without a JTA Driver: Two-Stage Commits

If there is no JTA driver available, then the session broker provides a two-stage commit algorithm. A two-stage commit differs from a two-phase commit in that it guarantees data integrity only up to the point of the final commit of the transaction. If the SQL script executes successfully on all databases, but the commit operation then fails on one database, only the database that experiences the commit failure rolls back.

Although unlikely, this scenario is possible. As a result, if your system does not include a JTA driver and you use a two-stage commit, build a mechanism into your application to deal with this type of potential problem.

## Session Broker Session Limitations

Although the session broker is a powerful tool that lets you use data that is distributed across multiple databases from a single application, it has some limitations:

- It may not meet the needs of your particular distributed data application (see "Session Broker Alternatives").

- You cannot split multiple table descriptors across databases.

- Each class must reside on only one database.

- You cannot use joins through expressions across databases.

- Many-to-many join tables must reside on the same database as the target object (See "Many-to-Many Join Tables and Direct Collection Tables" for a work-around for this limitation).

### Many-to-Many Join Tables and Direct Collection Tables

By default, TopLink assumes that many-to-many and direct collection tables are on the same database as the source object. If they are on a different database, then you must configure the mapping's session name using `ManyToManyMapping` or `DirectCollectionMapping` method `setSessionName` as Example 75-4 illustrates.Note that a many-to-many join table must still reside on the same database as the target object.

Example 75-4 Using Mapping setSessionName in a Descriptor Amendment Method

    		public void addToDescriptor(ClassDescriptor descriptor) {
        descriptor.getMappingForAttributeName("projects").setSessionName("branch-database");
    }

To work around this problem for data-level queries, use the `DatabaseQuery` method `setSessionName`.

## Session Broker Alternatives

When evaluating whether or not to use a session broker in your application, consider the following alternatives:

- Database Linking

- Multiple Sessions

### Database Linking

Most enterprise databases, such as the Oracle Database, support linking other databases on the database server. This allows querying and two-phase commit across linked databases. Using the session broker is not the same as linking databases. If your database allows linking, Oracle recommends that you use that functionality to provide multiple database access instead of using a session broker.

### Multiple Sessions

An alternative to the session broker is to use multiple sessions to work with multiple databases:

- If the data on each database is unrelated to data on the other databases, and relationships do not cross database boundaries, then you can create a separate session for each database. For example, you might have individual databases and associated sessions dedicated to each department.

  This arrangement requires that you to manage each session manually and ensure that the class descriptors for your project reside in the correct session.

- You can use additional sessions to house a standard batch job. In this case, you can create two or more sessions on the same database. In addition to the main session that supports client queries, you create other sessions that support batch inserts at low-traffic times in your system. This lets you maintain the client cache.