[jboss-svn-commits] JBL Code SVN: r32028 - in labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US: images and 1 other directory.

jboss-svn-commits at lists.jboss.org jboss-svn-commits at lists.jboss.org
Wed Mar 10 23:33:23 EST 2010 

Author: misty at redhat.com
Date: 2010-03-10 23:33:23 -0500 (Wed, 10 Mar 2010)
New Revision: 32028

Added:
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-control_and_resource_relationship.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_a_resource_with_a_transaction.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_subtransactionawareresource_with_subtransaction.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_subtransactionawareresource_with_subtransaction_as_resource.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-resource_and_recoverycoordinator_relationship.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_commit.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_rollback.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_commit.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_rollback.png
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-truncation_relationship.png
Modified:
   labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml
Log:
Finished the OTS Introduction chapter



Modified: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml	2010-03-10 23:50:24 UTC (rev 32027)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml	2010-03-11 04:33:23 UTC (rev 32028)
@@ -760,78 +760,464 @@
   <section>
     <title>Resource</title>
     <para>
+      The Transaction Service uses a two-phase commit protocol to complete a top-level transaction with each registered resource.
     </para>
+    <example>
+      <title>interface Resource</title>
+      <programlisting language="Java" role="JAVA">
+	{
+	Vote prepare ();
+	void rollback () raises (HeuristicCommit, HeuristicMixed,
+	HeuristicHazard);
+	void commit () raises (NotPrepared, HeuristicRollback,
+	HeuristicMixed, HeuristicHazard);
+	void commit_one_phase () raises (HeuristicRollback, HeuristicMixed,
+	HeuristicHazard);
+	void forget ();
+	};
+      </programlisting>
+      <para>Interface 3: The Resource Interface.</para>
+    </example>
+    <para>
+      The Resource interface defines the operations invoked by the transaction service. Each Resource object is implicitly associated with a single top-level transaction. A given Resource should not be registered with the same transaction more than once. This is because when a Resource is told to prepare/commit/abort it must do so on behalf of a specific transaction; however, the Resource methods do not specify the transaction identity: it is implicit, since a Resource can only be registered with a single transaction.
+    </para>
+    <para>
+      Transactional objects must register objects that support the Resource interface with the current transaction using the <methodname>register_resource</methodname> method of the transaction’s Coordinator interface. An object supporting the Coordinator interface will either be passed as a parameter (if explicit propagation is being used ) or may be retrieved using operations on the Current interface (if implicit propagation is used).  If the transaction is a subtransaction, then the Resource will not be informed of the subtransaction’s completion, and will be registered with its parent upon commit. This is illustrated below, where for simplicity we assume the hierarchy is only 2 deep.
+    </para>
+    <figure>
+      <title>Registering a Resource With a Transaction</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-registering_a_resource_with_a_transaction.png" format="PNG"/>
+	</imageobject>
+	<textobject>
+	  <para>Registering a Resource With a Transaction</para>
+	</textobject>
+      </mediaobject>
+    </figure>
+    <para>
+      A given Resource should not be registered with the same transaction more than once or it will receive multiple termination calls. It must not be registered with more than one transaction. This is because when a Resource is told to prepare/commit/abort it must do so on behalf of a specific transaction; however, the Resource methods do not specify the transaction identity. Therefore, the identity is implicit since the Resource should only be associated with a single transaction.
+    </para>
+    <para>
+      A single Resource or group of Resources are responsible for guaranteeing the <acronym>ACID</acronym> properties for the recoverable object they represent. The work Resources should perform can be summarized for each phase of the commit protocol:
+    </para>
+    <variablelist>
+      <varlistentry>
+	<term>prepare</term>
+	<listitem><para>If no persistent data associated with the resource has been modified within the transaction, then the Resource can return VoteReadOnly and forget about the transaction; it need not be contacted during the second phase of the commit protocol since it has made no state changes to either commit or roll back. If the resource is able to write (or has already written) all the data needed to commit the transaction to stable storage, as well as an indication that it has prepared the transaction, it can return VoteCommit. After receiving this response, the Transaction Service will eventually either commit or rollback. To support recovery, the resource should store the RecoveryCoordinator reference in stable storage. The resource can return VoteRollback under any circumstances; after returning this response the resource can forget the transaction. The resource reports inconsistent outcomes using the HeuristicMixed and HeuristicHazard exceptions. For example, if the R!
 esource has said it can commit and then decides it cannot, and must rollback. Heuristic decisions must be made persistent and remembered by the Resource until the transaction coordinator issues the <methodname>forget</methodname> method; this essentially tells the Resource that the heuristic decision has been noted (and possibly resolved).</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>rollback</term>
