resourceadapter.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.iapi.jdbc.ResourceAdapter

   Copyright 1999, 2004 The Apache Software Foundation or its licensors, as applicable.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 */

package org.apache.derby.iapi.jdbc;

import org.apache.derby.iapi.services.context.ContextService;
import org.apache.derby.iapi.store.access.xa.XAResourceManager;
import org.apache.derby.iapi.store.access.xa.XAXactId;
import org.apache.derby.iapi.error.StandardException;

/**
	The resource adapter is the clearing house for managing connections,
	transactions, and XAResources in a JDBC based resource manager living in
	the distributed transaction processing environment.  

	<P> There is one instance of ResourceAdapter per Resource Manager (database).
	The ResourceAdapter is responsible for keeping track of all run time global
	transactions and their state.   The resource adapter only knows of run time
	global transactions, i.e., it does not know of in-doubt global transactions
	re-created by recovery.

	<P>	The following is an overall design of the JTA implementation in cloudscape,
	most of it has little to do with the ResourceAdapter interface itself.
	<P><B>Design Overview </B>

	<P>The overriding design principle is that existing code should be disturbed
	as little as possible.  This is so that DTP code will not add to the bloat
	and drag of a normal, local, embbeded system.  The second design principle
	is that as much of the JDBC 2.0 extension functionality is to be
	implemented in the Connectivity layer and not in the underlying storage
	system as possible.  Ideally, the additional storage interface will
	implement no more than what is necessary to support the XAResource
	interface.

	<P>Language and replication code should not be touched, or have very
	minimal API changes.  The API changes are confined to passing XA calls down
	to the store.

	<P>Some change will be made to existing Connectivity code and new XA
	modules will be added.  This collection of code is hereby referred to as
	the "blob of mysterious connectivity code", or the "resource adapter", or
	"RA" for short.  In the JTA doc, the resource adapter is considered to be
	part of the JDBC driver.  This RA means "some connectivity code", it
	doesn't mean the object that implements the ResourceAdapter interface.

	<P>The most important difference, in terms of implementation, between a
	Connection that deals with a local transaction and a Connection that deals
	with a global transaction is that in a global transaction, 2 or more
	objects and threads can influence it - maybe concurrently.  The normal JDBC
	interaction goes thru the Connection, but transaction demarcation comes
	from an XAResource object(s).  The RA will channel all XAResource calls
	that deal with a run time XA transaction (i.e., commit, end, forget,
	prepare, start) thru the TransactionController that represents the real
	transaction underneath.   Furthermore, the RA will make sure that all calls
	thru a Connection or thru any XAResource objects must pass thru some sort
	of synchronized object before it can get to the underlying transaction
	object.  This is so that there is only one path to change the state of a
	run time transaction and the transaction object and the context manager can
	remain single thread access.

	<P>In-doubt transaction (i.e., transactions re-created by recovery)
	management and concurrency control is the responsibiliy of store. Moreover,
	since the RA does not know the identities of the list of in-doubt
	transactions, store must deal with (throw exception) when someone wants to
	start a transaction with the same Xid as an existing in-doubt transaction.

	<P>In terms of what this means to the app server that is calling us: if the
	Connection and the XAResource that represents a global transaction is being
	accessed by 2 different threads, they will access the database serially and
	not concurrently. An in-doubt transaction gotten thru recovery has no
	transaction object that is ever visible to the RA - because there is no
	connection that was ever made to it.  Therefore it is safe to influence the
	state of an in-doubt transaction directly thru some store factory interface
	- and have that go thru the transaction table underneath to find the actual
	transaction object and context manager etc.

	<P>One new functionality of a Connection is the ability to switch around
	with different transactions.  Before JTA, the lifetime of a transaction is
	bounded by a connection, and a transaction cannot migrate from one
	connection to another.  In JTA, a global transaction can be detached from a
	Connection.  A transaction can move around and be attached to different
	connections and its lifetime is not confine to the connection that started
	it.  From the Connection's point of view, before JTA, a (local) transaction
	is always started and ended in the same connection. With JTA, it needs to
	"take on" existing global transactions that was started by some other
	connections.

	<P>The RA will have the responsibility of 
	<OL>
	<LI>setting up a Context with the appropriate transaction before calling
	store to do work.</LI>
	<LI>handling error on the context.</LI>
	<LI>restoring a previous context if it was switched out due to an XAResouce
	call to commit a transaction that is not what the XAResoruce is currently
	attached to. </LI>
	</OL>

	<P>Because of all these switching around, a Connection may be in a
	transaction-less state.  This happens between an XAResource.end call that
	detached the current global transaction from the Connection, and the next
	XAResource.start call that attach the next global transaction with the
	Connection.

	<BR>An (inferior) implementation is for the Connection object to start a
	local connection once it is detached from a global transaction.  If the
	user then uses the Connection immediately without a XAResource.start call,
	then this Connection behaves just like it did before JTA, i.e., with a
	local transaction.  If, on the other hand, an XAResource.start call happens
	next, then either the local transaction is "morphed" into a global
	transaction, or, if the start call is to attach the connection to a
	pre-existing global transaction, then the local transaction is thrown away
	and the Connection will take on the pre-exising global transaction.

	<BR>Another (superior) implementation is to make it possible for a
	Connection to be transaction-less.  When a Connection is first created by
	XAConnection.getConnection, or when a XAResource.end call detached a global
	transaction from the Connection, it is left in a transaction-less state.
	If a XAResource.start call happens next, then the Connection either start a
	new global transaction or it takes on an existing one.  If a call is made
	directly on the Connection before XAResource.start call happens, then the
	Connection starts a new local transaction.  This only affects Connections
	that was gotten thru the XAConnection.getConnection().  Connections gotten
	thru the DriverManager or a DataSource will have a local transaction
	automatically started, as is the behavior today.  When a Connection with a
	local transaction commits, the transaction is still around but it is chain
	to the next one - this is the current behavior.  This behavior is very
	desirable from a performance point of view, so it should be retained.
	However, a local transaction cannot "morph" into a global transaction,
	therefore when this Connection is attached to a global transaction, the
	local transaction is thrown away and a global one started

	<P>The RA will need to keep track of all global transactions.  This is done
	by (yet another) transaction table that lives in the RA.  This transaction
	table maps Xid to the ContextManager of the global transaction and whatever
	else a connection needs to talk to the transaction - I assume the
	Connection object currently have tendrils into various contexts and objects
	and these are things that need to be detached and attached when a
	Connection is hooked up with another transaction.  The reason for yet
	another transaction table instead of the one in store is because the one in
	store keeps track of local and internal transactions and is really quite
	overworked already.

	<P><B>Detailed design</B>

	<BR> First some ugly pictures.  Some links are not shown to reduce
	clutter.  Externally visible object is in <B>bold</B>.
  
	<P><PRE>
* 
* When user ask for an XAConnection via a XADataSource, the following objects
* exists 
* <BR>
*
*                                                     |-------------|
*                                  |======= produces=>| <B>XAResource</B>  |
*                                  ||                 |-------------|
*                                  ||                       |
*                                  ||                     has A
*                                  ||                       |
*                                  ||  |---------------------
*                                  ||  V
* |--------------| produces |--------------| 
* | <B>XADataSource</B> |=========>| <B>XAConnection</B>
* |--------------|          |--------------| 
*       |                          | 
*     extends                    extends
*       |                          | 
*       |                |-----------------------|   |----------------------|
*       |                | DB2jPooledConnection |==>| BrokeredConnection |
*       |                |-----------------------|   |----------------------|
*       |                          |       ^                  |
*       |                        has A     |               has A
*       |                          |       |                  |
* |-----------------|              |       --------------------
* | EmbeddedDataSource |              |
* |-----------------|              |
*       |                          |
*     has A                        |
*       |                          |
*       V                          V
* |------------|           |----------------------|   |-----------------------|
* | JDBCDriver |=produces=>| DetachableConnection |==>| XATransactionResource |
* | LocalDriver|           |----------------------|   |                       |
* |------------|                   |                  |   points to :         |
*                                  |                  |XATransactionController|
*                                  |                  | ContextManager        |
*                                  |                  | LCC                   |
*                                  |                  | .. etc ..             |
*                                  |                  |-----------------------| 
*                                  |                            |