[teiid-commits] teiid SVN: r2585 - branches/7.1.x/documentation/reference/src/main/docbook/en-US/content.
teiid-commits at lists.jboss.org
teiid-commits at lists.jboss.org
Thu Sep 16 15:37:03 EDT 2010
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>
More information about the teiid-commits
mailing list