+	<listitem><para>If necessary, the resource should undo any changes made as part of the transaction. Heuristic exceptions can be used to report heuristic decisions related to the resource. If a heuristic exception is raised, the resource must remember this outcome until the <methodname>forget</methodname> operation is performed so that it can return the same outcome in case rollback is performed again. Otherwise, the resource can forget the transaction.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>commit</term>
+	<listitem><para>If necessary, the resource should commit all changes made as part of this transaction. As with rollback, heuristic exceptions can be raised. The NotPrepared exception is raised if the resource has not been prepared.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>commit_one_phase</term>
+	<listitem><para>Since there can be only a single resource, the HeuristicHazard exception is used to report heuristic decisions related to that resource. See Section <remark>Fix Me</remark> for how to disable the use of the one-phase commit protocol.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>forget</term>
+	<listitem><para>This operation is performed if the resource raised a heuristic exception. Once the coordinator has determined that the heuristic situation has been addressed, it will issue forget on the resource. The resource can then forget all knowledge of the transaction.</para></listitem>
+      </varlistentry>
+    </variablelist>
   </section>
 
   <section>
     <title>SubtransactionAwareResource</title>
+    
     <para>
+      An OTS implementation can support subtransactions. Recoverable objects that wish to participate within a nested transaction may support the SubtransactionAwareResource interface, a specialization of the Resource interface.
     </para>
+    <programlisting language="Java" role="JAVA">
+      interface SubtransactionAwareResource : Resource
+      {
+      void commit_subtransaction (in Coordinator parent);
+      void rollback_subtransaction ();
+      };
+    </programlisting>
+    <para>
+      Only by registering a SubtransactionAwareResource will a recoverable object be informed of the completion of a nested transaction. Registration is performed using either the <methodname>register_resource</methodname> or <methodname>register_subtran_aware</methodname> methods of the Coordinator or Current interfaces. Generally a recoverable object will register Resources to participate within the completion of top-level transactions, and SubtransactionAwareResources to be notified of the completion of subtransactions. The <methodname>commit_subtransaction</methodname> method is passed a reference to the parent transaction in order to allow subtransaction resources to register with these transactions, e.g., to perform propagation of locks.
+    </para>
+    <para>
+      It is important to realise that SubtransactionAwareResources are informed of the completion of a transaction after it has terminated, i.e., they cannot affect the outcome of the transaction. It is implementation specific as to how the OTS implementation will deal with any exceptions raised by SubtransactionAwareResources.
+    </para>
+    <para>
+      A SubtransactionAwareResource is registered with a transaction using either the <methodname>register_resource</methodname> method, or the <methodname>register_subtran_aware</methodname> method. Each method has subtly different requirements and effects:
+    </para>
+    <variablelist>
+      <varlistentry>
+	<term><methodname>register_resource</methodname></term>
+	<listitem><para>If the transaction is a subtransaction then the resource will be informed of its completion, and automatically registered with the subtransaction’s parent if it commits.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><methodname>register_subtran_aware</methodname></term>
+	<listitem><para>If the transaction is not a subtransaction, then an exception will be thrown. Otherwise, the resource will be informed of the completion of the subtransaction. However, unlike <methodname>register_resource</methodname>, it will not be propagated to the subtransaction’s parent if the transaction commits. If the resource requires this it must re-register using the supplied parent parameter.</para></listitem>
+      </varlistentry>
+    </variablelist>
+    <para>
+      Both of these registration techniques are illustrated in the following diagrams. Figure 11 shows how a SubtransactionAwareResource is registered with a subtransaction using the <methodname>register_subtran_aware</methodname> method:
+    </para>
+    <figure>
+      <title>Registering a SubtransactionAwareResource With a Subtransaction</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-registering_subtransactionawareresource_with_subtransaction.png" format="PNG"/>
+	</imageobject>
+	<textobject>
+	  <para>
+	    Registering a SubtransactionAwareResource With a Subtransaction
+	  </para>
+	</textobject>
+      </mediaobject>
+    </figure>
+    <para>
+      Figure 12 illustrates the mechanisms involved when a SubtransactionAwareResource is registered using the <methodname>register_resource</methodname> operation:
+    </para>
 
