[jboss-svn-commits] JBL Code SVN: r36224 - in labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US: extras and 1 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Dec 6 23:04:29 EST 2010
Author: misty at redhat.com
Date: 2010-12-06 23:04:28 -0500 (Mon, 06 Dec 2010)
New Revision: 36224
Added:
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ArjunaSubtranAwareResource.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/AtomicTransaction.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition_example.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/OTSAbstractRecord.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/img-2phase.png
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/jbossts-class-hierarchy.png
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/ots_architecture.png
Modified:
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/JBossTS_Interface.xml
Log:
Converted JBossTS_Interface.xml
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/JBossTS_Interface.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/JBossTS_Interface.xml 2010-12-07 02:51:43 UTC (rev 36223)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/JBossTS_Interface.xml 2010-12-07 04:04:28 UTC (rev 36224)
@@ -3,7 +3,370 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaJTS_Development_Guide.ent">
%BOOK_ENTITIES;
]>
-<chapter id="chap-ArjunaJTS_Development_Guide-Test_Chapter">
- <title></title>
+<chapter>
+ <title>JBossTS interfaces for extending the OTS</title>
+ <para>
+ This chapter contains a description of the use of the JBossTS classes you can use to extend the OTS
+ interfaces. These advanced interfaces are all written on top of the basic OTS engine described previously, and
+ applications which use them run on other OTS implementations, only without the added functionality.
+ </para>
+ <variablelist>
+ <title>Features</title>
+ <varlistentry>
+ <term>AtomicTransaction</term>
+ <listitem>
+ <para>
+ Provides a more manageable interface to the OTS transaction than
+ <interfacename>CosTransactions::Current</interfacename>. It automatically keeps track of transaction scope,
+ and allows you to create nested top-level transactions in a more natural manner than the one 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. These Resources can also be ordered within
+ JBossTS, enabling you to control the order in which <classname>Resource</classname>s are called during the
+ commit or abort protocol.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Implicit context propagation between client and server</term>
+ <listitem>
+ <para>
+ Where available, JBossTS uses implicit context propagation between client and server. Otherwise, JBossTS
+ provides an explicit interposition class, which simplifies the work involved in interposition. The JBossTS
+ API, <firstterm>Transactional Objects for Java (TXOJ)</firstterm>, requires either explicit or implicit
+ interposition. This is even true in a stand-alone mode when using a separate transaction manager. TXOJ is
+ fully described in the <citetitle>ArjunaCore Development Guide</citetitle>.
+ </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>
+ The OTS implementation of nested transactions is extremely limited, and can lead to the generation of inconsistent
+ results. One example is a scenario in which a subtransaction coordinator discovers part of the way through
+ committing that a resources cannot commit. It may not be able to 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. There are two phases, a <systemitem>prepare</systemitem> phase and a
+ <systemitem>commit</systemitem> or <systemitem>abort</systemitem> phase. Using a multi-phase commit protocol
+ avoids the above problem of discovering that one resources cannot commit after others have already been told to
+ commit. The <systemitem>prepare</systemitem> phase generates consensus on the commit outcome, and the
+ <systemitem>commit</systemitem> or <systemitem>abort</systemitem> phase enforces the outcome.
+ </para>
+ <para>
+ JBossTS supports the strict OTS implementation of subtransactions for those resources derived from
+ <interfacename>CosTransactions::SubtransactionAwareResource</interfacename>. However, if a resource is derived
+ from <interfacename>ArjunaOTS::ArjunaSubtranAwareResource</interfacename>, it is driven by a two-phase commit
+ protocol whenever a nested transaction commits.
+ </para>
+
+ <example>
+ <title>ArjunaSubtranAwareResource</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/ArjunaSubtranAwareResource.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ During the first phase of the commit protocol the <methodname>prepare_subtransaction</methodname> method is
+ called, and the resource behaves as though it were being driven by a top-level transaction, making any state
+ changes provisional upon the second phase of the protocol. Any changes to persistent state must still be
+ provisional upon the second phase of the top-level transaction, as well. Based on the votes of all registered
+ resources, JBossTS then calls either <methodname>commit_subtransaction</methodname> or
+ <methodname>rollback_subtransaction</methodname>.
+ </para>
+ <note>
+ <para>
+ This scheme only works successfully if all resources registered within a given subtransaction are instances of
+ the <interfacename>ArjunaSubtranAwareResource</interfacename> interface, and that after a resource tells the
+ coordinator it can prepare, it does not change its mind.
+ </para>
+ </note>
+
+ </section>
+
+ <section>
+ <title>Extended resources</title>
+ <para>
+ When resources are registered with a transaction, the transaction maintains them within a list, called the
+ <firstterm>intentions list</firstterm>. At termination time, the transaction uses the intentions list to drive
+ each resource appropriately, to commit or abort. However, you have no control over the order in which resources
+ are called, or whether previously-registered resources should be replaced with newly registered resources. The
+ JBossTS interface <interfacename>ArjunaOTS::OTSAbstractRecord</interfacename> gives you this level of control.
+ </para>
+
+ <example>
+ <title>OTSAbstractRecord</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/OTSAbstractRecord.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>typeId</entry>
+ <entry>
+ <para>
+ returns the record type of the instance. This is one of the values of the enumerated type
+ <type>Record_type</type>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>uid</entry>
+ <entry>
+ <para>
+ a stringified Uid for this record.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>propagateOnAbort</entry>
+ <entry>
+ <para>
+ by default, instances of <interfacename>OTSAbstractRecord</interfacename> should not be propagated to
+ the parent transaction if the current transaction rolls back. By returning <literal>TRUE</literal>, the
+ instance will be propagated.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>propagateOnCommit</entry>
+ <entry>
+ <para>
+ returning <literal>TRUE</literal> from this method causes the instance to be propagated to the parent
+ transaction if the current transaction commits. Returning <literal>FALSE</literal> disables the
+ propagation.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>saveRecord</entry>
+ <entry>
+ <para>
+ returning <literal>TRUE</literal> from this method causes JBossTS to try to save sufficient information
+ about the record to persistent state during commit, so that crash recovery mechanisms can replay the
+ transaction termination in the event of a failure. If <literal>FALSE</literal> is returned, no
+ information is saved.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>merge</entry>
+ <entry>
+ <para>
+ used when two records need to merge together.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>alter</entry>
+ <entry>
+ <para>
+ used when a record should be altered.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>shouldAdd</entry>
+ <entry>
+ <para>
+ returns <literal>true</literal> ii the record should be added to the list, <literal>false</literal> if
+ it should be discarded.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>shouldMerge</entry>
+ <entry>
+ <para>
+ returns <literal>true</literal> if the two records should be merged into a single record,
+ <literal>false</literal> otherwise.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>shouldReplace</entry>
+ <entry>
+ <para>
+ returns <literal>true</literal> if the record should replace an existing one, <literal>false</literal>
+ otherwise.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ When inserting a new record into the transaction’s intentions list, JBossTS uses the following algorithm:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ if a record with the same type and uid has already been inserted, then the methods
+ <methodname>shouldAdd</methodname>, and related methods, are invoked to determine whether this record should
+ also be added.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If no such match occurs, then the record is inserted in the intentions list based on the
+ <systemitem>type</systemitem> field, and ordered according to the uid. All of the records with the same type
+ appear ordered in the intentions list.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ <interfacename>OTSAbstractRecord</interfacename> is derived from
+ <interfacename>ArjunaSubtranAwareResource</interfacename>. Therefore, all instances of
+ <interfacename>OTSAbstractRecord</interfacename> inherit the benefits of this interface.
+ </para>
+ </section>
+
+ <section>
+ <title>AtomicTransaction</title>
+ <para>
+ In terms of the OTS, <interfacename>AtomicTransaction</interfacename> is the preferred interface to the OTS
+ protocol engine. It is equivalent to <interfacename>CosTransactions::Current</interfacename>, but with more
+ emphasis on easing application development. For example, if an instance of
+ <interfacename>AtomicTransaction</interfacename> goes out of scope before it is terminates, the transaction
+ automatically rolls back. <interfacename>CosTransactions::Current</interfacename> cannot provide this
+ functionality. When building applications using JBossTS, use <interfacename>AtomicTransaction</interfacename> for
+ the added benefits it provides. It is located in the <package>com.arjuna.ats.jts.extensions.ArjunaOTS</package>
+ package.
+ </para>
+
+ <example>
+ <title>AtomicTransaction</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/AtomicTransaction.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <table>
+ <title>AtomicTransaction's Methods</title>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>begin</entry>
+ <entry><para>Starts an action</para></entry>
+ </row>
+ <row>
+ <entry>commit</entry>
+ <entry><para>Commits an action</para></entry>
+ </row>
+ <row>
+ <entry>rollback</entry>
+ <entry><para>Abort an action</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Transaction nesting is determined dynamically. Any transaction started within the scope of another running
+ transaction is nested.
+ </para>
+ <para>
+ The <classname>TopLevelTransaction</classname> class, which is derived from
+ <interfacename>AtomicTransaction</interfacename>, allows creation of nested top-level transactions. Such
+ transactions allow non-serializable and potentially non-recoverable side effects to be initiated from within a
+ transaction, so use them with caution. You can create nested top-level transactions with a combination of the
+ <classname>CosTransactions::TransactionFactory</classname> and the <methodname>suspend</methodname> and
+ <methodname>resume</methodname> methods of <classname>CosTransactions::Current</classname>. However, the
+ <classname>TopLevelTransaction</classname> class provides a more user-friendly interface.
+ </para>
+ <para>
+ <classname>AtomicTransaction</classname> and <classname>TopLevelTransaction</classname> are completely compatible
+ with <interfacename>CosTransactions::Current</interfacename>. You an use the two transaction mechanisms
+ interchangeably within the same application or object.
+ </para>
+ <para>
+ <classname>AtomicTransaction</classname> and <classname>TopLevelTransaction</classname> are similar to
+ <interfacename>CosTransactions::Current</interfacename>. They both simplify the interface between you and the OTS.
+ However, you gain two advantages by using <classname>AtomicTransaction</classname> or
+ <classname>TopLevelTransaction</classname>.
+ </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, becomes the
+ thread’s current transaction.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Instances of <classname>AtomicTransaction</classname> track scope, and if such an instance goes out of scope
+ before it is terminated, it is automatically aborted, along with its children.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Context propagation issues</title>
+ <para>
+ When using TXOJ in a distributed manner, JBossTS requires you to use interposition between client and object. This
+ requirement also exists if the application is local, but the transaction manager is remote. In the case of
+ implicit context propagation, where the application object is derived from
+ <interfacename>CosTransactions::TransactionalObject</interfacename>, you do not need to do anything
+ further. JBossTS automatically provides interposition. However, where implicit propagation is not supported by the
+ ORB, or your application does not use it, you must take additional action to enable interposition.
+ </para>
+ <para>
+ The class <classname>com.arjuna.ats.jts.ExplicitInterposition</classname> allows an application to create a local
+ control object which acts as a local coordinator, fielding registration requests that would normally be passed
+ back to the originator. This surrogate registers itself with the original coordinator, so that it can correctly
+ participate in the commit protocol. The application thread context becomes the surrogate transaction
+ hierarchy. Any transaction context currently associated with the thread is lost. The interposition lasts for the
+ lifetime of the explicit interposition object, at which point the application thread is no longer associated with
+ a transaction context. Instead, it is set to <literal>null</literal>.
+ </para>
+ <para>
+ interposition is intended only for those situations where the transactional object and the transaction occur
+ within different processes, rather than being co-located. If the transaction is created locally to the client, do
+ not use the explicit interposition class. The transaction is implicitly associated with the transactional object
+ because it resides within the same process.
+ </para>
+
+ <example>
+ <title>ExplicitInterposition</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/ExplicitInterposition.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ A transaction context can be propagated between client and server in two ways: either as a reference to the
+ client’s transaction Control, or explicitly sent by the client. 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>
+
+ <example>
+ <title>ExplicitInterposition Example</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/ExplicitInterposition_example.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ if the <interfacename>Control</interfacename> passed to the <methodname>register</methodname> operation of
+ <classname>ExplicitInterposition</classname> is <literal>null</literal>, no exception is thrown. The system
+ assumes 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>
+ <para>
+ When the application returns, or when it finishes with the interposed hierarchy, the program should call
+ <methodname>unregisterTransaction</methodname> to disassociate the thread of control from the hierarchy. This
+ occurs automatically when the <classname>ExplicitInterposition</classname> object is garbage collected. However,
+ since this may be after the transaction terminates, JBossTS assumes the thread is still associated with the
+ transaction and issues a warning about trying to terminate a transaction while threads are still active within it.
+ </para>
+ </section>
</chapter>
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ArjunaSubtranAwareResource.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ArjunaSubtranAwareResource.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ArjunaSubtranAwareResource.java 2010-12-07 04:04:28 UTC (rev 36224)
@@ -0,0 +1,5 @@
+interface ArjunaSubtranAwareResource :
+ CosTransactions::SubtransactionAwareResource
+{
+ CosTransactions::Vote prepare_subtransaction ();
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/AtomicTransaction.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/AtomicTransaction.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/AtomicTransaction.java 2010-12-07 04:04:28 UTC (rev 36224)
@@ -0,0 +1,22 @@
+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;
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition.java 2010-12-07 04:04:28 UTC (rev 36224)
@@ -0,0 +1,9 @@
+public class ExplicitInterposition
+{
+ public ExplicitInterposition ();
+
+ public void registerTransaction (Control control) throws InterpositionFailed, SystemException;
+
+ public void unregisterTransaction () throws InvalidTransaction,
+ SystemException;
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition_example.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition_example.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/ExplicitInterposition_example.java 2010-12-07 04:04:28 UTC (rev 36224)
@@ -0,0 +1,19 @@
+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
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/OTSAbstractRecord.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/OTSAbstractRecord.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/OTSAbstractRecord.java 2010-12-07 04:04:28 UTC (rev 36224)
@@ -0,0 +1,17 @@
+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);
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/img-2phase.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/img-2phase.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/jbossts-class-hierarchy.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/jbossts-class-hierarchy.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/ots_architecture.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/ots_architecture.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list