2:37 p.m.
Author: rareddy
Date: 2010-09-16 15:37:03 -0400 (Thu, 16 Sep 2010)
New Revision: 2585
Modified:
branches/7.1.x/documentation/reference/src/main/docbook/en-US/content/transaction_support.xml
Log:
TEIID-1261: Adding the transactional behavior of the Teiid runtime under JBoss AS when
using different types of data sources that are available.
Modified:
branches/7.1.x/documentation/reference/src/main/docbook/en-US/content/transaction_support.xml
===================================================================
---
branches/7.1.x/documentation/reference/src/main/docbook/en-US/content/transaction_support.xml 2010-09-16
18:11:10 UTC (rev 2584)
+++
branches/7.1.x/documentation/reference/src/main/docbook/en-US/content/transaction_support.xml 2010-09-16
19:37:03 UTC (rev 2585)
@@ -175,9 +175,7 @@
Global - the XAResource interface provided by an XAConnection is
used to control the transaction. Note that XAConnections are
available only if Teiid is consumed through its XADataSource,
- <classname>org.teiid.jdbc.TeiidDataSource
- </classname>
- . JEE containers or data access APIs typically control XA
+ <classname>org.teiid.jdbc.TeiidDataSource</classname>. JEE containers
or data access APIs typically control XA
transactions on behalf of application code.
</para>
</listitem>
@@ -211,6 +209,129 @@
portable fashion requires some kind of transaction support.</para>
</section>
</section>
+ <section>
+ <title>Transactional Behavior with JBoss Data Source Types</title>
+ <para>JBoss AS allows creation of different types of data sources, based on
their transactional capabilities. The type
+ of data source you create for your VDB's sources also dictates if that data
source will be participating the
+ distributed transaction or not, irrespective of the transaction scope you
selected from above. Here are different types of data sources</para>
+ <itemizedlist>
+ <listitem>
+ <para>xa-datasource: Capable of participating in the distributed
transaction using XA. This is recommended
+ type be used with any Teiid sources.</para>
+ </listitem>
+ <listitem>
+ <para>local-datasource: Does not participate in XA, unless this is
the <emphasis>only</emphasis> source that is
+ local-datasource that is participating among other xa-datasources in the
current distributed transaction. This technique is
+ called last commit optimization. However, if you have more then one
local-datasources participating in a transaction, then
+ the transaction manager will end up with <emphasis>"Could not
enlist in transaction on entering meta-aware object!;"</emphasis>
+ exception.</para>
+ </listitem>
+ <listitem>
+ <para>no-tx-datasource: Does not participate in distributed
transaction at all. In the scope of Teiid command over multiple sources,
+ you can include this type of datasource in the same distributed
transaction context, however this source will be it
+ will not be subject to any transactional participation. Any changes done
on this source as part of the transaction scope,
+ can not be rolled back.</para>
+ </listitem>
+ </itemizedlist>
+ <para>If you have three different sources A, B, C and they are being used
in Teiid. Here are some variations
+ on how they behave with different types of data sources. The suffixes
"xa", "local", "no-tx" define different type of sources
used.</para>
+ <itemizedlist>
+ <listitem>
+ <para>A-xa B-xa, C-xa : Can participate in all transactional
scopes. No restrictions.</para>
+ </listitem>
+ <listitem>
+ <para>A-xa, B-xa, c-local: Can participate in all transactional
scopes. Note that there is only one single source
+ is "local". It is assumed that in the Global scope, the third
party datasource, other than Teiid Datasource is also XA.</para>
+ </listitem>
+ <listitem>
+ <para>A-xa, B-xa, C-no-tx : Can participate in all transactional
scopes. Note "C" is not a
+ really bound by any transactional contract. A and B are the only
participents in XA transaction.</para>
+ </listitem>
+ <listitem>
+ <para>A-xa, B-local, C-no-tx : Can participate in all transactional
scopes. Note "C" is not a
+ really bound by any transactional contract, and there is only single
"local" source.</para>
+ </listitem>
+ <listitem>
+ <para>If any two or more sources are "local" : They can
only participate in Command mode with "autoCommitTxn=OFF".
+ Otherwise will end with exception as "Could not enlist in
transaction on entering meta-aware object!;" exception, as it is
+ not possible to do a XA transaction with "local"
datasources.</para>
+ </listitem>
+ <listitem>
+ <para>A-no-tx, B-no-tx, C-no-tx : Can participate in all
transaction scopes, but none of the sources will be
+ bound by transactional terms. This is equivalent to not using
transactions or setting Command mode with "autoCommitTxn=OFF".</para>
+ </listitem>
+ </itemizedlist>
+ <note><para>Teiid Designer creates "local" data source by
default which is not optimal for the XA transactions.
+ Teiid would like this to be creating a XA data sources, however with current
limitations with DTP that feature is
+ currently not available. To create XA data source, look in JBoss AS
"doc" directory for example templates,
+ or use the "admin-console" to create the XA data
sources.</para></note>
+
+ <para>If your datasource is not XA, and not the only local source and can
not use "no-tx", then you can look into
+ extending the source to implement the compensating XA implementation. i.e. define
your own resource manager for
+ your source and manage the transaction the way you want it to behave. Note that
this could be complicated if not
+ impossible if your source natively does not support distributed XA protocol. In
summay</para>
+ <itemizedlist>
+ <listitem>
+ <para>Use XA datasource if possible</para>
+ </listitem>
+ <listitem>
+ <para>Use no-tx datasource if applicable</para>
+ </listitem>
+ <listitem>
+ <para>Use autoCommitTxn = OFF, and let go distributed
transactions, though not recommended</para>
+ </listitem>
+ <listitem>
+ <para>Write a compensating XA based
implementation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <table>
+ <title>Teiid Transaction Participation</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Teiid-Tx-Scope</entry>
+ <entry>XA source</entry>
+ <entry>Local Source</entry>
+ <entry>No-Tx SOurce</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Local</entry>
+ <entry>always</entry>
+ <entry>Only If Single Source</entry>
+ <entry>never</entry>
+ </row>
+ <row>
+ <entry>Global</entry>
+ <entry>always</entry>
+ <entry>Only If Single Source</entry>
+ <entry>never</entry>
+ </row>
+ <row>
+ <entry>Auto-commit=true, AutoCommitTxn=ON</entry>
+ <entry>always</entry>
+ <entry>Only If Single Source</entry>
+ <entry>never</entry>
+ </row>
+ <row>
+ <entry>Auto-commit=true, AutoCommitTxn=OFF</entry>
+ <entry>never</entry>
+ <entry>never</entry>
+ <entry>never</entry>
+ </row>
+ <row>
+ <entry>Auto-commit=true,
AutoCommitTxn=DETECT</entry>
+ <entry>always</entry>
+ <entry>Only If Single Source</entry>
+ <entry>never</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
<section>
<title>Limitations and Workarounds</title>
<itemizedlist>