+    <figure>
+      <title>Registering a SubtransactionAwareResource With a Subtransaction as a Resource</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-registering_subtransactionawareresource_with_subtransaction_as_resource.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>
+	    Registering a SubtransactionAwareResource With a Subtransaction as a Resource
+	  </para>
+	</textobject>
+      </mediaobject>
+    </figure>
+
+    <para>
+      In either case, the resource cannot effect the outcome of the transaction completion. It is only informed of the transaction decision, and should attempt to act accordingly. However, if the resource cannot (e.g., it cannot commit when <methodname>commit_subtransaction</methodname> is called) then it can raise an exception, and the OTS will deal with it in an implementation specific manner (for example, it is valid for the OTS to ignore such exceptions).
+    </para>
     <section>
       <title><application>JBoss Transaction Service</application> Specifics</title>
       <para>
+	A SubtransactionAwareResource which raises an exception to the commitment of a transaction may result in inconsistencies within the transaction if other SubtransactionAwareResources have previously been told that the transaction committed. Therefore, <application>JBoss Transaction Service</application> forces the enclosing transaction to abort if an exception is raised.
       </para>
+      <para>
+	<application>JBoss Transaction Service</application> also provides extended subtransaction aware resources to overcome this, and other problems. See Section  for further details <remark>Fix Me</remark>.
+      </para>
     </section>
   </section>
 
   <section>
     <title>The Synchronization Interface</title>
     <para>
+      If an object wishes to be informed that a transaction is about to commit, it can register an object which is an instance of the Synchronization interface, using the <methodname>register_synchronization</methodname> operation of the Coordinator interface. Synchronizations are typically employed to flush volatile (cached) state, which may be being used to improve performance of an application, to a recoverable object or database prior to the transaction committing.
     </para>
+    <note>
+      <para>
+	Synchronizations can only be associated with top-level transactions, and an exception will be raised if an attempt is made to register a Synchronization with a subtransaction. Each object supporting the Synchronization interface is associated with a single top-level transaction.
+      </para>
+    </note>
+    <programlisting language="Java" role="JAVA">
+      interface Synchronization : TransactionalObject
+      {
+      void before_completion ();
+      void after_completion (in Status s);
+      };
+    </programlisting>
+    <para>
+      The method <methodname>before_completion</methodname> is called prior to the start of the two-phase commit protocol, and <methodname>after_completion</methodname> is called after the protocol has completed (the final status of the transaction is given as a parameter). If <methodname>before_completion</methodname> raises an exception, the transaction will rollback. Any exceptions thrown by <methodname>after_completion</methodname> will have no effect on the transaction outcome. The OTS only requires Synchronizations to be invoked if the transaction commits; if it rolls back, registered Synchronizations will not be informed. See Section <remark>Fix Me</remark> for further details.
+    </para>
+    <para>
+      Given the previous description of Control, Resource, SubtransactionAwareResource, and Synchronization, the following UML relationship diagram can be drawn:
+    </para>
 
