[jboss-cvs] JBossAS SVN: r76330 - projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Jul 28 18:01:45 EDT 2008
Author: irooskov at redhat.com
Date: 2008-07-28 18:01:44 -0400 (Mon, 28 Jul 2008)
New Revision: 76330
Modified:
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/An_Introduction_to_the_JTA.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Appendix.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Configuring_JBossJTA.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Examples.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/JDBC_and_Transactions.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Preface.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Revision_History.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/The_Resource_Manager.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transaction_Recovery.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions_JTA_Programmers_Guide.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Using_JBossJTA_in_Application_Servers.xml
Log:
updated Transactions Programmers Guide with clean ids
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/An_Introduction_to_the_JTA.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/An_Introduction_to_the_JTA.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/An_Introduction_to_the_JTA.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,11 +2,11 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-An_Introduction_to_the_JTA">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-An_Introduction_to_the_JTA">
<title>An Introduction to the JTA</title>
<para>
</para>
- <section id="Transactions_JTA_Programmers_Guide-An_Introduction_to_the_JTA-The_Java_Transaction_API">
+ <section id="sect-Transactions_JTA_Programmers_Guide-An_Introduction_to_the_JTA-The_Java_Transaction_API">
<title>The Java Transaction API</title>
<para>
The interfaces specified by the many transaction standards are typically too low-level for most application programmers. Therefore, Sun Microsystems has specified higher-level interfaces to assist in the development of distributed transactional applications. Note, these interfaces are still low-level, and require, for example, the programmer to be concerned with state management and concurrency for transactional application. In addition, they are geared more for applications which require XA resource integration capabilities, rather than the more general resources which the other APIs allow.
@@ -28,9 +28,9 @@
<listitem>
<para>
Resource manager: (through a resource adapter<footnote>
- <para>
- A Resource Adapter is used by an application server or client to connect to a Resource Manager. JDBC drivers which are used to connect to relational databases are examples of Resource Adapters.
- </para>
+ <para>
+ A Resource Adapter is used by an application server or client to connect to a Resource Manager. JDBC drivers which are used to connect to relational databases are examples of Resource Adapters.
+ </para>
</footnote>) provides the application with access to resources. The resource manager participates in distributed transactions by implementing a transaction resource interface used by the transaction manager to communicate transaction association, transaction completion and recovery.
</para>
</listitem>
@@ -49,5 +49,6 @@
</para>
</note>
</section>
+
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Appendix.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Appendix.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Appendix.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,9 +2,9 @@
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<appendix id="Transactions_JTA_Programmers_Guide-Revision_History">
+<appendix id="appe-Transactions_JTA_Programmers_Guide-Revision_History">
<appendixinfo>
- <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</appendixinfo>
<title>Revision History</title>
<para>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,27 +2,29 @@
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<bookinfo id="Transactions_JTA_Programmers_Guide-Product_Name_and_Version">
+<bookinfo id="book-Transactions_JTA_Programmers_Guide-Transactions_JTA_Programmers_Guide">
<title>Transactions JTA Programmers Guide</title>
<subtitle>JBoss Enterprise Application Platform</subtitle>
<issuenum>0.1</issuenum>
<productnumber>0</productnumber>
- <abstract><para>This book is about the Transactions JTA from the view of the programmer</para></abstract>
+ <abstract>
+ <para>This book is about the Transactions JTA from the view of the
+programmer</para></abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
- <imagedata format='SVG' fileref="Common_Content/images/title_logo.svg" />
+ <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
</imageobject>
- <textobject><phrase>Logo</phrase></textobject>
+ <textobject>
+ <phrase>Logo</phrase>
+ </textobject>
</inlinemediaobject>
</corpauthor>
<copyright>
<year>&YEAR;</year>
<holder>&HOLDER;</holder>
</copyright>
- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</bookinfo>
-
-
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Configuring_JBossJTA.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Configuring_JBossJTA.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Configuring_JBossJTA.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,58 +2,96 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-Configuring_JBossJTA">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-Configuring_JBossJTA">
<title>Configuring JBossJTA</title>
<para>
</para>
- <section id="Transactions_JTA_Programmers_Guide-Configuring_JBossJTA-Configuring_options">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Configuring_JBossJTA-Configuring_options">
<title>Configuring options</title>
<para>
The following table shows the configuration features, with default values shown in italics. For more detailed information, the relevant section numbers are provided.
</para>
- <table frame='all'><title>JBossJTA configuration options.</title>
- <tgroup cols='3'>
+ <table frame="all" id="tabl-Transactions_JTA_Programmers_Guide-Configuring_options-JBossJTA_configuration_options.">
+ <title>JBossJTA configuration options.</title>
+ <tgroup cols="3">
<thead>
<row>
- <entry>Configuration Name</entry>
- <entry>Possibile Values</entry>
- <entry>Relevant Section</entry>
+ <entry>
+ Configuration Name
+ </entry>
+ <entry>
+ Possibile Values
+ </entry>
+ <entry>
+ Relevant Section
+ </entry>
</row>
</thead>
<tbody>
<row>
- <entry>com.arjuna.ats.jta.supportSubtransactions</entry>
- <entry>YES/NO</entry>
- <entry></entry>
+ <entry>
+ com.arjuna.ats.jta.supportSubtransactions
+ </entry>
+ <entry>
+ YES/NO
+ </entry>
+ <entry>
+ </entry>
</row>
<row>
- <entry>com.arjuna.ats.jta.jtaTMImplementation</entry>
- <entry>com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple/com.arjuna.ats.internal.jta.transaction.jts.TransactionManagerImple</entry>
- <entry></entry>
+ <entry>
+ com.arjuna.ats.jta.jtaTMImplementation
+ </entry>
+ <entry>
+ com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple/com.arjuna.ats.internal.jta.transaction.jts.TransactionManagerImple
+ </entry>
+ <entry>
+ </entry>
</row>
<row>
- <entry>com.arjuna.ats.jta.jtaUTImplementation</entry>
- <entry>com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple/com.arjuna.ats.internal.jta.transaction.jts.UserTransactionImple</entry>
- <entry></entry>
+ <entry>
+ com.arjuna.ats.jta.jtaUTImplementation
+ </entry>
+ <entry>
+ com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple/com.arjuna.ats.internal.jta.transaction.jts.UserTransactionImple
+ </entry>
+ <entry>
+ </entry>
</row>
<row>
- <entry>com.arjuna.ats.jta.xaBackoffPeriod</entry>
- <entry></entry>
- <entry></entry>
+ <entry>
+ com.arjuna.ats.jta.xaBackoffPeriod
+ </entry>
+ <entry>
+ </entry>
+ <entry>
+ </entry>
</row>
<row>
- <entry>com.arjuna.ats.jdbc.isolationLevel</entry>
- <entry>Any supported JDBC isolation level.</entry>
- <entry></entry>
+ <entry>
+ com.arjuna.ats.jdbc.isolationLevel
+ </entry>
+ <entry>
+ Any supported JDBC isolation level.
+ </entry>
+ <entry>
+ </entry>
</row>
<row>
- <entry>com.arjuna.ats.jta.xaTransactionTimetouEnabled</entry>
- <entry>true/false</entry>
- <entry>Chapter 3</entry>
+ <entry>
+ com.arjuna.ats.jta.xaTransactionTimetouEnabled
+ </entry>
+ <entry>
+ true/false
+ </entry>
+ <entry>
+ Chapter 3
+ </entry>
</row>
</tbody>
</tgroup>
</table>
</section>
+
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Examples.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Examples.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Examples.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,11 +2,11 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-Examples">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-Examples">
<title>Examples</title>
<para>
</para>
- <section id="Transactions_JTA_Programmers_Guide-Examples-JDBC_example">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Examples-JDBC_example">
<title>JDBC example</title>
<para>
The following code illustrates many of the points described above (note that for simplicity, much error checking code has been remove). This example assumes that you are using the transactional JDBC driver provided with JBossTS. For details about how to configure and use this driver see the previous Chapter.
@@ -139,7 +139,7 @@
</screen>
</section>
- <section id="Transactions_JTA_Programmers_Guide-Examples-Failure_recovery_example">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Examples-Failure_recovery_example">
<title>Failure recovery example</title>
<para>
This class implements the <interfacename>XAResourceRecovery</interfacename> interface for <code>XAResources</code>. The parameter supplied in setParameters can contain arbitrary information necessary to initialize the class once created. In this instance it contains the name of the property file in which the db connection information is specified, as well as the number of connections that this file contains information on (separated by ;).
@@ -347,11 +347,12 @@
* DB_JNDI_Host=qa02 DB_JNDI_Port=20000
*/
- private static final char BREAKCHARACTER = ';'; // delimiter for parameters
+ private static final char BREAKCHARACTER = ';'; // delimiter for parameters
</screen>
<para>
The class <classname>com.arjuna.ats.internal.jdbc.recovery.JDBC2RecoveryConnection</classname> may be used to create a new connection to the database using the same parameters that were used to create the initial connection.
</para>
</section>
+
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/JDBC_and_Transactions.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/JDBC_and_Transactions.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/JDBC_and_Transactions.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,11 +2,11 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-JDBC_and_Transactions">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-JDBC_and_Transactions">
<title>JDBC and Transactions</title>
<para>
</para>
- <section id="Transactions_JTA_Programmers_Guide-JDBC_and_Transactions-Using_the_transactional_JDBC_driver">
+ <section id="sect-Transactions_JTA_Programmers_Guide-JDBC_and_Transactions-Using_the_transactional_JDBC_driver">
<title>Using the transactional JDBC driver</title>
<para>
JBossJTA supports the construction of both local and distributed transactional applications which access databases using the JDBC 2.0 APIs. JDBC 2.0 supports two-phase commit of transactions, and is similar to the XA X/Open standard. The JDBC 2.0 support is found in the com.arjuna.ats.jdbc package.
@@ -44,13 +44,13 @@
<para>
However, these drivers and databases are no longer part of our supported platforms. They may continue to work with JBossTS, but we cannot make that guarantee.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Using_the_transactional_JDBC_driver-Managing_transactions">
<title>Managing transactions</title>
<para>
JBossJTA must be able to associate work performed on a JDBC connection with a specific transaction. Therefore, implicit transaction propagation and/or indirect transaction management must be used by applications, i.e., for each JDBC connection it must be possible for JBossJTA to determine the invoking thread’s current transaction context.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Using_the_transactional_JDBC_driver-Restrictions">
<title>Restrictions</title>
<para>
The following restrictions are imposed by limitations in the JDBC specifications and by JBossJTA to ensure that transactional interactions with JDBC databases can be correctly managed:
@@ -61,19 +61,19 @@
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-JDBC_and_Transactions-Transactional_drivers">
+ <section id="sect-Transactions_JTA_Programmers_Guide-JDBC_and_Transactions-Transactional_drivers">
<title>Transactional drivers</title>
<para>
The JBossJTA approach to incorporating JDBC connections within transactions is to provide transactional JDBC drivers through which all interactions occur. These drivers intercept all invocations and ensure that they are registered with, and driven by, appropriate transactions. There is a single type of transactional driver through which any JDBC driver can be driven; obviously if the database is not transactional then ACID properties cannot be guaranteed. This driver is <code>com.arjuna.ats.jdbc.TransactionalDriver</code>, which implements the <interfacename>java.sql.Driver</interfacename> interface.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Transactional_drivers-Loading_drivers">
<title>Loading drivers</title>
<para>
The driver may be directly instantiated and used within an application. For example:
</para>
</formalpara>
<screen>
-TransactionalDriver arjunaJDBC2Driver = new TransactionalDriver();
+TransactionalDriver arjunaJDBC2Driver = new TransactionalDriver();
</screen>
<para>
They can be registered with the JDBC driver manager (<code>java.sql.DriverManager</code>) by adding them to the Java system properties. The <property>jdbc.drivers</property> property contains a list of driver class names, separated by colons, that are loaded by the JDBC driver manager when it is initialized.
@@ -116,18 +116,19 @@
When you have loaded a driver, it is available for making a connection with a DBMS.
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-JDBC_and_Transactions-Connections">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-JDBC_and_Transactions-Connections">
<title>Connections</title>
<para>
In this section we shall discuss the notion of transactional JDBC connections, how they are managed within JBossJTA and the implications on using them within an application.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Making_the_connection">
<title>Making the connection</title>
<para>
Because JDBC connectivity in JBossJTA works by simply providing a new JDBC driver, application code can remain relatively the same to that when not using transactions. Typically, the application programmer need only start and terminate transactions.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-JDBC_2.0">
<title>JDBC 2.0</title>
<para>
Before describing the JDBC 2.0 support it is necessary to mention that the following properties can be set and passed to the JBossJTA driver (they are all located in the <classname>com.arjuna.ats.jdbc.TransactionalDriver</classname> class):
@@ -155,7 +156,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-XADataSources">
<title>XADataSources</title>
<para>
JDBC 2.0 connections are created from appropriate DataSources. Those connections which must participate within distributed transactions are obtained from <code>XADataSources</code>. Therefore, when using a JDBC 2.0 driver, JBossJTA will use the appropriate DataSource whenever a connection to the database is made. It will then obtain <code>XAResources</code> and register them with the transaction via the JTA interfaces. It is these <code>XAResources</code> which the transaction service will use when the transaction terminates in order to drive the database to either commit or rollback the changes made via the JDBC connection.
@@ -164,7 +165,7 @@
<para>
There are two ways in which the JBossJTA JDBC 2.0 support can obtain <code>XADataSources</code>. These will be explained in the following sections. Note, for simplicity we shall assume that the JDBC 2.0 driver is instantiated directly by the application.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Java_Naming_and_Directory_Interface_JNDI">
<title>Java Naming and Directory Interface (JNDI)</title>
<para>
In order to allow a JDBC driver to use arbitrary DataSources without having to know specific details about their implementations, DataSources are typically obtained from JNDI. A specific (XA)DataSource can be created and registered with an appropriate JNDI implementation, and the application (or JDBC driver) can later bind to and use it. Since JNDI only allows the application to see the (XA)DataSource as an instance of the interface (for example, <property>javax.sql.XADataSource</property>) rather than as an instance of the implementation class (for example, <property>com.mydb.myXADataSource</property>), the application is not tied at build time to only use a specific (XA)DataSource implementation.
@@ -200,37 +201,54 @@
Connection connection = arjunaJDBC2Driver.connect("jdbc:arjuna:jdbc/foo", dbProps);
</screen>
<para>
- The JNDI URL must be pre-pended with jdbc:arjuna: in order for the <code>ArjunaJDBC2Driver</code> to recognise that the DataSource must participate within transactions and be driven accordingly.
+ The JNDI URL must be pre-pended with jdbc:arjuna: in order for the <code>ArjunaJDBC2Driver</code> to recognise that the DataSource must participate within transactions and be driven accordingly.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Dynamic_class_instantiation">
<title>Dynamic class instantiation</title>
<para>
Many JDBC 2.0 implementations provide proprietary implementations of <interfacename>XADataSources</interfacename> that provide non-standard extensions to the specification. In order to allow the application to remain isolated from the actual JDBC 2.0 implementation it is using and yet continue to be able to use these extensions, JBossJTA hides the details of these proprietary implementations using dynamic class instantiation. In addition, the use of JNDI is not required when using this mechanism because the actual implementation of the <interfacename>XADataSource</interfacename> will be directly instantiated, albeit in a manner which will not tie an application or driver to a specific implementation. JBossJTA therefore has several classes which are for specific JDBC 2.0 implementations, and these can be selected at runtime by the application setting the <property>dynamicClass</property> property appropriately:
</para>
</formalpara>
- <table frame='all'><title>Dynamic Class property values for specific databases</title>
- <tgroup cols='2'>
- <thead>
- <row>
- <entry>Database Type</entry>
- <entry>Property Name</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Cloudscape 3.6</entry>
- <entry>com.arjuna.ats.internal.jdbc.drivers.cloudscape_3_6</entry>
- </row>
- <row>
- <entry>Sequelink 5.1</entry>
- <entry>com.arjuna.ats.internal.jdbc.drivers.sequelink_5_1</entry>
- </row>
- <row>
- <entry>Oracle 8.1.6</entry>
- <entry>com.arjuna.ats.internal.jdbc.drivers.oracle_8_1_6</entry>
- </row>
- </tbody>
- </tgroup>
+ <table frame="all" id="tabl-Transactions_JTA_Programmers_Guide-Connections-Dynamic_Class_property_values_for_specific_databases">
+ <title>Dynamic Class property values for specific databases</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Database Type
+ </entry>
+ <entry>
+ Property Name
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ Cloudscape 3.6
+ </entry>
+ <entry>
+ com.arjuna.ats.internal.jdbc.drivers.cloudscape_3_6
+ </entry>
+ </row>
+ <row>
+ <entry>
+ Sequelink 5.1
+ </entry>
+ <entry>
+ com.arjuna.ats.internal.jdbc.drivers.sequelink_5_1
+ </entry>
+ </row>
+ <row>
+ <entry>
+ Oracle 8.1.6
+ </entry>
+ <entry>
+ com.arjuna.ats.internal.jdbc.drivers.oracle_8_1_6
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<note>
<para>
@@ -251,7 +269,7 @@
TransactionalDriver arjunaJDBC2Driver = new TransactionalDriver();
Connection connection = arjunaJDBC2Driver.connect("jdbc:arjuna:sequelink://host:port;databaseName=foo",dbProperties);
</screen>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Using_the_connection">
<title>Using the connection</title>
<para>
Once the connection has been established (for example, using the <methodname>java.sql.DriverManager.getConnection</methodname> method), all operations on the connection will be monitored by JBossJTA. Note, it is not necessary to use the transactional connection within transactions. If a transaction is not present when the connection is used, then operations will be performed directly on the database.
@@ -290,13 +308,13 @@
ResultSet res1 = stmt.executeQuery("SELECT * FROM test_table");
</screen>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Connection_pooling">
<title>Connection pooling</title>
<para>
For each user name and password, JBossJTA will maintain a single instance of each connection for as long as that connection is in use. Subsequent requests for the same connection will get a reference to the originally created connection, rather than a new instance. Attempts to close the connection are allowed, but the connection will only actually be closed when all users (including transactions) have either finished with the connection, or issued close calls.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Reusing_connections">
<title>Reusing connections</title>
<para>
Some JDBC drivers allow the reuse of a connection for multiple different transactions once a given transaction has completed. Unfortunately this is not a common feature, and other drivers require a new connection to be obtained for each new transaction. By default, the JBossJTA transactional driver will always obtain a new connection for each new transaction. However, if an existing connection is available and is currently unused, it is possible to make JBossJTA reuse this connection. In order to do this, the reuseconnection=true option must be specified on the JDBC URL. For example:
@@ -305,19 +323,19 @@
<screen>
jdbc:arjuna:sequelink://host:port;databaseName=foo;reuseconnection=true
</screen>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Terminating_the_transaction">
<title>Terminating the transaction</title>
<para>
Whenever a transaction terminates (either explicitly by the application programmer, or implicitly when any associated transaction timeout expires) that has a JDBC connection registered with it, JBossJTA will drive the database (via the JDBC driver) to either commit or roll back any changes made to it. This happens transparently to the application.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-AutoCommit">
<title>AutoCommit</title>
<para>
If <code>AutoCommit</code> of the <code>java.sql.Connection</code> is set to true for JDBC 1.0 then the execution of every SQL statement is a separate top-level transaction, and grouping multiple statements to be managed within a single OTS transaction is not possible. Therefore, JBossJTA will disable <code>AutoCommit</code> on JDBC 1.0 connections before they can be used. If auto commit is subsequently set to true by the application, JBossJTA will raise the <code>java.sql.SQLException</code>.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-Connections-Setting_isolation_levels">
<title>Setting isolation levels</title>
<para>
When using the JBossJTA JDBC driver, it may be necessary to set the underlying transaction isolation level on the XA connection. By default, this is set to <code>TRANSACTION_SERIALIZABLE</code>, but you may want to set this to something more appropriate for your application. In order to do this, set the <property>com.arjuna.ats.jdbc.isolationLevel</property> property to the appropriate isolation level in string form, for example, <code>TRANSACTION_READ_COMMITTED</code>, or <code>TRANSACTION_REPEATABLE_READ</code>.
@@ -329,5 +347,6 @@
</para>
</note>
</section>
+
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Preface.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Preface.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Preface.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,14 +2,12 @@
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<preface id="Transactions_JTA_Programmers_Guide-Preface">
+<preface id="pref-Transactions_JTA_Programmers_Guide-Preface">
<title>Preface</title>
<para>
</para>
- <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
- <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
- <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- </xi:fallback>
- </xi:include>
+ <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ </xi:fallback></xi:include>
</preface>
+
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Revision_History.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Revision_History.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -18,3 +18,4 @@
</revdescription>
</revision>
</revhistory>
+
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/The_Resource_Manager.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/The_Resource_Manager.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/The_Resource_Manager.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,12 +2,12 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-The_Resource_Manager">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-Test">
<title>Test</title>
<para>
This is a test paragraph
</para>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-The_XAResource_Interface">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-The_XAResource_Interface">
<title>The XAResource Interface</title>
<para>
Whereas some transaction specifications and systems define a generic resource which can be used to register arbitrary resources with a transaction, the JTA is much more XA specific. The <interfacename>javax.transaction.xa.XAResource</interfacename> interface is a Java mapping of the <interfacename>XA</interfacename> interface. The <interfacename>XAResource</interfacename> interface defines the contract between a Resource Manager and a Transaction Manager in a distributed transaction processing environment. A resource adapter for a resource manager implements the <interfacename>XAResource</interfacename> interface to support association of a top-level transaction to a resource such as a relational database.
@@ -48,7 +48,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_XAResource_Interface-Extended_XAResource_control">
<title>Extended XAResource control</title>
<para>
By default, whenever an <code>XAResource</code> object is registered with a JTA compliant transaction service, you have no control over the order in which it will be invoked during the two-phase commit protocol, with respect to other <code>XAResource</code> objects. In JBossTS, however, there is support for controlling the order via the two interfaces <interfacename>com.arjuna.ats.jta.resources.StartXAResource</interfacename> and <interfacename>com.arjuna.ats.jta.resources.EndXAResource</interfacename>. By inheriting your <code>XAResource</code> instance from either of these interfaces, you control whether an instance of your class will be invoked first or last, respectively.
@@ -73,7 +73,7 @@
<para>
In order to utilize the LRCO in a distributed environment, it is necessary to disable interposition support. It is still possible to use implicit context propagation.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_XAResource_Interface-Enlisting_multiple_one_phase_aware_resources">
<title>Enlisting multiple one-phase aware resources</title>
<para>
As discussed in the Transaction Core documentation, in order to guarantee consistency (atomicity) of outcome between multiple participants (resources) within the same transaction, the two-phase commit protocol is used with a durable transaction log. In the case of possessing a single one-phase aware resource, it is still possible to achieve an atomic (all of nothing) outcome across resources by utilizing the Last Resource Commit Optimization, as explained earlier.
@@ -107,13 +107,14 @@
</caution>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Opening_a_Resource_Manager">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Opening_a_Resource_Manager">
<title>Opening a Resource Manager</title>
<para>
The X/Open <interfacename>XA</interfacename> interface requires that the transaction manager initialize a resource manager (xa_open) prior to any other xa_ calls. JTA requires initialization of a resource manager to be embedded within the resource adapter that represents the resource manager. The transaction manager does not need to know how to initialize a resource manager; it is only responsible for informing the resource manager about when to start and end work associated with a transaction and when to complete the transaction. The resource adapter is responsible for opening (initializing) the resource manager when the connection to the resource manager is established.
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Closing_a_Resource_Manager">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Closing_a_Resource_Manager">
<title>Closing a Resource Manager</title>
<para>
A resource manager is closed by the resource adapter as a result of destroying the transactional resource. A transaction resource at the resource adapter level is comprised of two separate objects:
@@ -137,7 +138,8 @@
The close notification allows the application server to perform any necessary cleanup work and to mark the physical XA connection as free for reuse, if connection pooling is in place.
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Threads_of_control">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Threads_of_control">
<title>Threads of control</title>
<para>
The X/Open <interfacename>XA</interfacename> interface specifies that the transaction association related xa calls must be invoked from the same thread context. This thread-of-control requirement is not applicable to the object-oriented component-based application run-time environment, in which application threads are dispatched dynamically at method invocation time. Different threads may be using the same connection resource to access the resource manager if the connection spans multiple method invocation. Depending on the implementation of the application server, different threads may be involved with the same <code>XAResource</code> object. The resource context and the transaction context may be operated independent of thread context. This means that it is possible for different threads to be invoking the start and end methods.
@@ -146,7 +148,8 @@
If the application server allows multiple threads to use a single <code>XAResource</code> object and the associated connection to the resource manager, it is the responsibility of the application server to ensure that there is only one transaction context associated with the resource at any point of time. Thus the <interfacename>XAResource</interfacename> interface requires that the resource managers be able to support the two-phase commit protocol from any thread context.
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Transaction_association">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Transaction_association">
<title>Transaction association</title>
<para>
Transactions are associated with a transactional resource via the start method, and disassociated from the resource via the <methodname>end</methodname> method. The resource adapter is responsible for internally maintaining an association between the resource connection object and the <code>XAResource</code> object. At any given time, a connection is associated with a single transaction, or it is not associated with any transaction at all. Because JTA does not support nested transactions it is an error for the start method to be invoked on a connection that is currently associated with a different transaction.
@@ -155,7 +158,8 @@
Interleaving multiple transaction contexts using the same resource may be done by the transaction manager as long as start and end are invoked properly for each transaction context switch. Each time the resource is used with a different transaction, the method end must be invoked for the previous transaction that was associated with the resource, and start must be invoked for the current transaction context.
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Externally_controlled_connections">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Externally_controlled_connections">
<title>Externally controlled connections</title>
<para>
For transactional application whose transaction states are managed by an application server, its resources must also be managed by the application server so that transaction association is performed properly. If an application is associated with a transaction, it is an error for the application to perform transactional work through the connection without having the connection’s resource object already associated with the global transaction. The application server must ensure that the <code>XAResource</code> object in use is associated with the transaction. This is done by invoking the <methodname>Transaction.enlistResource</methodname> method.
@@ -164,13 +168,14 @@
If a server side transactional application retains its database connection across multiple client requests, the application server must ensure that before dispatching a client request to the application thread, the resource is enlisted with the application’s current transaction context. This implies that the application server manages the connection resource usage status across multiple method invocations.
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Resource_sharing">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Resource_sharing">
<title>Resource sharing</title>
<para>
When the same transactional resource is used to interleave multiple transactions, it is the responsibility of the application server to ensure that only one transaction is enlisted with the resource at any given time. To initiate the transaction commit process, the transaction manager is allowed to use any of the resource objects connected to the same resource manager instance. The resource object used for the two-phase commit protocol does not need to have been involved with the transaction being completed.
</para>
<para>
- The resource adapter must be able to handle multiple threads invoking the <interfacename>XAResource</interfacename> methods concurrently for transaction commit processing. For example, with reference to the code below, suppose we have a transactional resource <code>r1</code>. Global transaction <code>xid1</code> was started and ended with <code>r1</code>. Then a different global transaction <code>xid2</code> is associated with <code>r1</code>. In the meanwhile, the transaction manager may start the two phase commit process for <code>xid1</code> using <code>r1</code> or any other transactional resource connected to the same resource manager. The resource adapter needs to allow the commit process to be executed while the resource is currently associated with a different global transaction.
+ The resource adapter must be able to handle multiple threads invoking the <interfacename>XAResource</interfacename> methods concurrently for transaction commit processing. For example, with reference to the code below, suppose we have a transactional resource <code>r1</code>. Global transaction <code>xid1</code> was started and ended with <code>r1</code>. Then a different global transaction <code>xid2</code> is associated with <code>r1</code>. In the meanwhile, the transaction manager may start the two phase commit process for <code>xid1</code> using <code>r1</code> or any other transactional resource connected to the same resource manager. The resource adapter needs to allow the commit process to be executed while the resource is currently associated with a different global transaction.
</para>
<screen>
XAResource xares = r1.getXAResource();
@@ -189,28 +194,30 @@
xares.commit(xid1, false);
</screen>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Local_and_global_transactions">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Local_and_global_transactions">
<title>Local and global transactions</title>
<para>
The resource adapter must support the usage of both local and global transactions within the same transactional connection. Local transactions are transactions that are started and coordinated by the resource manager internally. The <interfacename>XAResource</interfacename> interface is not used for local transactions. When using the same connection to perform both local and global transactions, the following rules apply:
</para>
- <itemizedlist>
- <listitem>
- <para>
- The local transaction must be committed (or rolled back) before starting a global transaction in the connection.
- </para>
- </listitem>
- <listitem>
- <para>
- The global transaction must be disassociated from the connection before any local transaction is started.
- </para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The local transaction must be committed (or rolled back) before starting a global transaction in the connection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The global transaction must be disassociated from the connection before any local transaction is started.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Transaction_timeouts">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Transaction_timeouts">
<title>Transaction timeouts</title>
<para>
- Timeout values can be associated with transactions in order to control their lifetime. If a transaction has not terminated (committed or rolled back) before the timeout value elapses, the transaction system will automatically roll it back. The <interfacename>XAResource</interfacename> interface supports a operation, which allows the timeout associated with the current transaction to be propagated to the resource manager and if supported, will override any default timeout associated with the resource manager. This can be useful when long running transactions may have lifetimes that would exceed the default and in which case, if the timeout were not altered, the resource manager would rollback before the transaction terminated and subsequently cause the transaction to roll back as well.
+ Timeout values can be associated with transactions in order to control their lifetime. If a transaction has not terminated (committed or rolled back) before the timeout value elapses, the transaction system will automatically roll it back. The <interfacename>XAResource</interfacename> interface supports a operation, which allows the timeout associated with the current transaction to be propagated to the resource manager and if supported, will override any default timeout associated with the resource manager. This can be useful when long running transactions may have lifetimes that would exceed the default and in which case, if the timeout were not altered, the resource manager would rollback before the transaction terminated and subsequently cause the transaction to roll back as well.
</para>
<para>
If no timeout value is explicitly set for a transaction, or a value of 0 is specified, then an implementation specific default value may be used. In the case of JBossTS, how this default value is set depends upon which JTA implementation you are using.
@@ -234,7 +241,8 @@
If the <property>com.arjuna.ats.jta.xaTransactionTimeoutEnabled</property> property is set to true (the default) then it will be called on all instances. Alternatively, the <methodname>setXATransactionTimeoutEnabled</methodname> method of <classname>com.arjuna.ats.jta.common.Configuration</classname> can be used.
</para>
</section>
- <section id="Transactions_JTA_Programmers_Guide-The_Resource_Manager-Dynamic_Registration">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Test-Dynamic_Registration">
<title>Dynamic Registration</title>
<para>
Dynamic registration is not supported in <interfacename>XAResource</interfacename> because of the following reasons:
@@ -252,5 +260,6 @@
</listitem>
</itemizedlist>
</section>
+
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transaction_Recovery.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transaction_Recovery.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transaction_Recovery.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,11 +2,11 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-Transaction_Recovery">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-Transaction_Recovery">
<title>Transaction Recovery</title>
<para>
</para>
- <section id="Transactions_JTA_Programmers_Guide-Transaction_Recovery-Failure_recovery">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Transaction_Recovery-Failure_recovery">
<title>Failure recovery</title>
<para>
During recovery, the Transaction Manager needs to be able to communicate to all resource managers that are in use by the applications in the system. For each resource manager, the Transaction Manager uses the <methodname>XAResource.recover</methodname> method to retrieve the list of transactions that are currently in a prepared or heuristically completed state. Typically, the system administrator configures all transactional resource factories that are used by the applications deployed on the system. An example of such a resource factory is the JDBC <code>XADataSource</code> object, which is a factory for the JDBC <code>XAConnection</code> objects.
@@ -41,10 +41,10 @@
</note>
</section>
- <section id="Transactions_JTA_Programmers_Guide-Transaction_Recovery-Recovering_XAConnections">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Transaction_Recovery-Recovering_XAConnections">
<title>Recovering XAConnections</title>
<para>
- When recovering from failures, JBossJTA requires the ability to reconnect to databases that were in use prior to the failures in order to resolve any outstanding transactions. Most connection information will be saved by the transaction service during its normal execution, and can be used during recovery to recreate the connection. However, it is possible that not all such information will have been saved prior to a failure (for example, a failure occurs before such information can be saved, but after the database connection is used). In order to recreate those connections it is necessary to provide implementations of the following JBossJTA interface <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename>, one for each database that may be used by an application.
+ When recovering from failures, JBossJTA requires the ability to reconnect to databases that were in use prior to the failures in order to resolve any outstanding transactions. Most connection information will be saved by the transaction service during its normal execution, and can be used during recovery to recreate the connection. However, it is possible that not all such information will have been saved prior to a failure (for example, a failure occurs before such information can be saved, but after the database connection is used). In order to recreate those connections it is necessary to provide implementations of the following JBossJTA interface <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename>, one for each database that may be used by an application.
</para>
<note>
<para>
@@ -107,7 +107,8 @@
</para>
</note>
</section>
- <section id="Transactions_JTA_Programmers_Guide-Transaction_Recovery-Shipped_XAResourceRecovery_implementations">
+
+ <section id="sect-Transactions_JTA_Programmers_Guide-Transaction_Recovery-Shipped_XAResourceRecovery_implementations">
<title>Shipped XAResourceRecovery implementations</title>
<para>
Recovery of <interfacename>XA</interfacename> datasources can sometimes be implementation dependant, requiring developers to provide their own <interfacename>XAResourceRecovery</interfacename> instances. However, JBossTS ships with several out-of-the-box implementations that may be useful.
@@ -147,5 +148,6 @@
</listitem>
</itemizedlist>
</section>
+
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,11 +2,11 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-Transactions">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-Transactions">
<title>Transactions</title>
<para>
</para>
- <section id="Transactions_JTA_Programmers_Guide-Transactions-The_API">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Transactions-The_API">
<title>The API</title>
<para>
The Java Transaction API consists of three elements: a high-level application transaction demarcation interface, a high-level transaction manager interface intended for application server, and a standard Java mapping of the X/Open XA protocol intended for transactional resource manager. All of the JTA classes and interfaces occur within the <package>javax.transaction</package> package, and the corresponding JBossJTA implementations within the <package>com.arjuna.ats.jta</package> package.
@@ -16,7 +16,7 @@
Each Xid that JBossTS creates must have a unique node identifier encoded within it and JBossTS will only recover transactions and states that match a specified node identifier. The node identifier to use should be provided to JBossTS via the <property>com.arjuna.ats.arjuna.xa.nodeIdentifier</property> property. You must make sure this value is unique across your JBossTS instances. If you do not provide a value, then JBossTS will fabricate one and report the value via the logging infrastructure. The contents of this should be alphanumeric.
</para>
</caution>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_API-UserTransaction">
<title>UserTransaction</title>
<para>
The <interfacename>UserTransaction</interfacename> interface provides applications with the ability to control transaction boundaries. It has methods for beginning, committing, and rolling back top-level transactions: nested transactions are not supported, and begin throws the <code>NotSupportedException</code> when the calling thread is already associated with a transaction. <interfacename>UserTransaction</interfacename> automatically associates newly created transactions with the invoking thread.
@@ -42,7 +42,7 @@
</para>
</listitem>
</orderedlist>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_API-TransactionManager">
<title>TransactionManager</title>
<para>
The <interfacename>TransactionManager</interfacename> interface allows the application server to control transaction boundaries on behalf of the application being managed.
@@ -76,7 +76,7 @@
In a multi-threaded environment it is possible that multiple threads are active within the same transaction. If checked transaction semantics have been disabled, or the transaction times out, then it is possible for a transaction to be terminated by a thread other than the one that created it. In this case, it is often important that this information is communicated to the creator. JBossTS does this during commit or rollback by throwing <code>IllegalStateException</code>.
</para>
</note>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_API-Suspending_and_resuming_a_transaction">
<title>Suspending and resuming a transaction</title>
<para>
The JTA supports the concept of a thread temporarily suspending and resuming transactions to enable it to perform non-transactional work. The suspend method is called to temporarily suspend the current transaction that is associated with the calling thread, i.e., so that the thread is no longer operating within its scope. If the thread is not associated with any transaction, a null object reference is returned; otherwise, a valid <code>Transaction</code> object is returned. The <code>Transaction</code> object can later be passed to the resume method to reinstate the transaction context.
@@ -103,7 +103,7 @@
<para>
When a transaction is suspended the application server must ensure that the resources in use by the application are no longer registered with the suspended transaction. When a resource is de-listed this triggers the Transaction Manager to inform the resource manager to disassociate the transaction from the specified resource object. When the application’s transaction context is resumed, the application server must ensure that the resources in use by the application are again enlisted with the transaction. Enlisting a resource as a result of resuming a transaction triggers the Transaction Manager to inform the resource manager to re-associate the resource object with the resumed transaction.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_API-The_Transaction_interface">
<title>The Transaction interface</title>
<para>
The <interfacename>Transaction</interfacename> interface allows operations to be performed on the transaction associated with the target object. Every top-level transaction is associated with one <code>Transaction</code> object when the transaction is created. The <code>Transaction</code> object can be used to:
@@ -134,14 +134,14 @@
<para>
The <methodname>commit</methodname> and <methodname>rollback</methodname> methods allow the target object to be committed or rolled back. The calling thread is not required to have the same transaction associated with the thread. If the calling thread is not allowed to commit the transaction, the transaction manager throws an exception. At present JBossJTA does not impose restrictions on threads terminating transactions.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_API-Resource_enlistment">
<title>Resource enlistment</title>
<para>
Transactional resources such as database connections are typically managed by the application server in conjunction with some resource adapter and optionally with connection pooling optimization. In order for an external transaction manager to co-ordinate transactional work performed by the resource managers, the application server must enlist and de-list the resources used in the transaction. These resources (participants) are enlisted with the transaction so that they can be informed when the transaction terminates, for example, are driven through the two-phase commit protocol.
</para>
</formalpara>
<para>
- As stated previously, the JTA is much more closely integrated with the XA concept of resources than the arbitrary objects. For each resource in-use by the application, the application server invokes the <methodname>enlistResource</methodname> method with an <code>XAResource</code> object which identifies the resource in use. See for details on how the implementation of the <code>XAResource</code> can affect recovery in the event of a failure.
+ As stated previously, the JTA is much more closely integrated with the XA concept of resources than the arbitrary objects. For each resource in-use by the application, the application server invokes the <methodname>enlistResource</methodname> method with an <code>XAResource</code> object which identifies the resource in use. See for details on how the implementation of the <code>XAResource</code> can affect recovery in the event of a failure.
</para>
<para>
The enlistment request results in the transaction manager informing the resource manager to start associating the transaction with the work performed through the corresponding resource. The transaction manager is responsible for passing the appropriate flag in its <methodname>XAResource.start</methodname> method call to the resource manager.
@@ -152,7 +152,7 @@
<para>
The de-list request results in the transaction manager informing the resource manager to end the association of the transaction with the target <code>XAResource</code>. The flag value allows the application server to indicate whether it intends to come back to the same resource whereby the resource states must be kept intact. The transaction manager passes the appropriate flag value in its <methodname>XAResource.end</methodname> method call to the underlying resource manager.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_API-Transaction_synchronization">
<title>Transaction synchronization</title>
<para>
Transaction synchronization allows the application server to be notified before and after the transaction completes. For each transaction started, the application server may optionally register a Synchronization call back object to be invoked by the transaction manager:
@@ -170,7 +170,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-The_API-Transaction_equality">
<title>Transaction equality</title>
<para>
The transaction manager implements the Transaction object’s equals method to allow comparison between the target object and another Transaction object. The equals method should return true if the target object and the parameter object both refer to the same global transaction.
@@ -184,5 +184,6 @@
boolean isSame = txObj.equals(someOtherTxObj);
</screen>
</section>
+
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions_JTA_Programmers_Guide.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions_JTA_Programmers_Guide.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Transactions_JTA_Programmers_Guide.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -3,16 +3,16 @@
]>
<book>
- <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="An_Introduction_to_the_JTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="The_Resource_Manager.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Transaction_Recovery.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="JDBC_and_Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Configuring_JBossJTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Using_JBossJTA_in_Application_Servers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="An_Introduction_to_the_JTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="The_Resource_Manager.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Transaction_Recovery.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="JDBC_and_Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Configuring_JBossJTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Using_JBossJTA_in_Application_Servers.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</book>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Using_JBossJTA_in_Application_Servers.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Using_JBossJTA_in_Application_Servers.xml 2008-07-28 22:01:07 UTC (rev 76329)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Using_JBossJTA_in_Application_Servers.xml 2008-07-28 22:01:44 UTC (rev 76330)
@@ -2,32 +2,32 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_JTA_Programmers_Guide-Using_JBossJTA_in_Application_Servers">
+<chapter id="chap-Transactions_JTA_Programmers_Guide-Using_JBossJTA_in_Application_Servers">
<title>Using JBossJTA in Application Servers</title>
<para>
</para>
- <section id="Transactions_JTA_Programmers_Guide-Using_JBossJTA_in_Application_Servers-JBoss_Application_Server">
+ <section id="sect-Transactions_JTA_Programmers_Guide-Using_JBossJTA_in_Application_Servers-JBoss_Application_Server">
<title>JBoss Application Server</title>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-JBoss_Application_Server-Service_Configuration">
<title>Service Configuration</title>
<para>
- The JBoss Transaction Service is configured primarily via the XML files stored in the etc directory, but when run as a JBOSS service there are a number of configurable attributes available. They are as follows:
+ The JBoss Transaction Service is configured primarily via the XML files stored in the etc directory, but when run as a JBOSS service there are a number of configurable attributes available. They are as follows:
</para>
</formalpara>
<itemizedlist>
<listitem>
<para>
- TransactionTimeout – The default transaction timeout to be used for new transactions. Specified as an integer in seconds.
+ TransactionTimeout – The default transaction timeout to be used for new transactions. Specified as an integer in seconds.
</para>
</listitem>
<listitem>
<para>
- StatisticsEnabled – This determines whether or not the transaction service should gather statistical information. This information can then be viewed using the PerformanceStatistics MBean. Specified as a Boolean. The default is to not gather this information.
+ StatisticsEnabled – This determines whether or not the transaction service should gather statistical information. This information can then be viewed using the PerformanceStatistics MBean. Specified as a Boolean. The default is to not gather this information.
</para>
</listitem>
<listitem>
<para>
- PropagateFullContext – This determines whether a full transactional context is propagated by context importer/exporter. If set to false only the current transaction context is propagated. If set to true the full transaction context (including parent transactions) is propagated.
+ PropagateFullContext – This determines whether a full transactional context is propagated by context importer/exporter. If set to false only the current transaction context is propagated. If set to true the full transaction context (including parent transactions) is propagated.
</para>
</listitem>
</itemizedlist>
@@ -38,30 +38,30 @@
<mbean code="com.arjuna.ats.jbossatx.jts.TransactionManagerService" name="jboss:service=TransactionManager">
<attribute name="TransactionTimeout">300</attribute>
-<attribute name="StatisticsEnabled>true</attribute>>
+<attribute name="StatisticsEnabled>true</attribute>>
</mbean>
</screen>
<para>
- The transaction service is configurable also via the standard JBoss Transaction Service property files. These are located in the JBossTS install location under the etc sub-directory.
+ The transaction service is configurable also via the standard JBoss Transaction Service property files. These are located in the JBossTS install location under the etc sub-directory.
</para>
<para>
- These files can be edited manually or through JMX. Each property file is exposed via an object with the name <code>com.arjuna.ts.properties</code> and an attribute of module where module is equal to the name of the module to be configured, for example, <code>com.arjuna.ts.properties:module=arjuna</code>.
+ These files can be edited manually or through JMX. Each property file is exposed via an object with the name <code>com.arjuna.ts.properties</code> and an attribute of module where module is equal to the name of the module to be configured, for example, <code>com.arjuna.ts.properties:module=arjuna</code>.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-JBoss_Application_Server-Logging">
<title>Logging</title>
<para>
In order to make JBossTS logging semantically consistent with JBossAS, the TransactionManagerService modifies the level of some log messages. This is achieved by overriding the value of the <property>com.arjuna.common.util.logger</property> property given in the <filename>jbossjta-properties.xml</filename> file. Therefore, the value of this property will have no effect on the logging behaviour when running embedded in JBossAS. By forcing use of the log4j_releveler logger, the TransactionManagerService causes all INFO level messages in the transaction code to be modified to behave as DEBUG messages. Therefore, these messages will not appear in log files if the filter level is INFO. All other log messages behave as normal.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-JBoss_Application_Server-The_services">
<title>The services</title>
<para>
There is currently one service offered by the JBOSS integration called TransactionManagerService. Here we shall discuss what this service does.
</para>
</formalpara>
<para>
- The transaction manager service’s main purpose is to ensure the recovery manager is started. It also binds the JBossTS JTA transaction manager to java:/TransactionManager name with the JNDI provider. This service depends upon the existence of the CORBA ORB Service and it must be using JacORB as the underlying ORB implementation.
+ The transaction manager service’s main purpose is to ensure the recovery manager is started. It also binds the JBossTS JTA transaction manager to java:/TransactionManager name with the JNDI provider. This service depends upon the existence of the CORBA ORB Service and it must be using JacORB as the underlying ORB implementation.
</para>
<para>
There are two instances of this service:
@@ -78,15 +78,16 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_JTA_Programmers_Guide-JBoss_Application_Server-Ensuring_Transactional_Context_is_Propagated_to_the_Server">
<title>Ensuring Transactional Context is Propagated to the Server</title>
<para>
- It is possible to coordinate transactions from a coordinator which is not located within the JBoss server (e.g. using transactions created by an external OTS server). To ensure the transaction context is propagated via JRMP invocations to the server, the transaction propagation context factory needs to be explicitly set for the JRMP invoker proxy. This is done as follows:
+ It is possible to coordinate transactions from a coordinator which is not located within the JBoss server (e.g. using transactions created by an external OTS server). To ensure the transaction context is propagated via JRMP invocations to the server, the transaction propagation context factory needs to be explicitly set for the JRMP invoker proxy. This is done as follows:
</para>
</formalpara>
<screen>
JRMPInvokerProxy.setTPCFactory( new com.arjuna.ats.internal.jbossatx.jts.PropagationContextManager() );
</screen>
</section>
+
</chapter>
More information about the jboss-cvs-commits
mailing list