[jboss-svn-commits] JBL Code SVN: r35340 - in labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide: en-US and 2 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Sep 28 23:12:49 EDT 2010
Author: misty at redhat.com
Date: 2010-09-28 23:12:48 -0400 (Tue, 28 Sep 2010)
New Revision: 35340
Added:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/Example_extends_LockManager.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/LockManager_class.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager-signature.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/activation_termination_commitment.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-save_state.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/simple_concurrency_control.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/images/txcore_class_hierarchy.png
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/images/txoj-lifecycle.png
Removed:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/tmp/
Modified:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Overview.xml
Log:
Converted Overview chapter of ArjunaCore Programmers Guide
Modified: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Overview.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Overview.xml 2010-09-29 00:46:37 UTC (rev 35339)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Overview.xml 2010-09-29 03:12:48 UTC (rev 35340)
@@ -6,69 +6,494 @@
<chapter>
<title>Overview</title>
- <section>
- <title>Introduction</title>
+ <para>
+ This chapter contains a description of the use of the TxCore transaction engine and the <application>Transactional
+ Objects for Java (TXOJ)</application> classes and facilities. The classes mentioned in this chapter are the key to
+ writing fault-tolerant applications using transactions. Thus, they are described and then applied in the
+ construction of a simple application. The classes to be described in this chapter can be found in the
+ <package>com.arjuna.ats.txoj</package> and <package>com.arjuna.ats.arjuna</package> packages.
+ </para>
+ <note>
+ <title>Stand-Alone Transaction Manager</title>
<para>
+ Although JBoss Transaction Service can be embedded in various containers, such as JBoss Application Server, it
+ remains a stand-alone transaction manager as well. There are no dependencies between the core JBoss Transaction
+ Service and any container implementations.
</para>
- </section>
+ </note>
<section>
<title>TxCore</title>
<subtitle>The Transaction Engine</subtitle>
<para>
+ In keeping with the object-oriented view, the mechanisms needed to construct reliable distributed applications are
+ presented to programmers in an object-oriented manner. Some mechanisms need to be inherited, for example,
+ concurrency control and state management. Other mechanisms, such as object storage and transactions, are
+ implemented as TxCore objects that are created and manipulated like any other object.
</para>
-
+ <note>
+ <para>
+ When the manual talks about using persistence and concurrency control facilities it assumes that the
+ <application>Transactional Objects for Java (TXOJ)</application> classes are being used. If this is not the case
+ then the programmer is responsible for all of these issues.
+ </para>
+ </note>
+ <para>
+ TxCore exploits object-oriented techniques to present programmers with a toolkit of Java classes from which
+ application classes can inherit to obtain desired properties, such as persistence and concurrency control. These
+ classes form a hierarchy, part of which is shown in <xref linkend="txcore_class_hierarchy" /> and which will be described later in this document.
+ </para>
+ <figure id="txcore_class_hierarchy">
+ <title>TxCore Class Hierarchy</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/txcore_class_hierarchy.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Apart from specifying the scopes of transactions, and setting appropriate locks within objects, the application
+ programmer does not have any other responsibilities: TxCore and <application>TXOJ</application> guarantee
+ that transactional objects will be registered with, and be driven by, the appropriate transactions, and crash
+ recovery mechanisms are invoked automatically in the event of failures.
+ </para>
</section>
<section>
<title>Saving object states</title>
<para>
-
+ TxCore needs to be able to remember the state of an object for several purposes.
</para>
+ <variablelist>
+ <varlistentry>
+ <term>recovery</term>
+ <listitem>
+ <para>
+ The state represents some past state of the object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>persistence</term>
+ <listitem>
+ <para>
+ The state represents the final state of an object at application termination.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Since these requirements have common functionality they are all implemented using the same mechanism: the classes
+ <classname>InputObjectState</classname> and <classname>OutputObjectState</classname>. The classes maintain an
+ internal array into which instances of the standard types can be contiguously packed or unpacked using appropriate
+ <methodname>pack</methodname> or <methodname>unpack</methodname> operations. This buffer is automatically resized
+ as required should it have insufficient space. The instances are all stored in the buffer in a standard form
+ called <firstterm>network byte order</firstterm>, making them machine independent. Any other
+ architecture-independent format, such as XDR or ASN.1, can be implemented simply by replacing the operations with
+ ones appropriate to the encoding required.
+ </para>
</section>
<section>
<title>The object store</title>
<para>
-
+ Implementations of persistence can be affected by restrictions imposed by the Java SecurityManager. Therefore, the
+ object store provided with TxCore is implemented using the techniques of interface and implementation. The current
+ distribution includes implementations which write object states to the local file system or database, and remote
+ implementations, where the interface uses a client stub (proxy) to remote services.
</para>
+ <para>
+ Persistent objects are assigned unique identifiers, which are instances of the <classname>Uid</classname> class,
+ when they are created. These identifiers are used to identify them within the object store. States are read using
+ the <methodname>read_committed</methodname> operation and written by the <methodname>write_committed</methodname>
+ and <methodname>write_uncommitted</methodname> operations.
+ </para>
</section>
<section>
<title>Recovery and persistence</title>
<para>
-
+ At the root of the class hierarchy is the class
+ <classname>StateManager</classname>. <classname>StateManager</classname> is responsible for object activation and
+ deactivation, as well as object recovery. Refer to <xref linkend="StateManager-signature" /> for the simplified
+ signature of the class.
</para>
+ <example id="StateManager-signature">
+ <title><classname>Statemanager</classname></title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/StateManager-signature.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ Objects are assumed to be of three possible flavours.
+ </para>
+ <variablelist>
+ <title>Three Flavors of Objects</title>
+ <varlistentry>
+ <term>Recoverable</term>
+ <listitem>
+ <para>
+ <classname>StateManager</classname> attempts to generate and maintain appropriate recovery information for
+ the object. Such objects have lifetimes that do not exceed the application program that creates them.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Recoverable and Persistent</term>
+ <listitem>
+ <para>
+ The lifetime of the object is assumed to be greater than that of the creating or accessing application, so
+ that in addition to maintaining recovery information, <classname>StateManager</classname> attempts to
+ automatically load or unload any existing persistent state for the object by calling the
+ <methodname>activate</methodname> or <methodname>deactivate</methodname> operation at appropriate times.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Neither Recoverable nor Persistent</term>
+ <listitem>
+ <para>
+ Bo recovery information is ever kept, nor is object activation or deactivation ever automatically attempted.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ If an object is <phrase>recoverable</phrase> or <phrase>recoverable and persistent</phrase>, then
+ <classname>StateManager</classname> invokes the operations <methodname>save_state</methodname> while performing
+ <methodname>deactivate</methodname>, and <methodname>restore_state</methodname> while performing
+ <methodname>activate</methodname>,) at various points during the execution of the application. These operations
+ must be implemented by the programmer since <classname>StateManager</classname> cannot detect user-level state
+ changes. <!--(We are examining the automatic generation of default save_state and restore_state operations,
+ allowing the programmer to override this when application specific knowledge can be used to improve
+ efficiency.)-->This gives the programmer the ability to decide which parts of an object’s state should be made
+ persistent. For example, for a spreadsheet it may not be necessary to save all entries if some values can simply
+ be recomputed. The <methodname>save_state</methodname> implementation for a class <classname>Example</classname>
+ that has integer member variables called A, B and C might be implemented as in <xref linkend="example-save_state" />.
+ </para>
+ <example id="example-save_state">
+ <title><methodname>save_state</methodname> Implementation</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-save_state.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <note>
+ <para>
+ it is necessary for all <methodname>save_state</methodname> and <methodname>restore_state</methodname> methods
+ to call <methodname>super.save_state</methodname> and <methodname>super.restore_state</methodname>. This is to
+ cater for improvements in the crash recovery mechanisms.
+ </para>
+ </note>
</section>
<section>
<title>The life cycle of a Transactional Object for Java</title>
<para>
-
+ A persistent object not in use is assumed to be held in a passive state, with its state residing in an object store
+ and activated on demand. The fundamental life cycle of a persistent object in TXOJ is shown in <xref
+ linkend="txoj-lifecycle" />.
</para>
+ <figure id="txoj-lifecycle">
+ <title>Lifecycle of a persistent Object in TXOJ</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/txoj-lifecycle.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <orderedlist>
+ <listitem>
+ <para>
+ The object is initially passive, and is stored in the object store as an instance of the class
+ <classname>OutputObjectState</classname>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When required by an application, the object is automatically activated by reading it from the store
+ using a <methodname>read_committed</methodname> operation and is then converted from an
+ <classname>InputObjectState</classname> instance into a fully-fledged object by the
+ <methodname>restore_state</methodname> operation of the object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When the application has finished with the object, it is deactivated by converting it back into an
+ <classname>OutputObjectState</classname> instance using the <methodname>save_state</methodname>
+ operation, and is then stored back into the object store as a shadow copy using
+ <methodname>write_uncommitted</methodname>. This shadow copy can be committed, overwriting the previous
+ version, using the <methodname>commit_state</methodname> operation. The existence of shadow copies is
+ normally hidden from the programmer by the transaction system. Object deactivation normally only occurs
+ when the top-level transaction within which the object was activated commits
+ </para>
+ </listitem>
+ </orderedlist>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <note>
+ <para>
+ During its life time, a persistent object may be made active then passive many times.
+ </para>
+ </note>
</section>
<section>
<title>The concurrency controller</title>
<para>
-
+ The concurrency controller is implemented by the class <classname>LockManager</classname>, which provides sensible
+ default behavior while allowing the programmer to override it if deemed necessary by the particular semantics of
+ the class being programmed. As with <classname>StateManager</classname> and persistence, concurrency control
+ implementations are accessed through interfaces. As well as providing access to remote services, the current
+ implementations of concurrency control available to interfaces include:
</para>
+ <variablelist>
+ <varlistentry>
+ <term>Local disk/database implementation</term>
+ <listitem>
+ <para>
+ Locks are made persistent by being written to the local file system or database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>A purely local implementation</term>
+ <listitem>
+ <para>
+ Locks are maintained within the memory of the virtual machine which created them. This implementation has
+ better performance than when writing locks to the local disk, but objects cannot be shared between virtual
+ machines. Importantly, it is a basic Java object with no requirements which can be affected by the
+ SecurityManager.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The primary programmer interface to the concurrency controller is via the <methodname>setlock</methodname>
+ operation. By default, the runtime system enforces strict two-phase locking following a multiple reader, single
+ writer policy on a per object basis. However, as shown in <xref linkend="txcore_class_hierarchy" />, by inheriting
+ from the <classname>Lock</classname> class, you can provide your own lock implementations with different lock
+ conflict rules to enable type specific concurrency control.
+ </para>
+ <para>
+ Lock acquisition is, of necessity, under programmer control, since just as <classname>StateManager</classname>
+ cannot determine if an operation modifies an object, <classname>LockManager</classname> cannot determine if an
+ operation requires a read or write lock. Lock release, however, is under control of the system and requires no
+ further intervention by the programmer. This ensures that the two-phase property can be correctly maintained.
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/LockManager_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ The <classname>LockManager</classname> class is primarily responsible for managing requests to set a lock on an
+ object or to release a lock as appropriate. However, since it is derived from <classname>StateManager</classname>,
+ it can also control when some of the inherited facilities are invoked. For example,
+ <classname>LockManager</classname> assumes that the setting of a write lock implies that the invoking operation
+ must be about to modify the object. This may in turn cause recovery information to be saved if the object is
+ recoverable. In a similar fashion, successful lock acquisition causes <methodname>activate</methodname> to be
+ invoked.
+ </para>
+ <para>
+ <xref linkend="Example_extends_LockManager" /> shows how to try to obtain a write lock on an object.
+ </para>
+ <example id="Example_extends_LockManager">
+ <title><classname>Example</classname> Class</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/Example_extends_LockManager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
</section>
<section>
<title>The transactional protocol engine</title>
<para>
-
+ The transaction protocol engine is represented by the <classname>AtomicAction</classname> class, which uses
+ <classname>StateManager</classname> to record sufficient information for crash recovery mechanisms to complete the
+ transaction in the event of failures. It has methods for starting and terminating the transaction, and, for those
+ situations where programmers need to implement their own resources, methods for registering them with the current
+ transaction. Because TxCore supports subtransactions, if a transaction is begun within the scope of an already
+ executing transaction it will automatically be nested.
</para>
+ <para>
+ You can use TxCore with multi-threaded applications. Each thread within an application can share a transaction or
+ execute within its own transaction. Therefore, all TxCore classes are also thread-safe.
+ </para>
+ <example id="activation_termination_commitment">
+ <title>Relationships Between Activation, Termination, and Commitment</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/activation_termination_commitment.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term>Creation of bindings to persistent objects</term>
+ <listitem>
+ <para>
+ This could involve the creation of stub objects and a call to remote objects. Here, we re-bind to an
+ existing persistent object identified by <systemitem>Name-A</systemitem>, and a new persistent object. A
+ naming system for remote objects maintains the mapping between object names and locations and is described
+ in a later chapter.<!--xref-->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Start of the atomic transaction</term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Operation invocations</term>
+ <listitem>
+ <para>
+ As a part of a given invocation, the object implementation is responsible to ensure that it is locked in
+ read or write mode, assuming no lock conflict, and initialized, if necessary, with the latest committed
+ state from the object store. The first time a lock is acquired on an object within a transaction the
+ object’s state is acquired, if possible, from the object store.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Commit of the top-level action</term>
+ <listitem>
+ <para>
+ This includes updating of the state of any modified objects in the object store.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Breaking of the previously created bindings</term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </example>
</section>
<section>
<title>The class hierarchy</title>
<para>
+ The principal classes which make up the class hierarchy of TxCore are depicted below.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><classname>StateManager</classname></para>
+ <itemizedlist>
+ <listitem>
+ <para><classname>LockManager</classname></para>
+ <itemizedlist>
+ <listitem>
+ <para>User-Defined Classes</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para><classname>Lock</classname></para>
+ <itemizedlist>
+ <listitem>
+ <para>User-Defined Classes</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para><classname>AbstractRecord</classname></para>
+ <itemizedlist>
+ <listitem><para><classname>RecoveryRecord</classname></para></listitem>
+ <listitem><para><classname>LockRecord</classname></para></listitem>
+ <listitem><para><classname>RecordList</classname></para></listitem>
+ <listitem><para>Other management record types</para></listitem>
+ </itemizedlist>
+ </listitem><!-- End AbstractRecord -->
+ </itemizedlist>
+ </listitem> <!-- End StateManager -->
+ <listitem>
+ <para><classname>AtomicAction</classname></para>
+ <itemizedlist>
+ <listitem><para><classname>TopLevelTransaction</classname></para></listitem>
+ </itemizedlist>
+ </listitem> <!-- End AtomicAction -->
+ <listitem>
+ <para><classname>Input/OutputObjectBuffer</classname></para>
+ <itemizedlist>
+ <listitem><para><classname>Input/OutputObjectState</classname></para></listitem>
+ </itemizedlist>
+ </listitem><!-- End Input/OutputObjectBuffer -->
+ <listitem>
+ <para><classname>ObjectStore</classname></para>
+ </listitem><!-- End ObjectStore -->
+ </itemizedlist>
+
+ <!-- Keeping this around in case the other way is hard to read StateManager // Basic naming, persistence and
+ recovery control LockManager // Basic two-phase locking concurrency control service User-Defined Classes Lock
+ // Standard lock type for multiple readers/single writer User-Defined Lock Classes AbstractRecord // Important
+ utility class, similar to Resource RecoveryRecord // handles object recovery LockRecord // handles object
+ locking RecordList // Intentions list other management record types AtomicAction // Implements transaction
+ control abstraction TopLevelTransaction Input/OutputBuffer // Architecture neutral representation of an
+ objects’ state Input/OutputObjectState // Convenient interface to Buffer ObjectStore // Interface to the object
+ storage services-->
+ <para>
+ Programmers of fault-tolerant applications will be primarily concerned with the classes
+ <classname>LockManager</classname>, <classname>Lock</classname>, and <classname>AtomicAction</classname>. Other
+ classes important to a programmer are <classname>Uid</classname> and <classname>ObjectState</classname>.
</para>
+ <para>
+ Most TxCore classes are derived from the base class <classname>StateManager</classname>, which provides primitive
+ facilities necessary for managing persistent and recoverable objects. These facilities include support for the
+ activation and de-activation of objects, and state-based object recovery.
+ </para>
+ <para>
+ The class <classname>LockManager</classname> uses the facilities of <classname>StateManager</classname> and
+ <classname>Lock</classname> to provide the concurrency control required for implementing the serialisability
+ property of atomic actions. The concurrency control consists of two-phase locking in the current implementation.
+ The implementation of atomic action facilities is supported by <classname>AtomicAction</classname> and
+ <classname>TopLevelTransaction</classname>.
+ </para>
+ <para>
+ Consider a simple example. Assume that <classname>Example</classname> is a user-defined persistent class suitably
+ derived from the <classname>LockManager</classname>. An application containing an atomic transaction
+ <systemitem>Trans</systemitem> accesses an object called <systemitem>O</systemitem> of type <type>Example</type>,
+ by invoking the operation <methodname>op1</methodname>, which involves state changes to
+ <systemitem>O</systemitem>. The serializability property requires that a write lock must be acquired on
+ <systemitem>O</systemitem> before it is modified. Therefore, the body of <methodname>op1</methodname> should
+ contain a call to the <methodname>setlock</methodname> operation of the concurrency controller.
+ </para>
+ <example id="simple_concurrency_control">
+ <title>Simple Concurrency Control</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/simple_concurrency_control.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <procedure>
+ <title>Steps followed by the operation <methodname>setlock</methodname></title>
+ <para>
+ The operation <methodname>setlock</methodname>, provided by the <classname>LockManager</classname> class,
+ performs the following functions in <xref linkend="simple_concurrency_control" />.
+ </para>
+ <step>
+ <para>Check write lock compatibility with the currently held locks, and if allowed, continue.</para>
+ </step>
+ <step>
+ <para>
+ Call the StateManager operation <methodname>activate</methodname>.<methodname>activate</methodname> will load,
+ if not done already, the latest persistent state of <classname>O</classname> from the object store, then call
+ the <classname>StateManager</classname> operation <methodname>modified</methodname>, which has the effect of
+ creating an instance of either <classname>RecoveryRecord</classname> or
+ <classname>PersistenceRecord</classname> for <classname>O</classname>, depending upon whether
+ <classname>O</classname> was persistent or not. The Lock is a WRITE lock so the old state of the object must
+ be retained prior to modification. The record is then inserted into the RecordList of Trans.
+ </para>
+ </step>
+ <step>
+ <para>
+ Create and insert a <classname>LockRecord</classname> instance in the <classname>RecordList</classname> of
+ <systemitem>Trans</systemitem>.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ Now suppose that action <systemitem>Trans</systemitem> is aborted sometime after the lock has been acquired. Then
+ the <methodname>rollback</methodname> operation of <classname>AtomicAction</classname> will process the
+ <classname>RecordList</classname> instance associated with <systemitem>Trans</systemitem> by invoking an
+ appropriate <methodname>Abort</methodname> operation on the various records. The implementation of this operation
+ by the <classname>LockRecord</classname> class will release the WRITE lock while that of
+ <classname>RecoveryRecord</classname> or <classname>PersistenceRecord</classname> will restore the prior state of
+ <classname>O</classname>.
+ </para>
+ <para>
+ It is important to realise that all of the above work is automatically being performed by TxCore on behalf of the
+ application programmer. The programmer need only start the transaction and set an appropriate lock; TxCore and
+ <application>TXOJ</application> take care of participant registration, persistence, concurrency control and
+ recovery.
+ </para>
</section>
-
-
</chapter>
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/Example_extends_LockManager.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/Example_extends_LockManager.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/Example_extends_LockManager.java 2010-09-29 03:12:48 UTC (rev 35340)
@@ -0,0 +1,29 @@
+public class Example extends LockManager
+{
+ public boolean foobar ()
+ {
+ AtomicAction A = new AtomicAction;
+ boolean result = false;
+
+ A.begin();
+
+ if (setlock(new Lock(LockMode.WRITE), 0) == Lock.GRANTED)
+ {
+ /*
+ * Do some work, and TXOJ will
+ * guarantee ACID properties.
+ */
+
+ // automatically aborts if fails
+
+ if (A.commit() == AtomicAction.COMMITTED)
+ {
+ result = true;
+ }
+ }
+ else
+ A.rollback();
+
+ return result;
+ }
+}
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/LockManager_class.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/LockManager_class.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/LockManager_class.java 2010-09-29 03:12:48 UTC (rev 35340)
@@ -0,0 +1,4 @@
+public abstract class LockManager extends StateManager
+{
+ public LockResult setlock (Lock toSet, int retry, int timeout);
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager-signature.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager-signature.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager-signature.java 2010-09-29 03:12:48 UTC (rev 35340)
@@ -0,0 +1,15 @@
+public abstract class StateManager
+{
+ public boolean activate ();
+ public boolean deactivate (boolean commit);
+
+ public Uid get_uid (); // object’s identifier.
+
+ // methods to be provided by a derived class
+
+ public boolean restore_state (InputObjectState os);
+ public boolean save_state (OutputObjectState os);
+
+ protected StateManager ();
+ protected StateManager (Uid id);
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/activation_termination_commitment.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/activation_termination_commitment.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/activation_termination_commitment.java 2010-09-29 03:12:48 UTC (rev 35340)
@@ -0,0 +1,11 @@
+{
+ . . .
+ O1 objct1 = new objct1(Name-A);/* (i) bind to "old" persistent object A */
+ O2 objct2 = new objct2(); /* create a "new" persistent object */
+ OTS.current().begin(); /* (ii) start of atomic action */
+
+ objct1.op(...); /* (iii) object activation and invocations */
+ objct2.op(...);
+ . . .
+ OTS.current().commit(true); /* (iv) tx commits & objects deactivated */
+} /* (v) */
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-save_state.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-save_state.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-save_state.java 2010-09-29 03:12:48 UTC (rev 35340)
@@ -0,0 +1,18 @@
+public boolean save_state(OutputObjectState o)
+{
+ if (!super.save_state(o))
+ return false;
+
+ try
+ {
+ o.packInt(A);
+ o.packInt(B);
+ o.packInt(C));
+}
+catch (Exception e)
+ {
+ return false;
+ }
+
+return true;
+}
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/simple_concurrency_control.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/simple_concurrency_control.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/simple_concurrency_control.java 2010-09-29 03:12:48 UTC (rev 35340)
@@ -0,0 +1,8 @@
+public boolean op1 (...)
+{
+ if (setlock (new Lock(LockMode.WRITE) == LockResult.GRANTED)
+ {
+ // actual state change operations follow
+ ...
+ }
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/images/txcore_class_hierarchy.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/images/txcore_class_hierarchy.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/images/txoj-lifecycle.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/images/txoj-lifecycle.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list