+    <figure>
+      <title>Truncation Relationship</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-truncation_relationship.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>Truncation Relationship</para>
+	</textobject>
+      </mediaobject>
+      
+    </figure>
+
     <section>
       <title><application>JBoss Transaction Service</application> Specifics</title>
       <para>
+	Synchronizations are required to be called prior to the start of the top-level transaction commit protocol, and after it completes. However, if the transaction is told to rollback (e.g., by the application program invoking the rollback method on the Current pseudo-object), the Synchronizations associated with the transaction will not be contacted. To override this such that Synchronizations are called however the transaction terminates, set the <varname>OTS_SUPPORT_ROLLBACK_SYNC</varname> property variable to YES.
       </para>
+      <para>
+	When using distributed transactions and interposition, a local proxy for the top-level transaction coordinator will be created for any recipient of the transaction context. The proxy looks like a Resource/SubtransactionAwareResource and registers itself as such with the actual top-level transaction coordinator, and is used by the local recipient for registering Resources and Synchronizations locally. See Section <remark>Fix Me</remark> for further details. This can affect how Synchronizations are invoked during top-level transaction commit: normally all Synchronizations are invoked before any Resource/SubtransactionAwareResource objects are processed. However, with interposition, only those Synchronizations registered locally to the transaction coordinator will be called; Synchronizations registered with remote participants will only be called when the interposed proxy is invoked, which may be after locally registered Resource/SubtransactionAwareResource objects. <applicat!
 ion>JBoss Transaction Service</application> provides a mechanism whereby all Synchronizations are invoked before any Resource/SubtransactionAwareResource, no matter where they are registered. To enable this feature set the <varname>OTS_SUPPORT_INTERPOSED_SYNCHRONIZATION</varname> property variable to YES.
+      </para>
     </section>
   </section>
 
   <section>
     <title>Transactions and Registered Resources</title>
     <para>
+      The relationship between a transaction Control and resources registered with it is shown in the following diagram.
     </para>
+
+    <figure>
+      <title>Control And Resource Relationship</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-control_and_resource_relationship.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>Control and Resource Relationship</para>
+	</textobject>
+      </mediaobject>
+    </figure>
+    <para>
+      Figure 15 shows the course of events when committing a subtransaction which has had both Resource and SubtransactionAwareResource objects registered with it; we assume that the SubtransactionAwareResources were registered using <methodname>register_subtran_aware</methodname>. The Resources are not informed of the termination of the subtransaction, whereas the SubtransactionAwareResources are. However, only the Resources are automatically propagated to the parent transaction.
+    </para>
+    <figure>
+      <title>Subtransaction Commit</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-subtransaction_commit.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>Subtransaction Commit</para>
+	</textobject>
+      </mediaobject>
+    </figure>
+    <para>
+      Figure 16 illustrates what happens when the subtransaction rolls back. Any registered resources are discarded (not shown), and SubtransactionAwareResources are informed of the transaction outcome.
+    </para>
+    <figure>
+      <title>Subtransaction Rollback</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-subtransaction_rollback.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>Subtransaction Rollback</para>
+	</textobject>
+      </mediaobject>
+    </figure>
+    
+    <para>
+      Figure 17 shows the activity diagram for committing a top-level transaction; those subtransactions within the top-level transaction which have also successfully committed will have propagated SubtransactionAwareResources to the top-level transaction, and these will then participate within the two-phase commit protocol. As can be seen, however, prior to prepare being called, any registered Synchronizations are first contacted. Because we are using indirect context management, when the transaction commits, the transaction service changes the invoking thread’s transaction context.
+    </para>
+    <figure>
+      <title>Top-Level Transaction Commit</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-top_level_transaction_commit.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>Top-Level Transaction Commit</para>
+	</textobject>
+      </mediaobject>
+    </figure>
+    <para>
+      Figure 18 shows rolling back a top-level transaction.
+    </para>
+    
+    <figure>
+      <title>Top-Level Transaction Rollback</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-top_level_transaction_rollback.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>Top-Level Transaction Rollback</para>
+	</textobject>
+      </mediaobject>
+    </figure>
+    
   </section>
 
   <section>
     <title>TransactionalObject Interface</title>
     <para>
