Package org.apache.derby.impl.jdbc

Class 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.

    • 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.

      • 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.

      • getContextManager

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

      • getDBName

        java.lang.String getDBName()

      • getUrl

        java.lang.String getUrl()

      • 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

      • 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

      • isLoginException

        private boolean isLoginException​(java.lang.Throwable thrownException)
        Determine if the exception thrown is a login exception. Needed for DERBY-5427 fix to prevent inappropriate thread dumps and javacores. This exception is special because it is SESSION_SEVERITY and database.isActive() is true, but the session hasn't started yet,so it is not an actual crash and should not report extended diagnostics.
        Parameters:
        thrownException -
        Returns:
        true if this is a login failure exception

      • 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,
                       boolean diagActive)
        clean up error and print it to derby.log if diagActive is true
        Parameters:
        e - the error we want to clean up
        diagActive - true if extended diagnostics should be considered, false not interested of extended diagnostic information
        Returns:
        true if the context manager is shutdown, false otherwise.

      • isIdle

        boolean isIdle()

      • isActive

        boolean isActive()