org.apache.derby.impl.jdbc
Class TransactionResourceImpl

java.lang.Object
  extended by 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.


Field Summary
protected  ContextManager cm
           
protected  ContextService csf
           
protected  Database database
           
private  java.lang.String dbname
           
private  java.lang.String drdaID
           
private  InternalDriver driver
           
protected  LanguageConnectionContext lcc
           
private  java.lang.String url
           
protected  java.lang.String username
           
 
Constructor Summary
TransactionResourceImpl(InternalDriver driver, java.lang.String url, java.util.Properties info)
          create a brand new connection for a brand new transaction
 
Method Summary
(package private)  boolean cleanupOnError(java.lang.Throwable e)
           
(package private)  void clearContextInError()
          An error happens in the constructor, pop the context.
(package private)  void clearLcc()
          Resolve: probably superfluous
(package private)  void commit()
          local transaction demarcation - note that global or xa transaction cannot commit thru the connection, they can only commit thru the XAResource, which uses the xa_commit or xa_rollback interface as a safeguard.
(package private)  ContextManager getContextManager()
          need to be public because it is in the XATransactionResource interface
(package private)  ContextService getCsf()
           
(package private)  Database getDatabase()
           
(package private)  java.lang.String getDBName()
           
(package private)  InternalDriver getDriver()
          Return instance variables to EmbedConnection.
(package private)  LanguageConnectionContext getLcc()
           
(package private)  java.lang.String getUrl()
           
(package private)  java.lang.String getUserName()
           
(package private)  java.sql.SQLException handleException(java.lang.Throwable thrownException, boolean autoCommit, boolean rollbackOnAutoCommit)
          clean up the error and wrap the real exception in some SQLException.
(package private)  boolean isActive()
           
(package private)  boolean isIdle()
           
(package private)  void restoreContextStack()
           
(package private)  void rollback()
           
(package private)  void setDatabase(Database db)
          Called only in EmbedConnection construtor.
(package private)  void setupContextStack()
           
(package private)  StandardException shutdownDatabaseException()
           
(package private)  void startTransaction()
           
static java.sql.SQLException wrapInSQLException(java.lang.Throwable thrownException)
          Wrap a Throwable in an SQLException.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cm

protected ContextManager cm

csf

protected ContextService csf

username

protected java.lang.String username

dbname

private java.lang.String dbname

driver

private InternalDriver driver

url

private java.lang.String url

drdaID

private java.lang.String drdaID

database

protected Database database

lcc

protected LanguageConnectionContext lcc
Constructor Detail

TransactionResourceImpl

TransactionResourceImpl(InternalDriver driver,
                        java.lang.String url,
                        java.util.Properties info)
                  throws java.sql.SQLException
create a brand new connection for a brand new transaction

Throws:
java.sql.SQLException
Method Detail

setDatabase

void setDatabase(Database db)
Called only in EmbedConnection construtor. The Local Connection sets up the database in its constructor and sets it here.


startTransaction

void startTransaction()
                throws StandardException,
                       java.sql.SQLException
Throws:
StandardException
java.sql.SQLException

getDriver

InternalDriver getDriver()
Return instance variables to EmbedConnection. RESOLVE: given time, we should perhaps stop giving out reference to these things but instead use the transaction resource itself.


getCsf

ContextService getCsf()

getContextManager

ContextManager getContextManager()
need to be public because it is in the XATransactionResource interface


getLcc

LanguageConnectionContext getLcc()

getDBName

java.lang.String getDBName()

getUrl

java.lang.String getUrl()

getDatabase

Database getDatabase()

shutdownDatabaseException

StandardException shutdownDatabaseException()

commit

void commit()
      throws StandardException
local transaction demarcation - note that global or xa transaction cannot commit thru the connection, they can only commit thru the XAResource, which uses the xa_commit or xa_rollback interface as a safeguard.

Throws:
StandardException

rollback

void rollback()
        throws StandardException
Throws:
StandardException

clearContextInError

void clearContextInError()
An error happens in the constructor, pop the context.


clearLcc

void clearLcc()
Resolve: probably superfluous


setupContextStack

final void setupContextStack()

restoreContextStack

final void restoreContextStack()

handleException

final java.sql.SQLException handleException(java.lang.Throwable thrownException,
                                            boolean autoCommit,
                                            boolean rollbackOnAutoCommit)
                                     throws java.sql.SQLException
clean up the error and wrap the real exception in some SQLException.

Throws:
java.sql.SQLException

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

getUserName

java.lang.String getUserName()

cleanupOnError

boolean cleanupOnError(java.lang.Throwable e)

isIdle

boolean isIdle()

isActive

boolean isActive()

Built on Thu 2011-03-10 11:54:14+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.