[jboss-svn-commits] JBL Code SVN: r32049 - 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 23:00:48 EST 2010
Author: misty at redhat.com
Date: 2010-03-11 23:00:47 -0500 (Thu, 11 Mar 2010)
New Revision: 32049
Added:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Interfaces_for_Extending_OTS.xml
Modified:
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/JTS_Programmers_Guide.xml
Log:
Interfaces for Configurating OTS
Modified: 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 2010-03-12 01:03:00 UTC (rev 32048)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Constructing_OTS_Application.xml 2010-03-12 04:00:47 UTC (rev 32049)
@@ -170,7 +170,7 @@
<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>
+ <section>
<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:
@@ -231,8 +231,8 @@
// end of transactional operation
};
</programlisting>
- </example>
- <example>
+ </section>
+ <section>
<title>Example of a transactional object</title>
<para>
A BankAccount2 is an object with external resources that inherits from the TransactionalObject interface:
@@ -263,7 +263,7 @@
res2.increment_num_transactions();
} // end of transactional operation
</programlisting>
- </example>
+ </section>
</section>
</section>
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Interfaces_for_Extending_OTS.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Interfaces_for_Extending_OTS.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Interfaces_for_Extending_OTS.xml 2010-03-12 04:00:47 UTC (rev 32049)
@@ -0,0 +1,255 @@
+<?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><application>JBoss Transaction Service</application> Interfaces for Extending the OTS</title>
+ <para>
+ This chapter contains a description of the use of the <application>JBoss Transaction Service</application> classes which provide extensions to the Object Transaction Suite (OTS) interfaces. These advanced interfaces are all written on top of the basic OTS engine described previously and have been designed so that applications written using them will continue to operate on other OTS implementations, but without the added functionality.
+ </para>
+ <para>
+ These features can be summarized below:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><classname>AtomicTransaction</classname> class</term>
+ <listitem><para>provides a more manageable interface to the OTS transaction than <classname>CosTransactions::Current</classname>, and automatically keeps track of transaction scope. In addition, it allows the creation of nested top-level transactions in a more natural manner than that provided by the OTS.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>advanced subtransaction-Resource classes</term>
+ <listitem><para>allow nested transactions to use a two-phase commit protocol, giving all of the benefits of using nested transactions. These Resources can also be ordered within <application>JBoss Transaction Service</application>, enabling the programmer to control when a Resource will be called during the commit/abort protocol with respect to other Resources.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>implicit context propagation between client and server (where available)</term>
+ <listitem><para>However, where this is not available an explicit interposition class is provided which simplifies the work required by the programmer to do interposition. The <application>JBoss Transaction Service</application> API, Transactional Objects for Java, outlined in Chapter 2 requires either explicit or implicit interposition, even in a stand-alone mode when using a separate transaction manager. Transactional Objects for Java is fully described in the TxCore manuals.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <note>
+ <para>
+ the extensions to the <filename>CosTransactions.idl</filename> are located in the <package>com.arjuna.ArjunaOTS</package> package and the <filename>ArjunaOTS.idl</filename> file.
+ </para>
+ </note>
+
+ <section>
+ <title>Nested Transactions</title>
+ <para>
+ As was mentioned previously, the OTS implementation of nested transactions is extremely limited, and can lead to the generation of inconsistent results: a subtransaction coordinator discovers part way through committing that some resources cannot commit; however, it cannot tell the committed resources to abort.
+ </para>
+ <para>
+ In most transactional systems which support subtransactions, the subtransaction commit protocol is the same as a top-level transaction’s, i.e., there are two phases, a prepare and a commit/abort. Using a multi-phase commit protocol avoids the above problem of discovering that some resources cannot commit whereas others have already been told to commit. The first (prepare) phase is used to generate consensus on the commit outcome, and the second phase is used to enforce this outcome.
+ </para>
+ <para>
+ <application>JBoss Transaction Service</application> supports the strict OTS implementation of subtransactions for those resources derived from CosTransactions::SubtransactionAwareResource. However, if a resource is derived from ArjunaOTS::ArjunaSubtranAwareResource then it will be driven by a two-phase commit protocol whenever a nested transaction commits:
+ </para>
+ <example>
+ <title>ArjunaSubtranAwareResource</title>
+ <programlisting role="JAVA" language="Java">
+ interface ArjunaSubtranAwareResource :
+ CosTransactions::SubtransactionAwareResource
+ {
+ CosTransactions::Vote prepare_subtransaction ();
+ };
+ </programlisting>
+ </example>
+ <para>
+ During the first phase of the commit protocol the prepare_subtransaction method will be called, and the resource can behave as though it were being driven by a top-level transaction, i.e., it should make any state changes provisional upon the second phase of the protocol. Any changes to persistent state must still be provisional upon the commit/abort of the top-level transaction. Based upon the votes of all registered resources, <application>JBoss Transaction Service</application> will then either call commit_subtransaction or rollback_subtransaction.
+ </para>
+ <note>
+ <para>
+ this scheme can only work successfully if all resources registered within a given subtransaction are instances of the ArjunaSubtranAwareResource, and that once a resource has told the coordinator it can prepare it will not negate this decision.
+ </para>
+ </note>
+
+ </section>
+
+ <section>
+ <title>Extended Resources</title>
+ <para>
+ When resources are registered with a transaction, the transaction maintains them within a list (the intentions list) so that at termination time it can drive each resource appropriately, i.e., to commit or abort. However, the application programmer has no control over the order in which resources will be called, or whether previously registered resources should be replaced with newly registered resources. The <application>JBoss Transaction Service</application> interface ArjunaOTS::OTSAbstractRecord gives programmers this control.
+ </para>
+ <example>
+ <title>OTSAbstractRecord</title>
+ <programlisting role="JAVA" language="Java">
+ interface OTSAbstractRecord : ArjunaSubtranAwareResource
+ {
+ readonly attribute long typeId;
+ readonly attribute string uid;
+
+ boolean propagateOnAbort ();
+ boolean propagateOnCommit ();
+
+ boolean saveRecord ();
+ void merge (in OTSAbstractRecord record);
+ void alter (in OTSAbstractRecord record);
+
+ boolean shouldAdd (in OTSAbstractRecord record);
+ boolean shouldAlter (in OTSAbstractRecord record);
+ boolean shouldMerge (in OTSAbstractRecord record);
+ boolean shouldReplace (in OTSAbstractRecord record);
+ };
+ </programlisting>
+ <para>
+ The attributes and methods will now be described:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>typeId</term>
+ <listitem><para>returns the record type of the instance. This is one of the values of the enumerated type Record_type.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>uid</term>
+ <listitem><para>a stringified Uid for this record.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>propateOnAbort</term>
+ <listitem><para>by default, instances of OTSAbstractRecord should not be propagated to the parent transaction if the current transaction rolls back. By returning TRUE, the instance will be propagated.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>propagateOnCommit</term>
+ <listitem><para>by returning TRUE from this method, the instance will be propagated to the parent transaction if the current transaction commits; FALSE means it will not be propagated.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>saveRecord</term>
+ <listitem><para>by returning TRUE from this method <application>JBoss Transaction Service</application> will attempt to save sufficient information about the record to persistent store during commit to enable crash recovery mechanisms to replay the transaction termination in the event of a failure. If FALSE is returned then no information will be saved.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>merge</term>
+ <listitem><para>used when two records need to merge together.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>alter</term>
+ <listitem><para>used when a record should be altered.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>shouldAdd</term>
+ <listitem><para>returns true is the record should be added to the list, false if it should be discarded.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>shouldMerge</term>
+ <listitem><para>returns true is the two records should be merged into single record, false if it should be discarded.</para></listitem>
+ </varlistentry>
+ <varlistitem>
+ <term>shouldReplace</term>
+ <listitem><para>returns true if the record should replace an existing one, false otherwise.</para></listitem>
+ </varlistitem>
+ </variablelist>
+ <para>
+ When inserting a new record into the transaction’s intentions list, <application>JBoss Transaction Service</application> uses the following algorithm: if a record with the same type and uid has already been inserted, then the methods shouldAdd etc. will be invoked to determine whether this record should also be added. If no such match occurs, then the record will be inserted in the intentions list based on the type field, and ordered according to the uid, i.e., all of the records with the same type will appear ordered in the intentions list.
+ </para>
+ <note>
+ <para>
+ OTSAbstractRecord is derived from ArjunaSubtranAwareResource. Therefore, all instances of OTSAbstractRecord will also obtain the benefits of this interface.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title><classname>AtomicTransaction</classname></title>
+ <para>
+ In terms of the OTS, <classname>AtomicTransaction</classname> is the preferred interface to the OTS protocol engine. It is equivalent to CosTransactions::Current, but with more emphasis on easing application development. For example, if an instance of <classname>AtomicTransaction</classname> goes out of scope before it is terminated then it will automatically rollback the transaction. This is something which CosTransactions::Current cannot do. When building applications using <application>JBoss Transaction Service</application>, programmers are encouraged to use <classname>AtomicTransaction</classname> for the added benefits it provides. It is located in the <package>com.arjuna.ats.jts.extensions.ArjunaOTS</package> package.
+ </para>
+ <programlisting language="Java" role="JAVA">
+ public class AtomicTransaction
+ {
+ public AtomicTransaction ();
+ public void begin () throws SystemException, SubtransactionsUnavailable,
+ NoTransaction;
+ public void commit (boolean report_heuristics) throws SystemException,
+ NoTransaction, HeuristicMixed,
+ HeuristicHazard,TransactionRolledBack;
+ public void rollback () throws SystemException, NoTransaction;
+ public Control control () throws SystemException, NoTransaction;
+ public Status get_status () throws SystemException;
+ /* Allow action commit to be supressed */
+ public void rollbackOnly () throws SystemException, NoTransaction;
+
+ public void registerResource (Resource r) throws SystemException, Inactive;
+ public void
+ registerSubtransactionAwareResource (SubtransactionAwareResource)
+ throws SystemException, NotSubtransaction;
+ public void
+ registerSynchronization(Synchronization s) throws SystemException,
+ Inactive;
+ };
+ </programlisting>
+ <para>
+ AtomicTransaction provides operations to start an action (begin); commit an action (commit); and abort an action (rollback). Transaction nesting is determined dynamically; that is, any transaction started within the scope of another running transaction is deemed to be nested.
+ </para>
+ <para>
+ The TopLevelTransaction class, which is derived from AtomicTransaction, allows the creation of nested top-level transactions. Such transactions allow non-serializable and potentially non-recoverable side effects to be initiated from within a transaction and should be used with caution. Nested top-level transactions can be created using a combination of the CosTransactions::TransactionFactory and the suspend and resume methods of CosTransactions::Current. However, the TopLevelTransaction class provides a more user-friendly interface.
+ </para>
+ <note>
+ <para>
+ AtomicTransaction and TopLevelTransaction are completely compatible with CosTransactions::Current, i.e., the two transaction mechanisms can be used interchangeably within the same application/object.
+ </para>
+ </note>
+ <para>
+ AtomicTransaction/TopLevelTransaction are similar to CosTransactions::Current, with the intention of simplifying the interface between application programmer and the OTS. However, by using AtomicTransaction/TopLevelTransaction the programmer has the following advantages:
+ </para>
+ <itemizedlist>
+ <listitem><para>the ability to create nested top-level transactions which are automatically associated with the current thread. When the transaction ends, the previous transaction associated with the thread, if any, will become the thread’s current transaction.</para></listitem>
+ <listitem><para>instances of AtomicTransaction track scope and if such an instance goes out of scope before being terminated then it will be automatically aborted, aborting any children it may have.</para></listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Context Propagation Issues</title>
+ <para>
+ When using Transactional Objects for Java in a distributed manner, <application>JBoss Transaction Service</application> requires interposition to be used between client and object; this is also true if the application is local (i.e., client is co-located with object) but the transaction manager is remote. In the case of implicit context propagation, i.e., where the application object is derived from CosTransactions::TransactionalObject, then the application programmer need take no further action; <application>JBoss Transaction Service</application> will automatically provide interposition. However, where implicit propagation is not supported by the ORB, or is not being used by the application, the programmer must take additional action to enable interposition.
+ </para>
+ <para>
+ The class com.arjuna.ats.jts.ExplicitInterposition is provided to allow an application 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 registers itself with the original coordinator to enable it to correctly participate in the commit protocol. The application thread context is modified to become the surrogate transaction hierarchy; any transaction context currently associated with the thread will be lost. The interposition lasts for the lifetime of the explicit interposition object, at which point the application thread will no longer be associated with a transaction context, i.e., it will be set to null.
+ </para>
+
+ <note>
+ <para>
+ nterposition is intended only for those situations where the transactional object and the transaction occur within different processes, i.e., are not co-located. If the transaction is created locally to the client (invoker of the transactional object), i.e., is not managed by a separate transaction manager, then the explicit interposition class should not be used. The transaction will be implicitly associated with the transactional object because it resides within the same process.
+ </para>
+ </note>
+ <programlisting language="Java" role="JAVA">
+ public class ExplicitInterposition
+ {
+ public ExplicitInterposition ();
+
+ public void registerTransaction (Control control) throws InterpositionFailed, SystemException;
+
+ public void unregisterTransaction () throws InvalidTransaction,
+ SystemException;
+ };
+ </programlisting>
+
+ <para>
+ There are two ways in which a transaction context can be propagated between client and server: either as a reference to the client’s transaction Control , or the client could send the transaction context explicitly. Therefore, there are two ways in which the interposed transaction hierarchy can be created and registered. For example, consider the class Example which is derived from LockManager and has a method increment:
+ </para>
+
+ <programlisting language="Java" role="JAVA">
+ public boolean increment (Control control)
+ {
+ ExplicitInterposition inter = new ExplicitInterposition();
+
+ try
+ {
+ inter.registerTransaction(control);
+ }
+ catch (Exception e)
+ {
+ return false;
+ }
+
+ // do real work
+
+ inter.unregisterTransaction(); // should catch exceptions!
+
+ // return value dependant upon outcome
+ }
+ </programlisting>
+
+ <note>
+ <para>
+ if the Control passed to the register operation of ExplicitInterposition is null, then no exception will be thrown. The system will simply assume that the client did not send a transaction context to the server; a transaction created within the object will thus be a top-level transaction.
+ </para>
+ </note>
+ <para>
+ When the application returns, or prior to this when it has finished with the interposed hierarchy, the program should call unregisterTransaction to disassociate the thread of control from the hierarchy. This occurs automatically when the ExplicitInterposition object is garbage collected. However, since this may be after the transaction has terminated, <application>JBoss Transaction Service</application> will assume the thread is still associated with the transaction and will issue a warning about trying to terminate a transaction while threads are still active within it.
+ </para>
+</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-12 01:03:00 UTC (rev 32048)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-12 04:00:47 UTC (rev 32049)
@@ -8,6 +8,7 @@
<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="Interfaces_for_Extending_OTS.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