+      The TransactionalObject interface is used by an object to indicate that it is transactional. By supporting this interface, an object indicates that it wants the transaction context associated with the client thread to be associated with all operations on its interface. The TransactionalObject interface defines no operations.
     </para>
+    <para>
+      An OTS implementation is not required to initialise the transaction context of every request handler. It is required to do so only if the interface supported by the target object is derived from TransactionalObject. Otherwise, the initial transaction context of the thread is undefined. A transaction service implementation can raise the TRANSACTION_REQUIRED exception if a TransactionalObject is invoked outside the scope of a transaction, i.e., the transaction context is null.
+    </para>
+    <para>
+      In a single-address space application (i.e., all objects reside within the same process), transaction contexts are implicitly shared between “clients” and objects, regardless of whether or not the objects support the TransactionalObject interface. Therefore, in order to preserve distribution transparency, where implicit transaction propagation is supported <application>JBoss Transaction Service</application> can be made to always propagate transaction contexts to objects. The default, which is only to propagate if the object is a TransactionalObject, can be overridden by setting the environment variable <varname>OTS_ALWAYS_PROPAGATE_CONTEXT</varname> to NO.
+    </para>
+    <para>
+      By default, <application>JBoss Transaction Service</application> does not require that objects supporting the TransactionalObject interface are invoked within the scope of a transaction. Rather, this it is left up to the object to determine whether it should be invoked within a transaction; if so, it should throw the TransactionRequired exception. This can be overridden by setting the <varname>OTS_NEED_TRAN_CONTEXT</varname> shell environment variable to YES.
+    </para>
+    <note>
+      <para>
+	It is important to ensure that the settings for OTS_ALWAYS_PROPAGATE_CONTEXT and OTS_NEED_TRAN_CONTEXT are identical at the client and the server. Failure to do this may result in abnormal termination of the application, depending upon which ORB is being used.
+      </para>
+    </note>
 
     <section>
       <title><application>JBoss Transaction Service</application> Specifics</title>
       <para>
+	In a single-address space application (i.e., all objects reside within the same process), transaction contexts are implicitly shared between “clients” and objects, regardless of whether or not the objects support the TransactionalObject interface. Therefore, in order to preserve distribution transparency, where implicit transaction propagation is supported <application>JBoss Transaction Service</application> will always propagate transaction contexts to objects. The default can be overridden by setting the environment variable <varname>OTS_ALWAYS_PROPAGATE_CONTEXT</varname> to NO.
       </para>
+      <para>
+	By default, <application>JBoss Transaction Service</application> does not require that objects supporting the TransactionalObject interface are invoked within the scope of a transaction. Rather, this it is left up to the object to determine whether it should be invoked within a transaction; if so, it should throw the TransactionRequired exception. This can be overridden by setting the <varname>OTS_NEED_TRAN_CONTEXT shell environment variable</varname> to YES.
+      </para>
     </section>
   </section>
 
   <section>
     <title>Interposition</title>
     <para>
+      OTS objects supporting the interfaces such as the Control interface are simply standard <acronym>CORBA</acronym> objects. This implies that when an interface is passed as a parameter in some operation call to a remote server only an object reference is passed. This ensures that any operations that the remote server performs on the interface are correctly performed on the real object. However, this can have substantial penalties for the application due to the overheads of remote invocation. For example, when the server registers a Resource with the current transaction that has the potential to be a remote invocation back to the originator of the transaction.
     </para>
