[jboss-svn-commits] JBL Code SVN: r35392 - in labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US: extras and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Oct 3 22:11:58 EDT 2010
Author: misty at redhat.com
Date: 2010-10-03 22:11:57 -0400 (Sun, 03 Oct 2010)
New Revision: 35392
Added:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-TransactionalQueue.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_enqueue.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_inspectValue.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_main.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_queueSize.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_restore_state.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_save_state.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_type.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_class.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_destructor.java
Modified:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml
Log:
Converted the Tutorial Chapter
Modified: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml 2010-10-02 15:00:03 UTC (rev 35391)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml 2010-10-04 02:11:57 UTC (rev 35392)
@@ -5,9 +5,180 @@
]>
<chapter>
<title>Constructing a Transactional Objects for Java application</title>
+ <orderedlist>
+ <title>Development Phases of a TxCore Application</title>
+ <listitem>
+ <para>
+ First, develop new classes with characteristics like persistence, recoverability, and concurrency control.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Then develop the applications that make use of the new classes of objects.
+ </para>
+ </listitem>
+ </orderedlist>
<para>
+ Although these two phases may be performed in parallel and by a single person, this guide refers to the first step
+ as the job of the class developer, and the second as the job of the applications developer.<!--Rewrite this --> The
+ class developer defines appropriate <methodname>save_state</methodname> and <methodname>restore_state</methodname>
+ operations for the class, sets appropriate locks in operations, and invokes the appropriate TxCore class
+ constructors. The applications developer defines the general structure of the application, particularly with regard
+ to the use of atomic actions.
+ </para>
+ <para>
+ This chapter outlines a simple application, a simple FIFO Queue class for integer values. The Queue is implemented
+ with a doubly linked list structure, and is implemented as a single object. This example is used throughout the rest
+ of this manual to illustrate the various mechanisms provided by TxCore. Although this is an unrealistic example
+ application, it illustrates all of the TxCore modifications without requiring in depth knowledge of the application
+ code.
+ </para>
+ <note>
+ <para>
+ The application is assumed not to be distributed. To allow for distribution, context information must be
+ propagated either implicitly or explicitly.
+ </para>
+ </note>
- </para>
+ <section>
+ <title>Queue description</title>
+ <para>
+ The queue is a traditional FIFO queue, where elements are added to the front and removed from the back. The
+ operations provided by the queue class allow the values to be placed on to the queue (<methodname>enqueue</methodname>) and to be removed
+ from it (<methodname>dequeue</methodname>), and values of elements in the queue can also be changed or inspected. In this
+ example implementation, an array represents the queue. A limit of <varname>QUEUE_SIZE</varname> elements has been imposed
+ for this example.
+ </para>
+ <example>
+ <title>Java interface definition of class <classname>queue</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example_queue_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ </section>
+
+ <section>
+ <title>Constructors and destructors</title>
+ <para>
+ Using an existing persistent object requires the use of a special constructor
+ that takes the Uid of the persistent object, as shown in <xref linkend="example-TransactionalQueue" />.
+ </para>
+ <example id="example-TransactionalQueue">
+ <title>Class <classname>TransactionalQueue</classname></title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/example-TransactionalQueue.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ The use of an atomic action within the constructor for a new object follows the guidelines outlined earlier and
+ ensures that the object’s state will be written to the object store when the appropriate top level atomic action
+ commits (which will either be the action A or some enclosing action active when the TransactionalQueue was
+ constructed). The use of atomic actions in a constructor is simple: an action must first be declared and its begin
+ operation invoked; the operation must then set an appropriate lock on the object (in this case a WRITE lock must
+ be acquired), then the main body of the constructor is executed. If this is successful the atomic action can be
+ committed, otherwise it is aborted.
+ </para>
+ <para>
+ The destructor of the <classname>queue</classname> class is only required to call the
+ <methodname>terminate</methodname> operation of <classname>LockManager</classname>.
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example_queue_destructor.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+
+ </section>
+
+ <section>
+ <title>Required methods</title>
+ <section>
+ <title><methodname>save_state</methodname>, <methodname>restore_state</methodname>, and <methodname>type</methodname></title>
+ <example>
+ <title>Method <methodname>save_state</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_save_state.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>Method <methodname>restore_state</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_restore_state.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <example>
+ <title>Method <methodname>type</methodname></title>
+ <para>
+ Because the Queue class is derived from the LockManager class, the operation type should be:
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_type.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title><methodname>enque</methodname> and <methodname>dequeue</methodname> methods</title>
+ <para>
+ If the operations of the <classname>queue</classname> class are to be coded as atomic actions, then the enqueue
+ operation might have the structure given below. The <methodname>dequeue</methodname> operation is similarly
+ structured, but is not implemented here.
+ </para>
+ <example>
+ <title>Method <methodname>enqueue</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_enqueue.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+
+ <section>
+ <title><methodname>queueSize</methodname> method</title>
+ <example>
+ <title>Method <methodname>queueSize</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_queueSize.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+
+ <section>
+ <title><methodname>inspectValue</methodname> and <methodname>setValue</methodname> methods</title>
+ <note>
+ <para>
+ The <methodname>setValue</methodname> method is not implemented here, but is similar in structure to <xref
+ linkend="example-queue-inspectValue" />.
+ </para>
+ </note>
+ <example id="example_queue-inspectValue">
+ <title>Method <methodname>inspectValue</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_inspectValue.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+ </section>
+
+
+ <section>
+ <title>The client</title>
+ <para>
+ Rather than show all of the code for the client, this example concentrates on a representative portion. Before
+ invoking operations on the object, the client must first bind to the object. In the local case this simply
+ requires the client to create an instance of the object.
+ </para>
+ <example>
+ <title>Binding to the Object</title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/example-queue_main.java"
+ xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ </section>
+
+
+ <section>
+ <title>Comments</title>
+ <para>
+ Since the <systemitem>queue</systemitem> object is persistent, the state of the object survives any failures of
+ the node on which it is located. The state of the object that survives is the state produced by the last top-level
+ committed atomic action performed on the object. If an application intends to perform two
+ <methodname>enqueue</methodname> operations atomically, for example, you can nest the
+ <methodname>enqueue</methodname> operations in another enclosing atomic action. In addition, concurrent operations
+ on such a persistent object are serialized, preventing inconsistencies in the state of the object.
+ </para>
+ <para>
+ However, since the elements of the <systemitem>queue</systemitem> objects are not individually concurrency
+ controlled, certain combinations of concurrent operation invocations are executed serially, even though logically
+ they could be executed concurrently. An example of this is modifying the states of two different elements in the
+ queue. <xref linkend="chap-configuration-options" /> addresses some of these issues.
+ </para>
+
+ </section>
+
</chapter>
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-TransactionalQueue.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-TransactionalQueue.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-TransactionalQueue.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,34 @@
+public TransactionalQueue (Uid u)
+{
+ super(u);
+
+ numberOfElements = 0;
+}
+The constructor that creates a new persistent object is similar:
+ public TransactionalQueue ()
+{
+ super(ObjectType.ANDPERSISTENT);
+
+ numberOfElements = 0;
+
+ try
+ {
+ AtomicAction A = new AtomicAction();
+
+ A.begin(0); // Try to start atomic action
+
+ // Try to set lock
+
+ if (setlock(new Lock(LockMode.WRITE), 0) == LockResult.GRANTED)
+ {
+ A.commit(true); // Commit
+ }
+ else // Lock refused so abort the atomic action
+ A.rollback();
+ }
+ catch (Exception e)
+ {
+ System.err.println(“Object construction error: “+e);
+ System.exit(1);
+ }
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_enqueue.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_enqueue.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_enqueue.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,37 @@
+public void enqueue (int v) throws OverFlow, UnderFlow, QueueError
+{
+ AtomicAction A = new AtomicAction();
+ boolean res = false;
+
+ try
+ {
+ A.begin(0);
+
+ if (setlock(new Lock(LockMode.WRITE), 0) == LockResult.GRANTED)
+ {
+ if (numberOfElements < QUEUE_SIZE)
+ {
+ elements[numberOfElements] = v;
+ numberOfElements++;
+ res = true;
+ }
+ else
+ {
+ A.rollback();
+ throw new UnderFlow();
+ }
+ }
+
+ if (res)
+ A.commit(true);
+ else
+ {
+ A.rollback();
+ throw new Conflict();
+ }
+ }
+ catch (Exception e1)
+ {
+ throw new QueueError();
+ }
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_inspectValue.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_inspectValue.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_inspectValue.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,50 @@
+public int inspectValue (int index) throws UnderFlow,
+ OverFlow, Conflict, QueueError
+{
+ AtomicAction A = new AtomicAction();
+ boolean res = false;
+ int val = -1;
+
+ try
+ {
+ A.begin();
+
+ if (setlock(new Lock(LockMode.READ), 0) == LockResult.GRANTED)
+ {
+ if (index < 0)
+ {
+ A.rollback();
+ throw new UnderFlow();
+ }
+ else
+ {
+ // array is 0 - numberOfElements -1
+
+ if (index > numberOfElements -1)
+ {
+ A.rollback();
+ throw new OverFlow();
+ }
+ else
+ {
+ val = elements[index];
+ res = true;
+ }
+ }
+ }
+
+ if (res)
+ A.commit(true);
+ else
+ {
+ A.rollback();
+ throw new Conflict();
+ }
+ }
+ catch (Exception e1)
+ {
+ throw new QueueError();
+ }
+
+ return val;
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_main.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_main.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_main.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,33 @@
+public static void main (String[] args)
+{
+ TransactionalQueue myQueue = new TransactionalQueue();
+ Before invoking one of the queue’s operations, the client starts a transaction. The queueSize operation is shown below:
+ AtomicAction A = new AtomicAction();
+ int size = 0;
+
+ try
+ {
+ A.begin(0);
+
+ try
+ {
+ size = queue.queueSize();
+ }
+ catch (Exception e)
+ {
+ }
+
+ if (size >= 0)
+ {
+ A.commit(true);
+
+ System.out.println(“Size of queue: “+size);
+ }
+ else
+ A.rollback();
+ }
+ catch (Exception e)
+ {
+ System.err.println(“Caught unexpected exception!”);
+ }
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_queueSize.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_queueSize.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_queueSize.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,28 @@
+public int queueSize () throws QueueError, Conflict
+{
+ AtomicAction A = new AtomicAction();
+ int size = -1;
+
+ try
+ {
+ A.begin(0);
+
+ if (setlock(new Lock(LockMode.READ), 0) == LockResult.GRANTED)
+ size = numberOfElements;
+
+ if (size != -1)
+ A.commit(true);
+ else
+ {
+ A.rollback();
+
+ throw new Conflict();
+ }
+ }
+ catch (Exception e1)
+ {
+ throw new QueueError();
+ }
+
+ return size;
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_restore_state.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_restore_state.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_restore_state.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,22 @@
+public boolean restore_state (InputObjectState os, int ObjectType)
+{
+ if (!super.restore_state(os, ObjectType))
+ return false;
+
+ try
+ {
+ numberOfElements = os.unpackInt();
+
+ if (numberOfElements > 0)
+ {
+ for (int i = 0; i < numberOfElements; i++)
+ elements[i] = os.unpackInt();
+ }
+
+ return true;
+ }
+ catch (IOException e)
+ {
+ return false;
+ }
+}
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_save_state.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_save_state.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_save_state.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,22 @@
+public boolean save_state (OutputObjectState os, int ObjectType)
+{
+ if (!super.save_state(os, ObjectType))
+ return false;
+
+ try
+ {
+ os.packInt(numberOfElements);
+
+ if (numberOfElements > 0)
+ {
+ for (int i = 0; i < numberOfElements; i++)
+ os.packInt(elements[i]);
+ }
+
+ return true;
+ }
+ catch (IOException e)
+ {
+ return false;
+ }
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_type.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_type.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example-queue_type.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,4 @@
+public String type ()
+{
+ return "/StateManager/LockManager/TransactionalQueue";
+}
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_class.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_class.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_class.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,26 @@
+public class TransactionalQueue extends LockManager
+{
+ public TransactionalQueue (Uid uid);
+ public TransactionalQueue ();
+ public void finalize ();
+
+ public void enqueue (int v) throws OverFlow, UnderFlow,
+ QueueError, Conflict;
+ public int dequeue () throws OverFlow, UnderFlow,
+ QueueError, Conflict;
+
+ public int queueSize ();
+ public int inspectValue (int i) throws OverFlow,
+ UnderFlow, QueueError, Conflict;
+ public void setValue (int i, int v) throws OverFlow,
+ UnderFlow, QueueError, Conflict;
+
+ public boolean save_state (OutputObjectState os, int ObjectType);
+ public boolean restore_state (InputObjectState os, int ObjectType);
+ public String type ();
+
+ public static final int QUEUE_SIZE = 40; // maximum size of the queue
+
+ private int[QUEUE_SIZE] elements;
+ private int numberOfElements;
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_destructor.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_destructor.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/example_queue_destructor.java 2010-10-04 02:11:57 UTC (rev 35392)
@@ -0,0 +1,4 @@
+public void finalize ()
+{
+ super.terminate();
+}
\ No newline at end of file
More information about the jboss-svn-commits
mailing list