org.apache.derby.impl.jdbc

Class TransactionResourceImpl

java.lang.Object

org.apache.derby.impl.jdbc.TransactionResourceImpl

public final class TransactionResourceImpl
extends java.lang.Object

An instance of a TransactionResourceImpl is a bundle of things that connects a connection to the database - it is the transaction "context" in a generic sense. It is also the object of synchronization used by the connection object to make sure only one thread is accessing the underlying transaction and context.

TransactionResourceImpl not only serves as a transaction "context", it also takes care of:

1. context management: the pushing and popping of the context manager in and out of the global context service
2. transaction demarcation: all calls to commit/abort/prepare/close a transaction must route thru the transaction resource.
3. error handling

The only connection that have access to the TransactionResource is the root connection, all other nested connections (called proxyConnection) accesses the TransactionResource via the root connection. The root connection may be a plain EmbedConnection, or a DetachableConnection (in case of a XATransaction). A nested connection must be a ProxyConnection. A proxyConnection is not detachable and can itself be a XA connection - although an XATransaction may start nested local (proxy) connections.

this is an example of how all the objects in this package relate to each other. In this example, the connection is nested 3 deep. DetachableConnection.

      lcc  cm   database  jdbcDriver
       ^    ^    ^         ^ 
       |    |    |         |
      |======================|
      | TransactionResource  |
      |======================|
             ^  |
             |  |
             |  |      |---------------rootConnection----------|
             |  |      |                                       |
             |  |      |- rootConnection-|                     |
             |  |      |                 |                     |
             |  V      V                 |                     |
|========================|      |=================|      |=================|
|    EmbedConnection     |      | EmbedConnection |      | EmbedConnection |
|                        |<-----|                 |<-----|                 |
| (DetachableConnection) |      | ProxyConnection |      | ProxyConnection |
|========================|      |=================|      |=================|
   ^                 | ^             ^                        ^
   |                 | |             |                        |
   ---rootConnection-- |             |                        |
                       |             |                        |
                       |             |                        |
 |======================|  |======================|  |======================|
 | ConnectionChild |  | ConnectionChild |  | ConnectionChild |
 |                      |  |                      |  |                      |
 |  (EmbedStatement)    |  |  (EmbedResultSet)    |  |  (...)               |
 |======================|  |======================|  |======================|

 

A plain local connection must be attached (doubly linked with) to a TransactionResource at all times. A detachable connection can be without a TransactionResource, and a TransactionResource for an XATransaction (called XATransactionResource) can be without a connection.

Method Summary

Modifier and Type	Method and Description
static java.sql.SQLException	wrapInSQLException(java.lang.Throwable thrownException) Wrap a Throwable in an SQLException.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

wrapInSQLException

public static java.sql.SQLException wrapInSQLException(java.lang.Throwable thrownException)

Wrap a Throwable in an SQLException.

Parameters:

thrownException - a Throwable

Returns:

thrownException, if it is an SQLException; otherwise, an SQLException which wraps thrownException