+    <para>
+      To avoid this overhead, an implementation of the OTS may support interposition. This permits a server to create a local control object which acts as a local coordinator fielding registration requests that would normally have been passed back to the originator. This surrogate must register itself with the original coordinator to enable it to correctly participate in the commit protocol. Interposed coordinators effectively form a tree structure with their parent coordinators.
+    </para>
+    <para>
+      If interposition is required, then the programmer must ensure that <application>JBoss Transaction Service</application> is correctly initialized prior to objects being created; obviously it is necessary for both client and server to agree to use interposition. Interposition is only possible on those ORBs which either support filters/interceptors, or the CosTSPortability interface, since interposition implicitly requires the use of implicit transaction propagation. The programmer must set the <varname>OTS_CONTEXT_PROP_MODE</varname> property variable to INTERPOSITION.
+    </para>
+    <para>
+      If using the <application>JBoss Transaction Service</application> advanced API then interposition is required.
+    </para>
   </section>
 
   <section>
     <title>The RecoverCoordinator</title>
     <para>
+      A reference to a RecoveryCoordinator is returned as a result of successfully calling <methodname>register_resource</methodname> on the transaction Coordinator. This object, which is implicitly associated with a single Resource, can be used to drive the Resource through recovery procedures in the event of a failure occurring during the transaction.
     </para>
+
+    <figure>
+      <title>Resource and Recovery Coordinator</title>
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="images/figure-resource_and_recoverycoordinator_relationship.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	  <para>Resource and Recovery Coordinator</para>
+	</textobject>
+      </mediaobject>
+    </figure>
   </section>
 
   <section>
     <title>Checked Transaction Behavior</title>
     <para>
+      The OTS supports both checked and unchecked transaction behaviour. Checked transactions have a number of integrity constraints including:
     </para>
