Session Manager overview

How do the application and Session Manager work together? The application uses resolve_initial_references() to obtain a reference to the Session Manager's ConnectionPool object. The application provides the ConnectionPool with the appropriate configuration profile name and the ConnectionPool obtains a connection to the database using the configuration in that profile. The ConnectionPool then returns a Connection object which represents this database connection to the application.

In order to do database work, the application then requests the native database handle from the Connection object. Subsequently, the application code talks to the database directly through this native connection handle. For example, if you are using Oracle, the application code makes direct OCI calls.

For more specific information about using the Session Manager API to get a connection to the database, see “Data access using the Session Manager”.

Programming restrictions vary according to the specific Session Manager implementation your application is using. For information on programming requirements and limitations while using the database's native API to do the work of the transaction (SQL statements, etc.), see “XA Session Manager for Oracle OCI, version 9i Client” and “DirectConnect Session Manager for Oracle OCI, version 9i Client”.

All the information needed for the connection is kept in connection profiles. Each profile has a unique name and consists of attributes such as the database login ID. The set of attributes varies depending on the Session Manager implementation. For more information, see “XA Session Manager for Oracle OCI, version 9i Client” and “DirectConnect Session Manager for Oracle OCI, version 9i Client”.

Use the VisiBroker Console to create and configure connection profiles. The connection profile has all the required attributes to make a connection to the database. For more information about the VisiBroker Console, see “Using the VisiBroker Console”.

The Session Manager associates transactions with the database work performed on a database connection—your application does not have to provide this function. This association is maintained until the application releases the Session Manager connection.

The Session Manager automatically registers the appropriate Resources with the Coordinator—application developers do not need to add anything to their code for Resource registration. While the DirectConnect implementation contains the Resource object invisibly embedded in the Session Manager implementation, the XA implementation uses an external process called the XA Resource Director. The XA Resource Director must be available to use the XA version of the Session Manager. For information about starting an XA Resource Director, see “Integrating VisiTransact with databases using the Session Manager”.

The Session Manager requires that a Connection object be released when the application completes a unit of work against that connection. For implicit transaction contexts, the connection must be released before the transaction is disassociated from that thread. This disassociation occurs:

When the application releases the connection, the Session Manager frees the database connection for use by other transactions.

After releasing the connection, the application may not continue to use that particular Connection object or its associated native connection handle. To perform further work on that transaction or other transactions, the application must obtain a new Connection object.

The Session Manager pools connections automatically. You do not have to add anything to your application code. When an application releases a connection, the Session Manager does not automatically close it. Rather, it keeps it in the connection pool. When there is another request for a connection, the pool will attempt to reuse connections. It will only open a new connection when there are no available compatible connections.

Within the same transaction, you can obtain and release Connection objects as many times as you need to complete work. Since the Session Manager ConnectionPool is more efficient when Connection objects are released after completing a unit of work, do not wait until the entire transaction is complete before releasing Connection objects.

Because the DirectConnect implementation of the Session Manager uses a single connection to perform work for a transaction, the ConnectionPool can not reuse any connection until the transaction is complete. The connection is returned to the pool for reuse after the transaction is committed or rolled back.

The Session Manager manages any connection threading requirements imposed by the database. Since the details about keeping connections with particular threads are incompletely specified by XA, DBMS companies have interpreted the XA requirements for threading behavior differently. For example, when using Oracle, a connection opened using XA requires that every single call for the rest of that connection's life has to be on that same thread. This makes it difficult to integrate with other software which manages threads according to its own policies.

The Session Manager makes sure that your application will always get a connection handle that works with the current thread.

Not all database connections have threading restrictions. When restrictions do not exist, the Session Manager pools connections more efficiently. For more information, see “Data access using the Session Manager”.

The Session Manager and XA Resource Director are not restricted to DBMSs or RDBMSs. They work with any Resource Managers that support XA protocol. Resource Managers are commonly thought to be databases but they include any XA-compliant Resource that is able to participate in a two-phase commit. Another example of a Resource Manager is a message queue.

XA is an accepted industry standard protocol specified by X/Open to allow Transaction Managers to coordinate global (two-phase commit) transactions. Most RDBMS vendors support XA as a way for external transaction coordinators (like the VisiTransact Transaction Service or TP Monitors) to control transaction completion.

Both the Session Manager and the XA Resource Director “speak” XA. Generally, they speak different pieces of XA. The part of XA that has to do with associating work with a transaction is facilitated by the Session Manager. The part of XA that has to do with transaction completion and recovery is performed by the XA Resource Director.

The Session Manager, in conjunction with the VisiTransact Transaction Service, performs the XA interface calls to include, in the transaction, the application's work on that database.

The XA Resource Director performs the two-phase commit for the database as instructed by the transaction's Terminator, and participates in recovery by acting as a bridge between the VisiTransact Transaction Service and the XA-compliant database. The XA Resource Director is deployed as a standalone process.

There should be one XA Resource Director instantiation (or process) deployed for each database.

The XA Resource Director is used with the XA implementation of the Session Manager. You do not use the XA Resource Director with DirectConnect Session Manager deployments.

