Package tyrex.tm

Transaction Manager

See:
Description

Interface Summary

DomainMetrics	Holds metrics associated with a transaction domain.
Heuristic	Defines values for different heuristic decisions.
JournalFactory	Interface for a journal factory.
TransactionInterceptor	The interceptor interface allows an external engine to hook up into the transaction monitor and either record the outcome of transactions or affect them.
TyrexTransaction	Tyrex extensions for Transaction.
TyrexTransactionManager	Tyrex extensions for TransactionManager.
XAResourceCallback	This interface defines methods that inform when the XA resource associated with this callback has been enlisted in a transaction, i.e.

Class Summary

Journal	Abstract class for transactional journal.
Journal.RecoveredTransaction	Provides information about a recovered transaction.
RuntimeContext	The runtime context provides an association between a component or client, the current thread, and resources used by the application.
TransactionDomain	A transaction domain provides centralized management for transactions.

Exception Summary

DomainConfigurationException	A general exception associated with transaction domains.
RecoveryException	Indicates an error occuring during recovery.
TransactionTimeoutException	Thrown to terminate the current thread and indicate that the current transaction has timed out.

Package tyrex.tm Description

Transaction Manager

Version:

$Revision: 1.3 $ $Date: 2001/03/13 03:14:59 $

Author:

Assaf Arkin

Transaction Domains

A transaction domain provides centralized management for transactions. A transaction domain defines the policy for all transactions created from that domain, such as default timeout, maximum number of open transactions, IIOP support, and journaling. In addition, the domain maintains resource managers such as JDBC data sources and JCA connectors.

The application server obtains a transaction manager or user transaction object, and managed resources from the transaction domain.

Transaction domains are created from a domain configuration file. For more information about domain configuration files, refer to the relevant documentation and domain.xsd.

Usage metrics for transactions can be obtained from DomainMetrics. Usage metrics include information such as the accumulated number of transactions committed and rolledback, the average duration of a transaction, etc.

The following code illustrates how to create a new transaction domain:

InputStream       stream;
TransactionDomain domain;

// Create a transaction domain using a domain configuration file
stream = new FileInputStream( "domain.xml" )
try {
    domain = TransactionDomain.createDomain( stream );
} catch ( DomainConfigurationException except ) {
    // Domain cannot be created, handle error
    . . . 
}
// Recover all resources used in the domain
try {
    domain.recover();
} catch ( RecoveryException except ) {
    // Ignore all errors, they are logged to the console.
}
// Domain is now active and ready to use

The Runtime Context

The runtime context provides an association between a component or client, the current thread, and resources used by the application.

The runtime context keeps track of active transaction, JNDI ENC, security subject, and open connections. It is associated with a component or client, and can be preserved across method invocations by associating it with the current thread.

Each thread is associated with a runtime context, whether explicitly or implicitly. A thread can be associated with a particular runtime context by calling setRuntimeContext. If this method was not called, a default runtime context is created on demand.

A new runtime context can be created with one of the newRuntimeContext methods and populated with JNDI bindings and security context. The runtime context is then associated with the current thread across method invocations belonging to the same component or client.

The runtime context keeps track of the current active transaction. When the runtime context is associated with the current thread, this is the same transaction available from TransactionManager.

The runtime context keeps track of the JNDI environment naming context. The JNDI bindings are accessible from the java: URL when the runtime context is associated with the current thread.

The runtime context keeps track of the security subject used for authentication and authorization when the runtime context is associated with the current thread.

The runtime context keeps track of all connections obtained from the environment naming context. Open connections can be retained across method invocations.

The following example illustrates how to create and use a runtime context:

RuntimeContext runCtx;
Context        jndiCtx;
Resources      resources;
DataSource     dataSource;

// Create a new context
runCtx = RuntimeContext.newRuntimeContext();

// Bind a JDBC DataSource to the JNDI ENC
jndiCtx = runCtx.getEnvContext().createSubcontext( "jdbc" );
resources = TransactionDomain.getDomain( "myDomain" ).getResources();
dataSource = (DataSource) resources.getResource( "dataSource" );
jndiCtx.bind( "myDB", dataSource );

. . .
// Associate the runtime context with the current thread
RuntimeContext.setRuntimeContext( runCtx );

. . .
// Dissociate the runtime context with the current thread
RuntimeContext.unsetRuntimeContext();

. . .
// Discard the runtime context
runCtx.cleanup();

JTA Extended Interfaces

All Tyrex transactions implement the interface TyrexTransaction, which supports asynchronous commit and rollback, and one phase commit.

All Tyrex transaction managed implement the interface TyrexTransactionManager, which supports transaction resolving from an Xid, and means to obtain extended transaction status.

tyrex.tm.TransactionStatus provide additional information about a transaction in addition to that provided by Transaction, including the transaction identifier (Xid), start time and timeout, resources and thread association.

Interceptors allow an external engine to hook up into the transaction monitor and either record the outcome of transactions or affect them. The interceptor is notified when transactions are created, attempt to commit, rolled back, and when they are resumed or suspended from threads.

Journaling

Transaction journal is an external service not provided by Tyrex. The Journal interface is used to link Tyrex into an implementation of a transaction journal.