+    <itemizedlist>
+      <listitem>
+	<para>Ensuring that a transaction will not commit until all transactional objects involved in the transaction have completed their transactional requests.</para>
+      </listitem>
+      <listitem>
+	<para>Ensuring that only the transaction originator can commit the transaction.</para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      In fact, checked transactional behaviour might be best described as classical transaction behaviour and is widely implemented. Checked behaviour is only possible if implicit propagation is used since the use of explicit propagation prevents the OTS from tracking which objects are involved in the transaction with any certainty.
+    </para>
+    <para>
+      In contrast, unchecked behaviour allows relaxed models of atomicity to be implemented. Any use of explicit propagation implies the possibility of unchecked behaviour since it is the application programmer’s responsibility to ensure the correct behaviour. Note that even using implicit propagation unchecked behaviour may still be possible since a server could unilaterally abort or commit the transaction via the Current interface.
+    </para>
+    <para>
+      Some Transaction Service implementations will enforce checked behaviour for the transactions they support, to provide an extra level of transaction integrity. The purpose of the checks is to ensure that all transactional requests made by the application have completed their processing before the transaction is committed. A checked Transaction Service guarantees that commit will not succeed unless all transactional objects involved in the transaction have completed the processing of their transactional requests. Rolling back the transaction does not require such as check, since all outstanding transactional activities will eventually rollback if they are not told to commit.
+    </para>
+    <para>
+      There are many possible implementations of checking in a Transaction Service. One provides equivalent function to that provided by the request/response inter-process communication models defined by X/Open. The X/Open Transaction Service model of checking is particularly important because it is widely implemented. It describes the transaction integrity guarantees provided by many existing transaction systems. These transaction systems will provide the same level of transaction integrity for object-based applications by providing a Transaction Service interface that implements the X/Open checks.
+    </para>
+    <para>
+      In X/Open, completion of the processing of a request means that the object has completed execution of its method and replied to the request. The level of transaction integrity provided by a Transaction Service implementing the X/Open model of checking provides equivalent function to that provided by the XATMI and TxRPC interfaces defined by X/Open for transactional applications. X/Open DTP Transaction Managers are examples of transaction management functions that implement checked transaction behaviour.
+    </para>
+    <para>
+      This implementation of checked behaviour depends on implicit transaction propagation. When implicit propagation is used, the objects involved in a transaction at any given time may be represented as a tree, the request tree for the transaction. The beginner of the transaction is the root of the tree. Requests add nodes to the tree, replies remove the replying node from the tree. Synchronous requests, or the checks described below for deferred synchronous requests, ensure that the tree collapses to a single node before commit is issued.
+    </para>
+    <para>
+      If a transaction uses explicit propagation, the Transaction Service cannot know which objects are or will be involved in the transaction; that is, a request tree cannot be constructed or assured. Therefore, the use of explicit propagation is not permitted by a Transaction Service implementation that enforces X/Open-style checked behaviour.
+    </para>
+    <para>
+      Applications that use synchronous requests implicitly exhibit checked behaviour. For applications that use deferred synchronous requests, in a transaction where all clients and objects are in the domain of a checking Transaction Service, the Transaction Service can enforce this property by applying a reply check and a commit check. The Transaction Service must also apply a resume check to ensure that the transaction is only resumed by application programs in the correct part of the request tree.
+    </para>
+    <variablelist>
+      <varlistentry>
+	<term>reply check</term>
+	<listitem><para>before allowing an object to reply to a transactional request, a check is made to ensure that the object has received replies to all its deferred synchronous requests that propagated the transaction in the original request. If this condition is not met, an exception is raised and the transaction is marked as rollback-only, that is, it cannot be successfully committed. A Transaction Service may check that a reply is issued within the context of the transaction associated with the request.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>commit check</term>
+	<listitem><para>before allowing commit to proceed, a check is made to ensure that:
+	<orderedlist>
+	  <listitem><para>the commit request for the transaction is being issued from the same execution environment that created the transaction.</para></listitem>
+	  <listitem><para>the client issuing commit has received replies to all the deferred synchronous requests it made that caused the propagation of the transaction.</para></listitem>
+	</orderedlist>
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>resume check</term>
+	<listitem><para>before allowing a client or object to associate a transaction context with its thread of control, a check is made to ensure that this transaction context was previously associated with the execution environment of the thread. This would be true if the thread either created the transaction or received it in a transactional operation.</para></listitem>
+      </varlistentry>
+    </variablelist>
+    
     <section>
       <title><application>JBoss Transaction Service</application> Specifics</title>
       <para>
+	Where support from the ORB is available, JBossTS supports X/Open checked transaction behaviour. However, unless the <varname>OTS_CHECKED_TRANSACTIONS</varname> property variable is set to YES this is disabled by default.
       </para>
+      <note>
+	<para>
+	  Checked transactions are only possible if using a co-located transaction manager, i.e., the use of a separate transaction manager processes does not allow checked transactions to be provided by the system.
+	</para>
+      </note>
+      <para>
+	In a multi-threaded application, multiple threads may be associated with a transaction during its lifetime, i.e., the threads share the context. In addition, it is possible that if one thread terminates a transaction other threads may still be active within it. In a distributed environment, it can be difficult to guarantee that all threads have finished with a transaction when it is terminated. By default, <application>JBoss Transaction Service</application> will issue a warning if a thread terminates a transaction when other threads are still active within it; however, it will allow the transaction termination to continue. Other solutions to this problem are possible, e.g., blocking the thread which is terminating the transaction until all other threads have disassociated themselves from the transaction context. Therefore, <application>JBoss Transaction Service</application> provides the com.arjuna.ats.arjuna.coordinator.CheckedAction class, which allows the thread/transa!
 ction termination policy to be overridden. Each transaction has an instance of this class associated with it, and application programmers can provide their own implementations on a per transaction basis.