For transaction completion and recovery, the XA Resource Director bridges the VisiTransact and X/Open transaction environments, which allows for interoperability between Resource objects and the XA-compliant database. (The Session Manager does the bridging for associating application work with the transaction.) The Resource Director is a persistent object which acts as an intermediary during commit, rollback, or recovery for all transactions using a specific database on a network.

One XA Resource Director is associated with each database server. The Session Manager tells the VisiTransact Transaction Service which Resource Director will coordinate the completion of the transaction. After all the work has been done, the VisiTransact Transaction Service communicates with the Resource Director and tells it to commit or rollback the transaction.

You do not have to implement an XA Resource Director or register it with the VisiTransact Transaction Service. It is done for you automatically; however, the system administrator must ensure that the XA Resource Director is available whenever the database is running.

The XA Resource Director ensures that all transactions in its associated database, which were initiated by the VisiTransact Transaction Service, will be completed either by commit or rollback. The transactions will be completed regardless of failure caused by the VisiTransact Transaction Service, the XA Resource Director, or the Resource Manager. Any transaction not completed at the time of failure will be resolved when these three components are back up and running.

For more information about the rules used during transaction completion or a two-phase commit, see “Transaction completion” and “Coordinating transaction completion with Resource objects”.

When only one application server talking to one database is involved in a transaction, the DirectConnect Session Manager is an alternative to using global (two-phase commit) transactions as provided by the XA implementation of the Session Manager. This consists of a single process containing a Session Manager with embedded Resources. For optimum performance, an VisiTransact Transaction Service instance is linked with the application code; however, this is not required. A transaction using the DirectConnect Session Manager is considered a local transaction because all of the components of the transaction are located locally in one process. With DirectConnect access transactions one process talks to one database. All of the work for a particular transaction is done on one physical database connection. The connection uses the same connection profile whenever the database is accessed for the same transaction. The benefit of this type of architecture is a gain in performance because it performs a single-phase commit only. It also allows transactional semantics for work done on databases which do not support two-phase commit.

When using the DirectConnect Session Manager implementation, you do not need the services of the XA Resource Director. The Session Manager uses an internal, transparent Resource implementation.

The single application server process is a multi-threaded process that includes all the methods that might be used in a particular transaction. This process talks to a single database. Additional Resources are not allowed—databases or other types of Resources like message queues. For example, if you are doing a debit and credit transaction, instead of having your debit/credit application server processes on different machines, they are in a single process on one machine. The debit/credit process can talk to the single database across a network. But, a transaction talks to one database only. All the interactions with that one database happen with that one process.

The DirectConnect Session Manager can take advantage of several performance optimizations. When you use a single application server process with a database as the only participant in the transaction, the transaction (via VisiTransact) performs a single phase commit. If the VisiTransact Transaction Service is embedded, the Session Manager does all the Resource registrations and all the work of the transaction locally to that process. The Session Manager, the VisiTransact Transaction Service instance, and the debit/credit process are all within the same application server process so they are not talking to each other across a network or across process boundaries. Additionally, because of the single phase commit, the VisiTransact Transaction Service need not log to the disk. Consequently, there is a performance gain.

The other advantage when using DirectConnect access transactions is that it is a simpler to get them up and running. You do not have to install the XA client library or the components that enable global transactions. For example, if using XA access transactions with Oracle, you have to install Oracle's distributed option; with DirectConnect access transactions, this is unnecessary.

The XA Resource Director is not used with the DirectConnect Session Manager. The Resource object used is built in to the DirectConnect implementation of the Session Manager.

When the application requests database access through the Session Manager, the ConnectionPool object allocates a database connection for that transaction. Unlike XA connections, the DirectConnect connection remains allocated to that transaction until the whole transaction is done. The application follows the same procedure (as it would with a distributed transaction) to get a connection and release a connection. Consequently, the VisiTransact Transaction Service knows what transaction and database is associated with a particular connection. When the request for a commit comes through, the Resource object that is embedded in the Session Manager gets that same physical connection and does a single phase commit or rollback on the transaction.

In other words, because the Session Manager manages connections, every time the application invokes getConnection() for the same transaction, it will get the same connection. The server can have many calls for the same transaction and all the work happens within the same transaction even though the application code did not have to maintain connection state.

If you try to register a Resource (register_resource() call) after a DirectConnect Resource has already been registered, this results in a CORBA::BAD_PARAM exception. In other words, the VisiTransact Transaction Service will not accept any register_resource() calls after a DirectConnect connection has been used.

If getConnection() attempts to obtain a DirectConnect connection, and a Resource has already been registered with the Coordinator, the request will fail throwing a VISSessionManager::Error exception.

You can choose to configure a stand-alone or embedded VisiTransact Transaction Service instance. If you embed an VisiTransact Transaction Service in a single application server, you may realize performance gains when processing a DirectConnect access transaction.

In order to obtain the performance gains of DirectConnect access transactions, there are several restrictions that apply:

•

Only one thread at a time can obtain a connection for a particular transaction. Once getConnection() has been invoked, no other thread will be able to obtain a connection for that transaction until the connection has been released.