A tyrex.tm.TransactionDomain 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 the transaction manager, user transaction and transaction factory from the transaction domain. It also uses the transaction domain to obtain connection factories and place them in the JNDI Environment Naming Context.

Transaction domains are created from domain configuration files. The structure and values of the domain configuration file is specified in Tyrex Configuration.

The following example illustrates how to create a new transaction domain from the domain configuration file domain.xml located in the current directory:

TransactionDomain domain;

// Create a transaction domain using
// a domain configuration file
try {
    domain = TransactionDomain.createDomain( "domain.xml" );
} catch ( DomainConfigurationException except ) {
    // Domain cannot be created, handle error
    . . . 
}
// Recover all resources used in the domain
try {
    domain.recover();
} catch ( RecoveryException except ) {
    while ( except != null ) {
        System.out.println( "Recovery error: " + except );
        except = except.getNextException();
    }
}
// Domain is now active and ready for use
        

The object tyrex.resource.Resources represents a collection of installed resources managers. Resources, such as JDBC data sources and JCA connectors, are configured based on their specification in the domain configuration file. In addition, resources can be added and removed at run-time.

Each resource manager is represented by an object of type tyrex.resource.Resource. Each such object represents a single installed resource. The application server uses these objects to interact with the resource manager, and expose the resource manager to the client application.

An installed resource has a client factory that is exposed to the application from the JNDI Environment Naming Context. The client factory type depends on the resource type, e.g. a JDBC DataSource, a JCA CCI ConnectionFactory, etc.

An installed resource has a connection pool that manages utilization of connections. The connection pool is not directly accessible to the application, but the usage metrics are accessible from tyrex.resource.PoolMetrics. Usage metrics includes such information as the number of connections created and released over a period of time, average duration for using or holding a connection in the pool, etc.

tyrex.resource.PoolLimits represents limits placed on the connection pool. These limits restrict the maximum number of connections that can be used at any one time, define the minimum number of connections to retain in the pool, the duration for retaining connections in the pool between uses, and more.

tyrex.tm.RuntimeContext provides an association between a component or a client, the current thread, and the resources accessed by that thread.

The runtime context keeps track of open transactions, JNDI Environment Naming Context, security subject, resource managers and open connector. It is managed for a given component or client, and can be preserved across method calls in different threads, by associating and dissociating it from the current thread.

Each thread is associated with one runtime context at any given time. A new runtime context can be created using one of the newRuntimeContext() methods, and populated with JNDI bindings and a security context. The runtime context is then associated/dissociated with the current thread across method invocations using the setRuntimeContext() and unsetRuntimeContext() methods.

The runtime context association works like a stack. Calling setRuntimeContext() pushes the current runtime context up the stack, and associates the thread with the current runtime context. Calling unsetRuntimeContext() pops the previous runtime context from the stack and associates it with the thread. A thread will always have a runtime context created on demand, if setRuntimeContext() was not called explicitly.

The runtime context keeps track of the current open transaction. When the runtime context is associated with the current thread, this is the same transaction on which the transaction manager operates.

The runtime context keeps track of the JNDI Environment Naming Context. When the runtime context is associated with the current thread, the same bindings will be accessible to the application from the java: URL.

The runtime context keeps track of the security subject used for authentication and authorization. When the runtime context is associated with the current thread, this subject is used to authenticate the caller against resource managers and other services.

The runtime context keeps track of all connections opened from connection pools obtained from the JNDI Environment Naming Context. Open connections and their transaction association is maintained across method invocations through the runtime context.

The following example illustrates how the application server will create and use a runtime context:

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

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

// Create the context 'comp/env/jdbc'
jndiCtx = runCtx.getEnvContext();
jndiCtx = jndiCtx.createSubcontext( "comp" );
jndiCtx = jndiCtx.createSubcontext( "env" );
jndiCtx = jndiCtx.createSubcontext( "jdbc" );

// Obtain resources from the transaction domain
// Obtain the client factory for 'db1'
resources = TransactionDomain.getDomain( "myDomain" ).
    getResources();
dataSource = (DataSource) resources.getResource( "db1" );
// Bind 'db1' as 'comp/env/jdbc/myDb'
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();
        

The following example illustrates how the application obtains a new JDBC connection from the data source previously listed in the JNDI context:

InitialContext initCtx;
String         jndiName;
DataSource     dataSource;
Connection     conn;

// Application code to access the database
initCtx = new InitialContext();
jndiName = "java:comp/env/jdbc/myDb";
dataSource = (DataSource) initCtx.lookup( jndiName );
conn = dataSource.getConnection();
        

All Tyrex transactions implement the extended interface tyrex.tm.TyrexTransaction, which supports asynchronous commit and rollback, one-phase commit, access to the parent transaction and transaction identifier, etc.

The Tyrex transaction manager implements the extended interface tyrex.tm.TyrexTransactionManager, which allows transactions to be resolved from an identifier, and provides additional management and resource association methods.

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.