+      </para>
+      <programlisting role="JAVA" language="Java">
+	public class CheckedAction
+	{
+	public CheckedAction ();
+
+	public synchronized void check (boolean isCommit, Uid actUid,
+	BasicList list);
+	};
+      </programlisting>
+      <para>
+	When a thread attempts to terminate the transaction and there are active threads within it, the system will invoke the <methodname>check</methodname> method on the transaction’s CheckedAction object. The parameters to the check method are:
+      </para>
+      <variablelist>
+	<varlistentry>
+	  <term>isCommit</term>
+	  <listitem><para>indicates whether the transaction is in the process of committing or rolling back.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>actUid</term>
+	  <listitem><para>the transaction identifier.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>list</term>
+	  <listitem><para>a list of all of the threads currently marked as active within this transaction.</para></listitem>
+	</varlistentry>
+      </variablelist>
+      <para>
+	When <methodname>check</methodname> returns, the transaction termination will continue. Obviously the state of the transaction at this point may be different from that when check was called, e.g., the transaction may subsequently have been committed.
+      </para>
+      <para>
+	The CheckedAction instance associated with a given transaction is set using the <methodname>setCheckedAction</methodname> method of Current.
+      </para>
     </section>
   </section>
 
   <section>
     <title>Summary of <application>JBoss Transaction Service</application> Implementation Decisions</title>
     <para>
+      The following list summarizes the run-time and compile-time design decisions used by <application>JBoss Transaction Service</application>.
     </para>
+    <itemizedlist>
+      <listitem><para>any execution environment (thread, process) can use a transaction Control.</para></listitem>
+      <listitem><para>Controls, Coordinators and Terminators are valid for use for the duration of the transaction if implicit transaction control is used (via Current). If using explicit control (via the TransactionFactory and Terminator), use the <methodname>destroyControl</methodname> method of the OTS class in com.arjuna.CosTransactions to signal when the information can be garbage collected.</para></listitem>
+      <listitem><para>Coordinators and Terminators can be propagated between execution environments.</para></listitem>
+      <listitem><para>if an attempt is made to commit a transaction when there are still active subtransactions within it, <application>JBoss Transaction Service</application> will rollback the parent and the subtransactions.</para></listitem>
+      <listitem><para>there is full support for nested transactions. However, if a resource raises an exception to the commitment of a subtransaction after other resources have previously been told that the transaction committed, <application>JBoss Transaction Service</application> forces the enclosing transaction to abort; this will guarantee that all resources used within the subtransaction will be returned to a consistent state. Support for subtransactions can be disabled at runtime by setting the <varname>OTS_SUPPORT_SUBTRANSACTIONS</varname> variable to NO.</para></listitem>
+      <listitem><para>Current should be obtained using the <methodname>get_current</methodname> method of the OTS.</para></listitem>
+      <listitem><para>a timeout value of zero seconds is assumed for a transaction if not specified using set_timeout.</para></listitem>
+      <listitem><para>by default, Current does not use a separate transaction manager server. This can be overridden by setting the <varname>OTS_TRANSACTION_MANAGER</varname> environment variable. How the OTS locates the transaction manager is ORB specific. See the chapter on configuring <application>JBoss Transaction Service</application>.</para></listitem>
+      <listitem><para>checked transactions are not enabled by default. To enable them, set the OTS_CHECKED_TRANSACTIONS property to YES.</para></listitem>
+    </itemizedlist>
   </section>
   
 </chapter>

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-control_and_resource_relationship.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-control_and_resource_relationship.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_a_resource_with_a_transaction.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_a_resource_with_a_transaction.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_subtransactionawareresource_with_subtransaction.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_subtransactionawareresource_with_subtransaction.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_subtransactionawareresource_with_subtransaction_as_resource.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-registering_subtransactionawareresource_with_subtransaction_as_resource.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-resource_and_recoverycoordinator_relationship.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-resource_and_recoverycoordinator_relationship.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_commit.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_commit.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_rollback.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_rollback.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_commit.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_commit.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_rollback.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_rollback.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-truncation_relationship.png
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-truncation_relationship.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

More information about the jboss-svn-commits mailing list