[jboss-svn-commits] JBL Code SVN: r35372 - 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
Thu Sep 30 23:40:53 EDT 2010
Author: misty at redhat.com
Date: 2010-09-30 23:40:52 -0400 (Thu, 30 Sep 2010)
New Revision: 35372
Added:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_activate_method.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_deactivate_method.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_modified_method.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/aliasing.java
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/nested_transactions_in_constructors.java
Modified:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Hints_and_Tips.xml
Log:
Converted Hints and Tips Chapter for ArjunaCore Development Guide
Modified: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Hints_and_Tips.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Hints_and_Tips.xml 2010-10-01 01:46:44 UTC (rev 35371)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/Hints_and_Tips.xml 2010-10-01 03:40:52 UTC (rev 35372)
@@ -11,25 +11,138 @@
<section>
<title>Using transactions in constructors</title>
<para>
-
+ Examples throughout this manual use transactions in the implementation of constructors for new persistent
+ objects. This is deliberate because it guarantees correct propagation of the state of the object to the object
+ store. The state of a modified persistent object is only written to the object store when the top-level
+ transaction commits. Thus, if the constructor transaction is top-level and it commits, the newly-created object
+ is written to the store and becomes available immediately. If, however, the constructor transaction commits but
+ is nested because another transaction that was started prior to object creation is running, the state is written
+ only if all of the parent transactions commit.
</para>
+ <para>
+ On the other hand, if the constructor does not use transactions, inconsistencies in the system can arise. For
+ example, if no transaction is active when the object is created, its state is not saved to the store until the
+ next time the object is modified under the control of some transaction.
+ </para>
+ <example>
+ <title>Nested Transactions In Constructors</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/nested_transactions_in_constructors.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ The two objects are created outside of the control of the top-level action
+ <systemitem>A</systemitem>. <systemitem>obj1</systemitem> is a new object. <systemitem>obj2</systemitem> is an
+ old existing object. When the <methodname>remember</methodname> operation of <systemitem>obj2</systemitem> is
+ invoked, the object will be activated and the <type>Uid</type> of <systemitem>obj1</systemitem>
+ remembered. Since this action commits, the persistent state of <systemitem>obj2</systemitem> may now contain the
+ <type>Uid</type> of <systemitem>obj1</systemitem>. However, the state of <systemitem>obj1</systemitem> itself
+ has not been saved since it has not been manipulated under the control of any action. In fact, unless it is
+ modified under the control of an action later in the application, it will never be saved. If, however, the
+ constructor had used an atomic action, the state of <systemitem>obj1</systemitem> would have automatically been
+ saved at the time it was constructed and this inconsistency could not arise.
+ </para>
</section>
<section>
<title><methodname>save_state</methodname> and <methodname>restore_state</methodname> methods</title>
<para>
+ TxCore may invoke the user-defined <methodname>save_state</methodname> operation of an object at any time during
+ the lifetime of an object, including during the execution of the body of the object’s constructor. This is
+ particularly a possibility if it uses atomic actions. It is important, therefore, that all of the variables
+ saved by <methodname>save_state</methodname> are correctly initialized. Exercise caution when writing the
+ <methodname>save_state</methodname> and <methodname>restore_state</methodname> operations, to ensure that no
+ transactions are started, either explicitly in the operation, or implicitly through use of some other
+ operation. The reason for this restriction is that TxCore may invoke <methodname>restore_state</methodname> as
+ part of its commit processing. This would result in the attempt to execute an atomic transaction during the
+ commit or abort phase of another transaction. This might violate the atomicity properties of the transaction
+ being committed or aborted, and is thus discouraged. In order to support crash recovery for persistent objects,
+ all <methodname>save_state</methodname> and <methodname>restore_state</methodname> methods of user objects must
+ call <methodname>super.save_state</methodname> and <methodname>super.restore_state</methodname>.
+ </para>
- </para>
+ <section>
+ <title>Packing objects</title>
+ <para>
+ All of the basic types of Java (<type>int</type>, <type>long</type>, etc.) can be saved and restored from an
+ <classname>InputObjectState</classname> or <classname>OutputObjectState</classname>
+ instance by using the <methodname>pack</methodname> and <methodname>unpack</methodname> routines provided by
+ <classname>InputObjectState</classname> and <classname>OutputObjectState</classname>. However packing and
+ unpacking objects should be handled differently. This is because packing objects brings in the additional
+ problems of aliasing. Aliasing happens when two different object references may point at the same item. For
+ example:
+ </para>
+ <example>
+ <title>Aliasing</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/aliasing.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ Here, both <varname>s1</varname> and <varname>s2</varname> point at the same string. A naive implementation of
+ <methodname>save_state</methodname> might copy the string twice. From a <methodname>save_state</methodname>
+ perspective this is simply inefficient. However, <methodname>restore_state</methodname> would unpack the two
+ strings into different areas of memory, destroying the original aliasing information. The current version of
+ TxCore packs and unpacks separate object references.
+ </para>
+ </section>
</section>
</section>
<section>
<title>Direct use of StateManager</title>
<para>
-
+ The examples throughout this manual derive user classes from <classname>LockManager</classname>. These are two
+ important reasons for this.
</para>
-
+ <orderedlist>
+ <listitem>
+ <para>
+ Firstly, and most importantly, the serializability constraints of atomic actions require it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It reduces the need for programmer intervention.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ However, if you only require access to TxCore's persistence and recovery mechanisms, direct derivation of a user
+ class from <classname>StateManager</classname> is possible.
+ </para>
+ <para>
+ Classes derived directly from <classname>StateManager</classname> must make use of its state management mechanisms
+ explicitly. These interactions are normally undertaken by <classname>LockManager</classname>. From a programmer's
+ point of view this amounts to making appropriate use of the operations <methodname>activate</methodname>,
+ <methodname>deactivate</methodname>, and <methodname>modified</methodname>, since
+ <classname>StateManager</classname>'s constructors are effectively identical to those of
+ <classname>LockManager</classname>.
+ </para>
+ <example>
+ <title><methodname>activate</methodname></title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/StateManager_activate_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ Activate loads an object from the object store. The object’s UID must already have been set via the constructor
+ and the object must exist in the store. If the object is successfully read then restore_state is called to build
+ the object in memory. Activate is idempotent so that once an object has been activated further calls are
+ ignored. The parameter represents the root name of the object store to search for the object. A value of null
+ means use the default store.
+ </para>
+ </example>
+ <example>
+ <title><methodname>deactivate</methodname></title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/StateManager_deactivate_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ The inverse of activate. First calls save_state to build the compacted image of the object which is then saved
+ in the object store. Objects are only saved if they have been modified since they were activated. The parameter
+ represents the root name of the object store into which the object should be saved. A value of null means use
+ the default store.
+ </para>
+ </example>
+ <example>
+ <title><methodname>modified</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/StateManager_modified_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ Must be called prior to modifying the object in memory. If it is not called, the object will not be saved in the
+ object store by <methodname>deactivate</methodname>.
+ </para>
+ </example>
</section>
-
</chapter>
-
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_activate_method.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_activate_method.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_activate_method.java 2010-10-01 03:40:52 UTC (rev 35372)
@@ -0,0 +1,2 @@
+boolean activate ()
+boolean activate (String storeRoot)
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_deactivate_method.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_deactivate_method.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_deactivate_method.java 2010-10-01 03:40:52 UTC (rev 35372)
@@ -0,0 +1,2 @@
+boolean deactivate ()
+boolean deactivate (String storeRoot)
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_modified_method.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_modified_method.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/StateManager_modified_method.java 2010-10-01 03:40:52 UTC (rev 35372)
@@ -0,0 +1 @@
+void modified ()
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/aliasing.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/aliasing.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/aliasing.java 2010-10-01 03:40:52 UTC (rev 35372)
@@ -0,0 +1,13 @@
+public class Test
+{
+ public Test (String s);
+ ...
+ private String s1;
+ private String s2;
+};
+
+public Test (String s)
+{
+ s1 = s;
+ s2 = s;
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/nested_transactions_in_constructors.java
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/nested_transactions_in_constructors.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/ArjunaCore_Development_Guide/en-US/extras/nested_transactions_in_constructors.java 2010-10-01 03:40:52 UTC (rev 35372)
@@ -0,0 +1,10 @@
+AtomicAction A = new AtomicAction();
+Object obj1;
+Object obj2;
+
+obj1 = new Object(); // create new object
+obj2 = new Object("old"); // existing object
+
+A.begin(0);
+obj2.remember(obj1.get_uid()); // obj2 now contains reference to obj1
+A.commit(true); // obj2 saved but obj1 is not
More information about the jboss-svn-commits
mailing list