[jboss-svn-commits] JBL Code SVN: r32048 - labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Mar 11 20:03:01 EST 2010
Author: misty at redhat.com
Date: 2010-03-11 20:03:00 -0500 (Thu, 11 Mar 2010)
New Revision: 32048
Added:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Constructing_OTS_Application.xml
Modified:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml
Log:
Finished "Constructing OTS Application" chapter
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Constructing_OTS_Application.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Constructing_OTS_Application.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Constructing_OTS_Application.xml 2010-03-12 01:03:00 UTC (rev 32048)
@@ -0,0 +1,354 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>Constructing an OTS Application</title>
+
+ <section>
+ <title>Important Notes for <application>JBoss Transaction Service</application></title>
+ <para>
+ The following are important notes for programmers when building any application using <application>JBoss Transaction Service</application> (i.e., those which use the raw OTS (Object Transaction Service) interfaces or the extended <application>JBoss Transaction Service</application> API (Application Program Interface)).
+ </para>
+ <section>
+ <title>Initialisation</title>
+ <para>
+ It is important that <application>JBoss Transaction Service</application> is correctly initialised prior to any application object being created. In order to guarantee this, the programmer should use the <methodname>initORB</methodname> and <methodname>POA</methodname> methods described in the Orb Portability Guide. Consult the Orb Portability Guide if direct use of the <methodname>ORB_init</methodname> and <methodname>create_POA</methodname> methods provided by the underlying ORB is required.
+ </para>
+ </section>
+ <section>
+ <title>Implicit context propagation and interposition</title>
+ <para>
+ If implicit context propagation and interposition are required, then the programmer must ensure that <application>JBoss Transaction Service</application> is correctly initialised prior to objects being created. Implicit context propagation is only possible on those ORBs which either support filters/interceptors, or the CosTSPortability interface. Depending upon which type of functionality is required, the programmer must perform the following:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Implicit context propagation</term>
+ <listitem><para>set the <varname>OTS_CONTEXT_PROP_MODE</varname> property variable to CONTEXT.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Interposition</term>
+ <listitem><para>set the <varname>OTS_CONTEXT_PROP_MODE</varname> property variable to INTERPOSITION.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ If using the <application>JBoss Transaction Service</application> API the interposition must be used.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Writing applications using the raw OTS interfaces</title>
+ <para>
+ To participate within an OTS transaction, a programmer must be concerned with:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ creating Resource and SubtransactionAwareResource objects for each object which will participate within the transaction/subtransaction. These resources are responsible for the persistence, concurrency control, and recovery for the object. The OTS will invoke these objects during the prepare/commit/abort phase of the (sub)transaction, and the Resources must then perform all appropriate work.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ registering Resource and SubtransactionAwareResource objects at the correct time within the transaction, and ensuring that the object is only registered once within a given transaction. As part of registration a Resource will receive a reference to a RecoveryCoordinator which must be made persistent so that recovery can occur in the event of a failure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ ensuring that, in the case of nested transactions, any propagation of resources such as locks to parent transactions are correctly performed. Propagation of SubtransactionAwareResource objects to parents must also be managed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ in the event of failures, the programmer or system administrator is responsible for driving the crash recovery for each Resource which was participating within the transaction.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The OTS does not provide any Resource implementations. These must be provided by the application programmer or the OTS implementer. The interfaces defined within the OTS specification are too low-level for most application programmers. Therefore, we have designed <application>JBoss Transaction Service</application> to make use of raw Common Object Services interfaces but provide a higher-level API for building transactional applications and frameworks. This API automates much of the above activities concerned with participating in an OTS transaction.
+ </para>
+ </section>
+
+ <section>
+ <title>Transaction context management</title>
+ <para>
+ If implicit transaction propagation is being used the programmer should ensure that appropriate objects support the TransactionalObject interface; otherwise, the transaction contexts must be explicitly passed as parameters to the relevant operations.
+ </para>
+ <section>
+ <title>A transaction originator: indirect and implicit</title>
+ <para>
+ In the code fragments below, a transaction originator uses indirect context management and implicit transaction propagation; txn_crt is a pseudo object supporting the Current interface; the client uses the begin operation to start the transaction which becomes implicitly associated with the originator’s thread of control:
+ </para>
+ <programlisting role="JAVA" language="Java">
+ ...
+ txn_crt.begin();
+ // should test the exceptions that might be raised
+ ...
+ // the client issues requests, some of which involve
+ // transactional objects;
+ BankAccount1.makeDeposit(deposit);
+ ...
+ </programlisting>
+ <para>
+ The program commits the transaction associated with the client thread. The report_heuristics argument is set to false so no report will be made by the Transaction Service about possible heuristic decisions.
+ </para>
+ <programlisting role="JAVA" language="Java">
+ ...
+ txn_crt.commit(false);
+ ...
+ </programlisting>
+ </section>
+ <section>
+ <title>Transaction originator: direct and explicit</title>
+ <para>
+ In the following example, a transaction originator uses direct context management and explicit transaction propagation. The client uses a factory object supporting the CosTransactions::TransactionFactory interface to create a new transaction and uses the returned Control object to retrieve the Terminator and Coordinator objects.
+ </para>
+ <programlisting role="JAVA" language="Java">
+ ...
+ org.omg.CosTransactions.Control c;
+ org.omg.CosTransactions.Terminator t;
+ org.omg.CosTransactions.Coordinator co;
+ org.omg.CosTransactions.PropagationContext pgtx;
+
+ c = TFactory.create(0);
+ t = c.get_terminator();
+ pgtx = c.get_coordinator().get_txcontext();
+ ...
+ </programlisting>
+ <para>
+ The client issues requests, some of which involve transactional objects, in this case explicit propagation of the context is used. The Control object reference is passed as an explicit parameter of the request; it is declared in the OMG IDL of the interface.
+ </para>
+
+ <programlisting role="JAVA" language="Java">
+ ...
+ transactional_object.do_operation(arg, pgtx);
+ </programlisting>
+ <para>
+ The transaction originator uses the Terminator object to commit the transaction; the report_heuristics argument is set to false: so no report will be made by the Transaction Service about possible heuristic decisions.
+ </para>
+ <programlisting role="JAVA" language="Java">
+ ...
+ t.commit(false);
+ </programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>Implementing a transactional client</title>
+ <para>
+ The <methodname>commit</methodname> operation of Current or the Terminator interface takes the boolean report_heuristics parameter. If the report_heuristics argument is false, the <methodname>commit</methodname> operation can complete as soon as the Coordinator has made its decision to commit or rollback the transaction. The application is not required to wait for the Coordinator to complete the <methodname>commit</methodname> protocol by informing all the participants of the outcome of the transaction. This can significantly reduce the elapsed time for the <methodname>commit</methodname> operation, especially where participant Resource objects are located on remote network nodes. However, no heuristic conditions can be reported to the application in this case.
+ </para>
+ <para>
+ Using the report_heuristics option guarantees that the commit operation will not complete until the Coordinator has completed the <methodname>commit</methodname> protocol with all Resource objects involved in the transaction. This guarantees that the application will be informed of any non-atomic outcomes of the transaction via the HeuristicMixed or HeuristicHazard exceptions, but increases the application-perceived elapsed time for the <methodname>commit</methodname> operation.
+ </para>
+ </section>
+
+ <section>
+ <title>Implementing a Recoverable Server</title>
+ <para>
+ A Recoverable Server includes at least one transactional object and one resource object. The responsibilities of each of these objects are explained in the following sections.
+ </para>
+ <section>
+ <title>Transactional object</title>
+ <para>
+ The responsibilities of the transactional object are to implement the transactional object’s operations, and to register a Resource object with the Coordinator so commitment of the Recoverable Server’s resources, including any necessary recovery, can be completed.
+ </para>
+ <para>
+ The Resource object identifies the involvement of the Recoverable Server in a particular transaction. This means a Resource object may only be registered in one transaction at a time. A different resource object must be registered for each transaction in which a recoverable server is concurrently involved. A transactional object may receive multiple requests within the scope of a single transaction. It only needs to register its involvement in the transaction once. The <methodname>is_same_transaction</methodname> operation allows the transactional object to determine if the transaction associated with the request is one in which the transactional object is already registered.
+ </para>
+ <para>
+ The <methodname>hash_transaction</methodname> operations allow the transactional object to reduce the number of transaction comparisons it has to make. All Coordinators for the same transaction return the same hash code. The <methodname>is_same_transaction</methodname> operation need only be done on Coordinators which have the same hash code as the Coordinator of the current request.
+ </para>
+ </section>
+ <section>
+ <title>Resource object</title>
+ <para>
+ The responsibilities of a Resource object are to participate in the completion of the transaction, to update the Recoverable Server’s resources in accordance with the transaction outcome, and ensure termination of the transaction, including across failures. The protocols that the Resource object must follow were described in Chapter 4.
+ </para>
+ </section>
+ <section>
+ <title>Reliable servers</title>
+ <para>
+ A Reliable Server is a special case of a Recoverable Server. A Reliable Server can use the same interface as a Recoverable Server to ensure application integrity for objects that do not have recoverable state. In the case of a Reliable Server, the transactional object can register a Resource object that replies VoteReadOnly to prepare if its integrity constraints are satisfied (e.g., all debits have a corresponding credit), or replies VoteRollback if there is a problem. This approach allows the server to apply integrity constraints which apply to the transaction as a whole, rather than to individual requests to the server.
+ </para>
+ <example>
+ <title>Example of a recoverable server</title>
+ <para>
+ BankAccount1 is an object with internal resources. It inherits from both the TransactionalObject and the Resource interfaces:
+ </para>
+ <programlisting role="JAVA" language="Java">
+ interface BankAccount1:
+ CosTransactions::TransactionalObject, CosTransactions::Resource
+ {
+ ...
+ void makeDeposit (in float amt);
+ ...
+ };
+ </programlisting>
+ <para>
+ The corresponding Java class is:
+ </para>
+ <programlisting role="JAVA" language="Java">
+ public class BankAccount1
+ {
+ public void makeDeposit(float amt);
+ ...
+ };
+ </programlisting>
+ <para>
+ Upon entering, the context of the transaction is implicitly associated with the object’s thread. The pseudo object supporting the Current interface is used to retrieve the Coordinator object associated with the transaction.
+ </para>
+ <programlisting role="JAVA" language="Java">
+ void makeDeposit (float amt)
+ {
+ org.omg.CosTransactions.Control c;
+ org.omg.CosTransactions.Coordinator co;
+ c = txn_crt.get_control();
+ co = c.get_coordinator();
+ ...
+ </programlisting>
+ <para>
+ Before registering the resource the object should check whether it has already been registered for the same transaction. This is done using the <methodname>hash_transaction</methodname> and <methodname>is_same_transaction</methodname> operations.
+ </para>
+ <para>
+ <note>
+ <para>
+ This object registers itself as a resource. This imposes the restriction that the object may only be involved in one transaction at a time. This is not the recommended way for recoverable objects to participate within transactions, and is only used as an example.
+ </para>
+ </note>
+ </para>
+
+ <para>
+ If more parallelism is required, separate resource objects should be registered for involvement in the same transaction.
+ </para>
+ <programlisting role="JAVA" language="Java">
+ RecoveryCoordinator r;
+ r = co.register_resource(this);
+
+ // performs some transactional activity locally
+ balance = balance + f;
+ num_transactions++;
+ ...
+ // end of transactional operation
+ };
+ </programlisting>
+ </example>
+ <example>
+ <title>Example of a transactional object</title>
+ <para>
+ A BankAccount2 is an object with external resources that inherits from the TransactionalObject interface:
+ </para>
+ <programlisting role="JAVA" language="Java">
+ interface BankAccount2: CosTransactions::TransactionalObject
+ {
+ ...
+ void makeDeposit(in float amt);
+ ...
+ };
+
+ public class BankAccount2
+ {
+ public void makeDeposit(float amt);
+ ...
+ }
+ </programlisting>
+ <para>
+ Upon entering, the context of the transaction is implicitly associated with the object’s thread. The <methodname>makeDeposit</methodname> operation performs some transactional requests on external, recoverable servers. The objects res1 and res2 are recoverable objects. The current transaction context is implicitly propagated to these objects.
+ </para>
+ <programlisting role="JAVA" language="Java">
+ void makeDeposit(float amt)
+ {
+ balance = res1.get_balance(amt);
+ balance = balance + amt;
+ res1.set_balance(balance);
+ res2.increment_num_transactions();
+ } // end of transactional operation
+ </programlisting>
+ </example>
+ </section>
+ </section>
+
+ <section>
+ <title>Failure models</title>
+ <para>
+ The Transaction Service provides atomic outcomes for transactions in the presence of application, system or communication failures. This section describes the behaviour of application entities when failures occur.
+ </para>
+ <para>
+ From the viewpoint of each user object role, two types of failure are relevant: a failure affecting the object itself (local failure) and a failure external to the object (external failure), such as failure of another object or failure in the communication with that object.
+ </para>
+ <section>
+ <title>Transaction originator</title>
+ <section>
+ <title>Local failure</title>
+ <para>
+ A failure of a Transaction originator prior to the originator issuing <methodname>commit</methodname> will cause the transaction to be rolled back. A failure of the originator after issuing <methodname>commit</methodname> and before the outcome is reported may result in either commitment or rollback of the transaction depending on timing; in this case completion of the transaction takes place without regard to the failure of the originator.
+ </para>
+ </section>
+ <section>
+ <title>External failure</title>
+ <para>
+ Any external failure affecting the transaction prior to the originator issuing <methodname>commit</methodname> will cause the transaction to be rolled back; the standard exception TransactionRolledBack will be raised in the originator when it issues <methodname>commit</methodname>.
+ </para>
+ <para>
+ A failure after <methodname>commit</methodname> and before the outcome has been reported will mean that the client may not be informed of the transaction outcome, depending on the nature of the failure, and the use of the report_heuristics option of <methodname>commit</methodname>. For example, the transaction outcome will not be reported to the client if communication between the client and the Coordinator fails.
+ </para>
+ <para>
+ A client may use get_status on the Coordinator to determine the transaction outcome. However, this is not reliable because the status NoTransaction is ambiguous: it could mean that the transaction committed and has been forgotten, or that the transaction rolled back and has been forgotten.
+ </para>
+ <para>
+ If an originator needs to know the transaction outcome, including in the case of external failures, then either the originator’s implementation must include a Resource object so that it will participate in the two-phase commit procedure (and any recovery), or the originator and Coordinator must be located in the same failure domain (for example, the same execution environment).
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Transactional server</title>
+ <section>
+ <title>Local failure</title>
+ <para>
+ If the Transactional Server fails then optional checks by a Transaction Service implementation may cause the transaction to be rolled back; without such checks, whether the transaction rolls back depends on whether the commit decision has already been made (this would be the case where an unchecked client invokes commit before receiving all replies from servers).
+ </para>
+ </section>
+ <section>
+ <title>External failure</title>
+ <para>
+ Any external failure affecting the transaction during the execution of a Transactional Server will cause the transaction to be rolled back. If this occurs while the transactional object’s method is executing, the failure has no effect on the execution of this method. The method may terminate normally, returning the reply to its client. Eventually the TransactionRolledBack exception will be returned to a client issuing commit.
+ </para>
+ </section>
+ <section>
+ <title>Recoverable server</title>
+ <para>
+ Behaviour of a recoverable server when failures occur is determined by the two phase commit protocol between the Coordinator and the recoverable server’s Resource object. This protocol, including the local and external failure models and the required behaviour of the Resource, has been described previously.
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Summary</title>
+ <para>
+ In summary, when developing OTS applications using the raw OTS interfaces, the programmer must be concerned with:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ creating Resource and SubtransactionAwareResource objects for each object which will participate within the transaction/subtransaction. These resources are responsible for the persistence, concurrency control, and recovery for the object. The OTS will invoke these objects during the prepare/commit/abort phase of the (sub)transaction, and the Resources must then perform all appropriate work.
+ </para>
+ </listitem>
+ <listitem>
+ <para>registering Resource and SubtransactionAwareResource objects at the correct time within the transaction, and ensuring that the object is only registered once within a given transaction. As part of registration a Resource will receive a reference to a RecoveryCoordinator which must be made persistent so that recovery can occur in the event of a failure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>ensuring that, in the case of nested transactions, any propagation of resources such as locks to parent transactions are correctly performed. Propagation of SubtransactionAwareResource objects to parents must also be managed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>in the event of failures, the programmer or system administrator is responsible for driving the crash recovery for each Resource which was participating within the transaction.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The OTS does not provide any Resource implementations. These must be provided by the application programmer or the OTS implementer.
+ </para>
+ </section>
+</chapter>
+
Modified: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-11 23:53:18 UTC (rev 32047)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-12 01:03:00 UTC (rev 32048)
@@ -7,6 +7,7 @@
<xi:include href="Transaction_Processing_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="JBossTS_basics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="OTS_Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Constructing_OTS_Application.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<index />
</book>
More information about the jboss-svn-commits
mailing list