[jboss-cvs] JBossAS SVN: r74206 - in projects/docs/enterprise/4.3/Transactions: Programmers_Guide and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Jun 5 18:42:13 EDT 2008
Author: mhideo at redhat.com
Date: 2008-06-05 18:42:10 -0400 (Thu, 05 Jun 2008)
New Revision: 74206
Added:
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/Makefile
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_A.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_B.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Author_Group.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_02.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_03.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_04.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_05.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_06.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_07.xml
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.ent
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.xml
Log:
init
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/Makefile
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/Makefile (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/Makefile 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,21 @@
+#Makefile for Red Hat Documentation
+#Created by Jeff Fearn <jfearn at redhat.com>
+#Copyright Red Hat Inc. 2006
+
+XML_LANG = en-US
+# FIX_ME!
+DOCNAME = JBoss_TS_Programmers_Guide
+# Be Careful with PRODUCT!
+# Only Set This if you want theis Book to be placed in a sub directory when published
+# defaults to RHEL
+PRODUCT = JBoss_Enterprise_Application_Platform
+
+BRAND = JBoss
+
+TRANSLATIONS = $(XML_LANG)
+#OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW
+#TRANSLATIONS = $(XML_LANG) $(OTHER_LANGS)
+
+COMMON_CONFIG = /usr/share/publican
+include $(COMMON_CONFIG)/make/Makefile.common
+
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/Makefile
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_A.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_A.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_A.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,269 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<appendix>
+ <title>Object store implementations</title>
+
+ <section>
+ <title>The ObjectStore</title>
+ <para>
+ In this appendix we shall examine the various TxCore object store implementations and give guidelines as to how other implementations may be created and plugged into an application.
+ </para>
+ <para>
+ This release of JBossTS contains several different implementations of a basic object store. Each serves a particular purpose and is generally optimised for that purpose. All of the implementations are derived from the <interface>ObjectStore</interface> interface. This defines the minimum operations which must be provided in order for an object store implementation to be used by JBossTS. The default object store implementation can be overridden at runtime by setting the <property>com.arjuna.ats.arjuna.objectstore.objectStoreType</property> property variable to one of the types described below.
+ </para>
+<screen>
+ /*
+ * This is the base class from which all object store types are derived.
+ * Note that because object store instances are stateless, to improve
+ * efficiency we try to only create one instance of each type per process.
+ * Therefore, the create and destroy methods are used instead of new
+ * and delete. If an object store is accessed via create it *must* be
+ * deleted using destroy. Of course it is still possible to make use of
+ * new and delete directly and to create instances on the stack.
+ */
+
+ public class ObjectStore
+ {
+ public static final int OS_COMMITTED;
+ public static final int OS_COMMITTED_HIDDEN;
+ public static final int OS_HIDDEN;
+ public static final int OS_INVISIBLE;
+ public static final int OS_ORIGINAL;
+ public static final int OS_SHADOW;
+ public static final int OS_UNCOMMITTED;
+ public static final int OS_UNCOMMITTED_HIDDEN;
+ public static final int OS_UNKNOWN;
+ public ObjectStore (ClassName type);
+ public ObjectStore (ClassName type, String osRoot);
+ public ObjectStore (String osRoot);
+ public synchronized boolean allObjUids (String s, InputObjectState buff)
+ throws ObjectStoreException;
+ public synchronized boolean allObjUids (String s, InputObjectState buff,
+ int m) throws ObjectStoreException;
+
+ public synchronized boolean allTypes (InputObjectState buff)
+ throws ObjectStoreException;
+ public synchronized int currentState(Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized boolean commit_state (Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized boolean hide_state (Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized boolean reveal_state (Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized InputObjectState read_committed (Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized InputObjectState read_uncommitted (Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized boolean remove_committed (Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized boolean remove_uncommitted (Uid u, String tn)
+ throws ObjectStoreException;
+ public synchronized boolean write_committed (Uid u, String tn,
+ OutputObjectState buff)
+ throws ObjectStoreException;
+ public synchronized boolean write_uncommitted (Uid u, String tn,
+ OutputObjectState buff)
+ throws ObjectStoreException;
+ public static void printState (PrintStream strm, int res);
+};
+</screen>
+ <para>
+ JBossTS programmers need not usually interact with any of the object store implementations directly other than possibly to create them in the first place (even this is not necessary if the default store type is used as JBossTS will create stores as necessary). All stores manipulate instances of the class <classname>ObjectState</classname> which are named using a type (via the object's type() operation) and a Uid. For atomic actions purposes object states in the store can be principally in two distinct states: OS_COMMITTED, and OS_UNCOMMITTED. An object state starts in the OS_COMMITTED state but when modified under the control of an atomic action a new second object state may be written that is in the OS_UNCOMMITTED state. If the action commits this second object state replaces the original and becomes OS_COMMITTED. If the action aborts, this second object state is simply discarded. All of the implementations provided with this release handle these state transitions by ma!
king use of shadow copies of object states, however, any other implementation that maintains this abstraction is permissible. Object states may become hidden (and thus inaccessible) under the control of the crash recovery system.
+ </para>
+ <para>
+ Browsing of the contents of a store is possible through the <methodname>allTypes</methodname> and <methodname>allObjUids</methodname> operations. <methodname>allTypes</methodname> returns an <type>InputObjectState</type> containing all of the type names of all objects in a store, terminated by a null name. <methodname>allObjUids</methodname> returns an <type>InputObjectState</type> that contains all of the Uids of all objects of a given type terminated by the special <methodname>Uid.nullUid()</methodname>.
+ </para>
+ </section>
+ <section id="Persistent_object_stores">
+ <title>Persistent object stores</title>
+ <para>
+ This section briefly describes the characteristics and optimisations of each of the supplied implementations of the persistent object store. Persistent object states are mapped onto the structure of the file system supported by the host operating system.
+ </para>
+ <formalpara>
+ <title>Common functionality</title>
+ <para>In addition to the features mentioned earlier all of the supplied persistent object stores obey the following rules:</para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Each object state is stored in its own file that is named using the <code>Uid</code> of the object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The type of an object (as given by the <methodname>type()</methodname> operation) determines the directory into which the object is placed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All of the stores have a common root directory that is determined when JBossTS is configured. This directory name is automatically prepended to any store specific root information.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All stores also have the notion of a localised root directory that is automatically prepended to the type of the object to determine the ultimate directory name. The localised root name is specified when the store is created. By default the localised root name is <code>defaultStore</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
+<screen>
+<ObjectStore root Directory from configure> /JBossTS/ObjectStore/
+ <ObjectStore Type1> FragmentedStore/
+ <Default root> defaultStore/
+ <StateManager> StateManager
+ <LockManager> LockManager/
+ <User Types>
+ <Localised root 2> myStore/
+ <StateManager> StateManager/
+
+ <ObjectStore Type2> ActionStore/
+ <Default root> defaultStore/
+</screen>
+
+ <formalpara>
+ <title>The shadowing store</title>
+ <para>
+ This is the original version of the object store as provided in prior releases and is implemented by the class <classname>ShadowingStore</classname>. It is simple but slow. It uses pairs of files to represent objects (the shadow version and the committed version) and files are opened, locked, operated upon, unlocked and closed on every interaction with the object store. Thus significant portions of time can be spent in the system simply opening, closing and renaming files, all of which are very expensive operations.
+ </para>
+ </formalpara>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>ShadowingStore</type>.
+ </para>
+ <formalpara>
+ <title>No file-level locking</title>
+ <para>
+ Since transactional objects are concurrency controlled through <methodname>LockManager</methodname>, it is not necessary to impose additional locking at the file level, as the basic ShadowingStore implementation does. Therefore, the default object store implementation for JBossTS, <methodname>ShadowNoFileLockStore</methodname>, relies upon user-level locking. This enables it to provide better performance than the <methodname>ShadowingStore</methodname> implementation.
+ </para>
+ </formalpara>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>ShadowNoFileLockStore</type>.
+ </para>
+ <formalpara>
+ <title>The hashed store</title>
+ <para>
+ The <code>HashedStore</code> has the same structure for object states as the shadowing stores but has an alternate directory structure that is better suited to storing large numbers of objects of the same type. Using this store objects are scattered amongst a set of directories by applying a hashing function to the object's Uid. By default 255 sub-directories are used. However, this can be overridden by setting the <code>HASHED_DIRECTORIES</code> environment variable accordingly.
+ </para>
+ </formalpara>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>HashedStore</type>.
+ </para>
+ <formalpara>
+ <title>No file-level locking</title>
+ <para>
+ Since transactional objects are concurrency controlled through <methodname>LockManager</methodname>, it is not necessary to impose additional locking at the file level, as the basic <methodname>ShadowingStore</methodname> implementation does. Therefore, the default object store implementation for JBossTS, <methodname>ShadowNoFileLockStore</methodname>, relies upon user-level locking. This enables it to provide better performance than the <methodname>ShadowingStore</methodname> implementation.
+ </para>
+ </formalpara>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>ShadowNoFileLockStore</type>.
+ </para>
+ <formalpara>
+ <title>The hashed store</title>
+ <para>
+ The <methodname>HashedStore</methodname> has the same structure for object states as the shadowing stores but has an alternate directory structure that is better suited to storing large numbers of objects of the same type. Using this store objects are scattered amongst a set of directories by applying a hashing function to the object's Uid. By default 255 sub-directories are used. However, this can be overridden by setting the <code>HASHED_DIRECTORIES</code> environment variable accordingly.
+ </para>
+ </formalpara>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>HashedStore</type>.
+ </para>
+ <formalpara>
+ <title>The JDBC store</title>
+ <para>
+ The <methodname>JDBCStore</methodname> uses a JDBC database to save persistent object states; when used in conjunction with the Transactional Objects for Java API nested transaction support is available. In the current implementation, all object states are stored as Binary Large Objects (BLOBs) within the same table. The limitation on object state size imposed by using BLOBs is 64k; if an attempt is made to store an object state which exceeds this limit an error will be output and the state will not be stored. The transaction will subsequently be forced to roll back.
+ </para>
+ </formalpara>
+ <para>
+ When using the JDBC object store, the application must provide an implementation of the following interface, located in the <code>com.arjuna.ats.arjuna.objectstore</code> package:
+ </para>
+<screen>
+public interface JDBCAccess
+{
+ public Connection getConnection () throws SQLException;
+ public void putConnection (Connection conn) throws SQLException;
+ public void initialise (ObjectName objName);
+}
+</screen>
+ <para>
+ The implementation of this class is responsible for providing the <emphasis>Connection</emphasis> which the JDBC ObjectStore will use to save and restore object states:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>getConnection</methodname>: returns the Connection to use. This method will be called whenever a connection is required and the implementation should use whatever policy is necessary for determining what connection to return. This method need not return the same Connection instance more than once.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>putConnection</methodname>: this method will be called to return one of the Connections acquired from getConnection. Connections are returned if any errors occur when using them.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>initialise</methodname>: this can be used to pass additional arbitrary information to the implementation.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The JDBC object store will initially request the number of Connections defined in the <property>com.arjuna.ats.arjuna.objectstore.jdbcPoolSizeInitial</property> property and will use no more than defined in the <property>com.arjuna.ats.arjuna.objectstore.jdbcPoolSizeMaximum</property> property.
+ </para>
+ <para>
+ The implementation of the <interfacename>JDBCAccess</interfacename> interface to use should be set in the <property>com.arjuna.ats.arjuna.objectstore.jdbcUserDbAccess</property> property variable.
+ </para>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>JDBCStore</type>.
+ </para>
+ <para>
+ A JDBC object store can be used for managing the transaction log. In this case, the transaction log implementation should be set to <property>JDBCActionStore</property> and the <methodname>JDBCAccess</methodname> implementation must be provided via the <property>com.arjuna.ats.arjuna.objectstore.jdbcTxDbAccess</property> property variable. In this case, the default table name is JBossTSTxTable.
+ </para>
+ <note>
+ <para>
+ It is possible to use the same JDBCAccess implementation for both the user object store and also the transaction log.
+ </para>
+ </note>
+ <formalpara>
+ <title>The cached store</title>
+ <para>
+ This object store used the hashed object store, but does not read or write states to the persistent backing store immediately. It maintains the states in a volatile memory cache and either flushes the cache periodically or when it is full. The failure semantics associated with this object store are different to the normal persistent object stores, because a failure could result in states in the cache being lost.
+ </para>
+ </formalpara>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>CachedStore</type>.
+ </para>
+ <para>
+ The store can be configured with the following properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <property>com.arjuna.ats.internal.arjuna.objectstore.cacheStore.hash</property> sets the number of internal stores to hash the states over. The default value is 128.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>com.arjuna.ats.internal.arjuna.objectstore.cacheStore.size</property> is the maximum size the cache can reach before a flush is triggered. The default is 10240 bytes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>com.arjuna.ats.internal.arjuna.objectstore.cacheStore.removedItems</property> is the maximum number of removed items that the cache can contain before a flush is triggered. By default, calls to remove a state that is in the cache will simply remove the state from the cache, but leave a blank entry (rather than remove the entry immediately, which would affect the performance of the cache). When triggered, these entries are removed from the cache. The default value is twice the size of the hash.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>com.arjuna.ats.internal.arjuna.objectstore.cacheStore.workItems</property> is the maximum number of items that are allowed to build up in the cache before it is flushed. The default value is 100.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>com.arjuna.ats.internal.arjuna.objectstore.cacheStore.scanPeriod</property> sets the time in milliseconds for periodically flushing the cache. The default is 120 seconds.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>com.arjuna.ats.internal.arjuna.objectstore.cacheStore.sync</property> determines whether flushes of the cache are sync-ed to disk. The default is OFF. To enable, set to ON.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</appendix>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_A.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_B.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_B.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_B.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,235 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<appendix>
+ <title>Class definitions</title>
+
+ <section>
+ <title>Introduction</title>
+ <para>
+ This appendix contains an overview of those classes that the application programmer will typically use. The aim of this appendix is to provide a quick reference guide to these classes for use when writing applications in TxCore. For clarity only the public and protected interfaces of the classes will be given.
+ </para>
+ </section>
+ <section>
+ <title>Class library</title>
+ <formalpara>
+ <title>Lock Manager</title>
+ <para></para>
+ </formalpara>
+<screen>
+public class LockResult
+{
+ public static final int GRANTED;
+ public static final int REFUSED;
+ public static final int RELEASED;
+};
+
+public class ConflictType
+{
+ public static final int CONFLICT;
+ public static final int COMPATIBLE;
+ public static final int PRESENT;
+};
+
+public abstract class LockManager extends StateManager
+{
+ public static final int defaultRetry;
+ public static final int defaultTimeout;
+ public static final int waitTotalTimeout;
+
+ public final synchronized boolean releaselock (Uid lockUid);
+ public final synchronized int setlock (Lock toSet);
+ public final synchronized int setlock (Lock toSet, int retry);
+ public final synchronized int setlock (Lock toSet, int retry, int sleepTime);
+ public void print (PrintStream strm);
+ public String type ();
+ public boolean save_state (OutputObjectState os, int ObjectType);
+ public boolean restore_state (InputObjectState os, int ObjectType);
+
+ protected LockManager ();
+ protected LockManager (int ot);
+ protected LockManager (int ot, ObjectName attr);
+ protected LockManager (Uid storeUid);
+ protected LockManager (Uid storeUid, int ot);
+ protected LockManager (Uid storeUid, int ot, ObjectName attr);
+
+ protected void terminate ();
+};
+</screen>
+ <formalpara>
+ <title>StateManager</title>
+ <para></para>
+ </formalpara>
+<screen>
+public class ObjectStatus
+{
+ public static final int PASSIVE;
+ public static final int PASSIVE_NEW;
+ public static final int ACTIVE;
+ public static final int ACTIVE_NEW;
+};
+
+public class ObjectType
+{
+ public static final int RECOVERABLE;
+ public static final int ANDPERSISTENT;
+ public static final int NEITHER;
+};
+
+public abstract class StateManager
+{
+ public boolean restore_state (InputObjectState os, int ot);
+ public boolean save_state (OutputObjectState os, int ot);
+ public String type ();
+
+ public synchronized boolean activate ();
+ public synchronized boolean activate (String rootName);
+ public synchronized boolean deactivate ();
+ public synchronized boolean deactivate (String rootName);
+ public synchronized boolean deactivate (String rootName, boolean commit);
+
+ public synchronized int status ();
+ public final Uid get_uid ();
+ public void destroy ();
+ public void print (PrintStream strm);
+
+ protected void terminate ();
+
+ protected StateManager ();
+ protected StateManager (int ot);
+ protected StateManager (int ot, ObjectName objName);
+ protected StateManager (Uid objUid);
+ protected StateManager (Uid objUid, int ot);
+ protected StateManager (Uid objUid, int ot, ObjectName objName);
+ protected synchronized final void modified ();
+};
+</screen>
+ <formalpara>
+ <title>Input/OutputObjectState</title>
+ <para></para>
+ </formalpara>
+<screen>
+class OutputObjectState extends OutputBuffer
+{
+ public OutputObjectState (Uid newUid, String typeName);
+
+ public boolean notempty ();
+ public int size ();
+ public Uid stateUid ();
+ public String type ();
+};
+class InputObjectState extends ObjectState
+{
+ public OutputObjectState (Uid newUid, String typeName, byte[] b);
+
+ public boolean notempty ();
+ public int size ();
+ public Uid stateUid ();
+ public String type ();
+};
+</screen>
+ <formalpara>
+ <title>Input/OutputBuffer</title>
+ <para></para>
+ </formalpara>
+<screen>
+public class OutputBuffer
+{
+ public OutputBuffer ();
+
+ public final synchronized boolean valid ();
+ public synchronized byte[] buffer();
+ public synchronized int length ();
+
+ /* pack operations for standard Java types */
+
+ public synchronized void packByte (byte b) throws IOException;
+ public synchronized void packBytes (byte[] b) throws IOException;
+ public synchronized void packBoolean (boolean b) throws IOException;
+ public synchronized void packChar (char c) throws IOException;
+ public synchronized void packShort (short s) throws IOException;
+ public synchronized void packInt (int i) throws IOException;
+ public synchronized void packLong (long l) throws IOException;
+ public synchronized void packFloat (float f) throws IOException;
+ public synchronized void packDouble (double d) throws IOException;
+ public synchronized void packString (String s) throws IOException;
+};
+public class InputBuffer
+{
+ public InputBuffer ();
+
+ public final synchronized boolean valid ();
+ public synchronized byte[] buffer();
+ public synchronized int length ();
+
+ /* unpack operations for standard Java types */
+
+ public synchronized byte unpackByte () throws IOException;
+ public synchronized byte[] unpackBytes () throws IOException;
+ public synchronized boolean unpackBoolean () throws IOException;
+ public synchronized char unpackChar () throws IOException;
+ public synchronized short unpackShort () throws IOException;
+ public synchronized int unpackInt () throws IOException;
+ public synchronized long unpackLong () throws IOException;
+ public synchronized float unpackFloat () throws IOException;
+ public synchronized double unpackDouble () throws IOException;
+ public synchronized String unpackString () throws IOException;
+};
+</screen>
+ <formalpara>
+ <title>Uid</title>
+ <para></para>
+ </formalpara>
+<screen>
+public class Uid implements Cloneable
+{
+ public Uid ();
+ public Uid (Uid copyFrom);
+ public Uid (String uidString);
+ public Uid (String uidString, boolean errorsOk);
+ public synchronized void pack (OutputBuffer packInto) throws IOException;
+ public synchronized void unpack (InputBuffer unpackFrom) throws IOException;
+
+ public void print (PrintStream strm);
+ public String toString ();
+ public Object clone () throws CloneNotSupportedException;
+ public synchronized void copy (Uid toCopy) throws UidException;
+ public boolean equals (Uid u);
+ public boolean notEquals (Uid u);
+ public boolean lessThan (Uid u);
+ public boolean greaterThan (Uid u);
+
+ public synchronized final boolean valid ();
+ public static synchronized Uid nullUid ();
+};
+</screen>
+ <formalpara>
+ <title>AtomicAction</title>
+ <para></para>
+ </formalpara>
+<screen>
+public class AtomicAction
+{
+ public AtomicAction ();
+
+ 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 sr)
+ throws SystemException, NotSubtransaction;
+ public void registerSynchronization (Synchronization s) throws SystemException,
+ Inactive;
+};
+</screen>
+ </section>
+</appendix>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Appendix_B.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Author_Group.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Author_Group.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Author_Group.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,10 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<authorgroup>
+ <corpauthor>
+ Red Hat Documentation Group
+ </corpauthor>
+</authorgroup>
+
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Author_Group.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,26 @@
+<?xml version='1.0'?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<bookinfo>
+ <title>JBoss TS Programmers Guide</title>
+ <subtitle>JBoss Enterprise SOA Platform</subtitle>
+ <issuenum>1.0</issuenum>
+ <productnumber>4.3</productnumber>
+ <abstract>
+ <para>This book is the Enterprise Application Platform edition of the JBoss TS Programmers
+Guide</para></abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="Common_Content/images/redhat-logo.svg" />
+ </imageobject>
+ </inlinemediaobject>
+ </corpauthor>
+ <copyright>
+ <year>&YEAR;</year>
+ <holder>&HOLDER;</holder>
+ </copyright>
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
+
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,292 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+ <title>Overview</title>
+
+ <section>
+ <title>Introduction</title>
+ <para>This chapter contains a description of the use of the <classname>TxCore</classname> transaction engine and the <firstterm>Transactional Objects for Java</firstterm> classes and facilities. The classes mentioned in this chapter are the key to writing fault-tolerant applications using transactions. Thus, after describing them we shall apply them in the construction of a simple application. The classes to be described in this chapter can be found in the <classname>com.arjuna.ats.txoj</classname> and <classname>com.arjuna.ats.arjuna</classname> packages.</para>
+ </section>
+
+ <section>
+ <title>TxCore – the transaction engine</title>
+
+ <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; while other mechanisms, such as object storage and transactions, are implemented as <classname>TxCore</classname> 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 <emphasis>Transactional Objects for Java</emphasis> (TXOJ) classes are being used. If this is not the case then the programmer is responsible for all of these issues.</para></note>
+
+ <para><classname>TxCore</classname> 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 below and which will be described later in this document.</para>
+
+ <mediaobject id="figure_1">
+ <imageobject>
+ <imagedata align="center" fileref="images/image1.png" />
+ </imageobject>
+ <caption> Txcore class hierarchy </caption>
+ </mediaobject>
+
+ <para>Apart from specifying the scopes of transactions, and setting appropriate locks within objects, the application programmer does not have any other responsibilities: <classname>TxCore</classname> and <emphasis>Transactional Objects for Java</emphasis> (TXOJ) 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>
+
+ <title>Saving object states</title>
+
+ <para>
+ <classname>TxCore</classname> needs to be able to remember the state of an object for several purposes, including recovery (the state represents some past state of the object) and persistence (the state represents the final state of an object at application termination). 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 (unpacked) using appropriate <command>pack</command> (<command>unpack</command>) 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 (so-called network byte order) to make them machine independent. Any other architecture independent format (such as XDR or ASN.1) could be implemented s!
imply 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 <classname>TxCore</classname> is implemented using the techniques of interface/implementation. The current distribution has 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 (instances of the Uid class), when they are created, and this is used to identify them within the object store. States are read using the <literal>read_committed</literal> operation and written by the <literal>write_(un)committed</literal> operations.
+ </para>
+ </section>
+
+ <section>
+ <title>Recovery and persistence</title>
+ <para>At the root of the class hierarchy is the class <classname>StateManager</classname>. This class is responsible for object activation and deactivation and object recovery. The simplified signature of the class is:</para>
+
+ <screen>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);
+};
+ </screen>
+
+ <para>Objects are assumed to be of three possible flavours. They may simply be recoverable, in which case <classname>StateManager</classname> will attempt to generate and maintain appropriate recovery information for the object. Such objects have lifetimes that do not exceed the application program that creates them. Objects may be recoverable and persistent, in which case 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> will attempt to automatically load (unload) any existing persistent state for the object by calling the activate (deactivate) operation at appropriate times. Finally, objects may possess none of these capabilities, in which case no recovery information is ever kept nor is object activation/deactivation ever automatically attempted.</para>
+
+
+ <para>If an object is recoverable or recoverable and persistent then <classname>StateManager</classname> will invoke the operations <command>save_state</command> (while performing <command>deactivate</command>), and <command>restore_state</command> (while performing activate) 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 <command>save_state</command> and <command>restore_state</command> 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 <command>save_state</comman!
d> implementation for a class <classname>Example</classname> that has integer member variables called A, B and C could simply be:</para>
+
+ <screen>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;
+}
+ </screen>
+
+ <para>Objects are assumed to be of three possible flavours. They may simply be <emphasis>recoverable</emphasis>, in which case <classname>StateManager</classname> will attempt to generate and maintain appropriate recovery information for the object. Such objects have lifetimes that do not exceed the application program that creates them. Objects may be <emphasis>recoverable and persistent</emphasis>, in which case 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> will attempt to automatically load (unload) any existing persistent state for the object by calling the <classname>activate</classname> (<classname>deactivate</classname>) operation at appropriate times. Finally, objects may possess none of these capabilities, in which case no recovery information is ever kept nor is object activation/deactivation ever automat!
ically attempted.</para>
+
+ <para>If an object is <emphasis>recoverable</emphasis> or <emphasis>recoverable and persistent</emphasis> then <classname>StateManager</classname> will invoke the operations <command>save_state</command> (while performing <command>deactivate</command>), and <command>restore_state</command> (while performing <command>activate</command>) 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 <classname>save_state</classname> and <classname>restore_state</classname> 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 <classname>save_state</classname> implementation for a class <classname>Example</classname> that has integer member variables called A, B and C could simply be:</para>
+
+ <screen>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;
+}
+ </screen>
+ <note><para>It is necessary for all <command>save_state</command> and <command>restore_state</command> methods to call <classname>super.save_state </classname>and <classname>super.restore_state</classname>. 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 <emphasis>passive</emphasis> state with its state residing in an object store and <emphasis>activated</emphasis> on demand. The fundamental life cycle of a persistent object in <emphasis>TXOJ</emphasis> is shown in <xref linkend="figure_2"/>.</para>
+
+ <mediaobject id="figure_2">
+ <imageobject>
+ <imagedata align="center" fileref="images/image2.png" />
+ </imageobject>
+ <caption> The lifecycle of a persistent object. </caption>
+ </mediaobject>
+
+ <itemizedlist>
+ <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 <command>read_committed</command> operation and is then converted from an <classname>InputObjectState</classname> instance into a fully-fledged object by the <command>restore_state</command> 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 <command>save_state</command> operation, and is then stored back into the object store as a shadow copy using write_uncommitted. This shadow copy can be committed, overwriting the previous version, using the <command>commit_state</command> operation. The existence of shadow copies is normally hidden from the programmer by the transaction system. Object de-activation normally only occurs when the top-level transaction within which the object was activated commits.</para></listitem>
+ </itemizedlist>
+
+ <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 behaviour 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>
+
+ <itemizedlist>
+ <listitem><para>local disk/database implementation, where locks are made persistent by being written to the local file system or database.</para></listitem>
+ <listitem><para>a purely local implementation, where 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>
+ </itemizedlist>
+
+ <para>The primary programmer interface to the concurrency controller is via the setlock 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="figure_1"/>, by inheriting from the <classname>Lock</classname> class it is possible for programmers to provide their own lock implementations with different lock conflict rules to enable <firstterm>type specific concurrency control</firstterm>.</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>
+
+ <screen>public abstract class LockManager extends StateManager
+{
+ public LockResult setlock (Lock toSet, int retry, int timeout);
+};</screen>
+
+ <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 activate to be invoked.</para>
+
+ <para>The code below shows how we may try to obtain a write lock on an object:</para>
+
+ <screen>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;
+}
+}</screen>
+
+ </section>
+
+ <section>
+ <title>The transaction protocol engine</title>
+
+ <para>The transaction protocol engine is represented by the <classname>AtomicAction</classname> class, which uses <classname>StateManager</classname> in order 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 require to implement their own resources, methods for registering them with the current transaction. Because <emphasis>TxCore</emphasis> supports subtransactions, if a transaction is begun within the scope of an already executing transaction it will automatically be nested.</para>
+
+ <note><para><emphasis>TxCore</emphasis> is multi-threaded aware, allowing each thread within an application to share a transaction or execute within its own transaction. Therefore, all <emphasis>TxCore</emphasis> classes are also thread safe.</para></note>
+ </section>
+
+ <section>
+ <title>Example</title>
+
+ <para>The simple example below illustrates the relationships between activation, termination and commitment:</para>
+
+ <screen>{
+ . . .
+ 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) */</screen>
+
+ <para>The execution of the above code involves the following sequence of activities:</para>
+
+ <itemizedlist>
+ <listitem><para>Creation of bindings to persistent objects; this could involve the creation of stub objects and a call to remote objects. In the above example we re-bind to an existing persistent object identified by <literal>Name-A</literal>, 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.</para></listitem>
+ <listitem><para>Start of the atomic transaction.</para></listitem>
+ <listitem><para>Operation invocations: 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 initialised, 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>
+ <listitem><para>Commit of the top-level action. This includes updating of the state of any modified objects in the object store.</para></listitem>
+ <listitem><para>Breaking of the previously created bindings.</para></listitem>
+ </itemizedlist>
+
+ </section>
+
+ <section>
+ <title>The class hierarchy</title>
+
+ <para>The principal classes which make up the class hierarchy of <emphasis>TxCore</emphasis> are depicted below.</para>
+
+ <screen>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</screen>
+
+ <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>. Most <emphasis>TxCore</emphasis> 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. The class <classname>LockManager</classname> uses the facilities of <classname>StateManager</classname> and <classname>Lock</classname> to provide the concurrency control (two-phase locking in the current implementation) required for implementing the serialisability property of atomic actions. The implementation of atomic action facilities is !
supported by <classname>AtomicAction</classname> and <classname>TopLevelTransaction</classname>.</para>
+
+ <para>Most <emphasis>TxCore</emphasis> system 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. The class <classname>LockManager</classname> uses the facilities of <classname>StateManager</classname> and provides the concurrency control required for implementing the serialisability property of atomic actions.</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 Trans accesses an object (called O) of type <classname>Example</classname> by invoking the operation op1 which involves state changes to O. The serialisability property requires that a write lock must be acquired on O before it is modified; thus the body of op1 should contain a call to the <literal>setlock</literal> operation of the concurrency controller:</para>
+
+ <screen>public boolean op1 (...)
+{
+ if (setlock (new Lock(LockMode.WRITE) == LockResult.GRANTED)
+ {
+ // actual state change operations follow
+ ...
+ }
+}</screen>
+
+ <para>The operation <literal>setlock</literal>, provided by the <classname>LockManager</classname> class, performs the following functions in this case:</para>
+
+ <itemizedlist>
+ <listitem><para>Check write lock compatibility with the currently held locks, and if allowed:</para></listitem>
+ <listitem><para>Call the <classname>StateManager</classname> operation activate that will load, if not done already, the latest persistent state of O from the object store. Then call the <classname>StateManager</classname> operation modified which has the effect of creating an instance of either <classname>RecoveryRecord</classname> or <classname>PersistenceRecord</classname> for O depending upon whether O was persistent or not (the Lock is a <literal>WRITE</literal> lock so the old state of the object must be retained prior to modification) and inserting it into the <classname>RecordList</classname> of <classname>Trans</classname>.</para></listitem>
+ <listitem><para>Create and insert a LockRecord instance in the RecordList of Trans.</para></listitem>
+ </itemizedlist>
+
+ <para>Now suppose that action <literal>Trans</literal> is aborted sometime after the lock has been acquired. Then the rollback operation of <classname>AtomicAction</classname> will process the <classname>RecordList</classname> instance associated with <literal>Trans</literal> by invoking an appropriate <literal>Abort</literal> operation on the various records. The implementation of this operation by the <classname>LockRecord</classname> class will release the <literal>WRITE</literal> lock while that of <classname>RecoveryRecord</classname>/<classname>PersistenceRecord</classname> will restore the prior state of O.</para>
+
+ <para>It is important to realise that all of the above work is automatically being performed by <emphasis>TxCore</emphasis> on behalf of the application programmer. The programmer need only start the transaction and set an appropriate lock; <emphasis>TxCore</emphasis> and <emphasis>Transactional Objects for Java</emphasis> take care of participant registration, persistence, concurrency control and recovery.</para>
+
+ </section>
+
+
+
+ </section>
+
+</chapter>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_02.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_02.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_02.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,652 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+ <title>Using TxCore</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>In this section we shall describe <emphasis>TxCore</emphasis> and <emphasis>Transactional Objects for Java</emphasis> in more detail, and show how it can be used to construct transactional applications.</para>
+ </section>
+
+ <section>
+ <title>State management</title>
+
+ <section>
+ <title>Object States</title>
+
+ <para><emphasis>TxCore</emphasis> needs to be able to remember the state of an object for several purposes, including recovery (the state represents some past state of the object), and for persistence (the state represents the final state of an object at application termination). Since all of these requirements require common functionality they are all implemented using the same mechanism - the classes <classname>Input/OutputObjectState</classname> and <classname>Input/OutputBuffer</classname>.</para>
+
+ <formalpara><title>OutputBuffer</title>
+
+ <para><programlisting>public class OutputBuffer
+{
+public OutputBuffer ();
+
+public final synchronized boolean valid ();
+public synchronized byte[] buffer();
+public synchronized int length ();
+
+ /* pack operations for standard Java types */
+
+public synchronized void packByte (byte b) throws IOException;
+public synchronized void packBytes (byte[] b) throws IOException;
+public synchronized void packBoolean (boolean b) throws IOException;
+public synchronized void packChar (char c) throws IOException;
+public synchronized void packShort (short s) throws IOException;
+public synchronized void packInt (int i) throws IOException;
+public synchronized void packLong (long l) throws IOException;
+public synchronized void packFloat (float f) throws IOException;
+public synchronized void packDouble (double d) throws IOException;
+public synchronized void packString (String s) throws IOException;
+};</programlisting></para></formalpara>
+
+ <formalpara><title>InputBuffer</title><para><programlisting>public class InputBuffer
+{
+public InputBuffer ();
+
+public final synchronized boolean valid ();
+public synchronized byte[] buffer();
+public synchronized int length ();
+
+/* unpack operations for standard Java types */
+
+public synchronized byte unpackByte () throws IOException;
+public synchronized byte[] unpackBytes () throws IOException;
+public synchronized boolean unpackBoolean () throws IOException;
+public synchronized char unpackChar () throws IOException;
+public synchronized short unpackShort () throws IOException;
+public synchronized int unpackInt () throws IOException;
+public synchronized long unpackLong () throws IOException;
+public synchronized float unpackFloat () throws IOException;
+public synchronized double unpackDouble () throws IOException;
+public synchronized String unpackString () throws IOException;
+};</programlisting></para></formalpara>
+
+ <para>The <classname>Input/OutputBuffer</classname> class maintains an internal array into which instances of the standard Java types can be contiguously packed (unpacked) using the pack (unpack) 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 (so-called network byte order) to make them machine independent.</para>
+
+ <formalpara><title>OutputObjectState</title>
+
+ <para><programlisting>class OutputObjectState extends OutputBuffer
+{
+public OutputObjectState (Uid newUid, String typeName);
+
+public boolean notempty ();
+public int size ();
+public Uidpublic class InputBuffer
+{
+public InputBuffer ();
+
+public final synchronized boolean valid ();
+public synchronized byte[] buffer();
+public synchronized int length ();
+
+/* unpack operations for standard Java types */
+
+public synchronized byte unpackByte () throws IOException;
+public synchronized byte[] unpackBytes () throws IOException;
+public synchronized boolean unpackBoolean () throws IOException;
+public synchronized char unpackChar () throws IOException;
+public synchronized short unpackShort () throws IOException;
+public synchronized int unpackInt () throws IOException;
+public synchronized long unpackLong () throws IOException;
+public synchronized float unpackFloat () throws IOException;
+public synchronized double unpackDouble () throws IOException;
+public synchronized String unpackString () throws IOException;
+};</programlisting></para></formalpara>
+
+ <para>The <classname>Input/OutputBuffer</classname> class maintains an internal array into which instances of the standard Java types can be contiguously packed (unpacked) using the pack (unpack) 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 (so-called network byte order) to make them machine independent.</para>
+
+ <formalpara>
+ <title>
+ OutputObjectState
+ </title>
+
+ <para>
+ <programlisting>class OutputObjectState extends OutputBuffer
+{
+ public OutputObjectState (Uid newUid, String typeName);
+
+ public boolean notempty ();
+ public int size ();
+ public Uid stateUid ();
+ public String type ();
+};</programlisting>
+ </para>
+
+ </formalpara>
+
+
+ <formalpara>
+ <title>InputObjectState</title>
+ <para>
+ <programlisting>class InputObjectState extends InputBuffer
+{
+ public OutputObjectState (Uid newUid, String typeName, byte[] b);
+
+ public boolean notempty ();
+ public int size ();
+ public Uid stateUid ();
+ public String type ();
+};</programlisting>
+ </para>
+ </formalpara>
+
+
+ <para>The class <classname>Input/OutputObjectState</classname> provides all the functionality of <classname>Input/OutputBuffer</classname> (through inheritance) but adds two additional instance variables that signify the Uid and type of the object for which the <classname>Input/OutputObjectState</classname> instance is a compressed image. These are used when accessing the object store during storage and retrieval of the object state.</para>
+ </section>
+
+ <section>
+ <title>The object store</title>
+
+ <para>The object store provided with <emphasis>TxCore</emphasis> deliberately has a fairly restricted interface so that it can be implemented in a variety of ways. For example, object stores are implemented in shared memory; on the Unix file system (in several different forms); and as a remotely accessible store. More complete information about the object stores available in <emphasis>TxCore</emphasis> can be found in the Appendix.</para>
+
+ <note><para>As with all <emphasis>TxCore</emphasis> classes the default object stores are pure Java implementations; to access the shared memory and other more complex object store implementations it is necessary to use native methods.</para></note>
+
+ <para>All of the object stores hold and retrieve instances of the class <classname>Input/OutputObjectState</classname>. These instances are named by the Uid and Type of the object that they represent. States are read using the <command>read_committed</command> operation and written by the system using the <command>write_uncommitted</command> operation. Under normal operation new object states do not overwrite old object states but are written to the store as shadow copies. These shadows replace the original only when the <command>commit_state</command> operation is invoked. Normally all interaction with the object store is performed by <emphasis>TxCore</emphasis> system components as appropriate thus the existence of any shadow versions of objects in the store are hidden from the programmer.</para>
+
+ <screen>public class ObjectStore
+{
+public static final int OS_COMMITTED;
+public static final int OS_UNCOMMITTED;
+public static final int OS_COMMITTED_HIDDEN;
+public static final int OS_UNCOMMITTED_HIDDEN;
+public static final int OS_UNKNOWN;
+
+/* The abstract interface */
+public abstract boolean commit_state (Uid u, String name)
+throws ObjectStoreException;
+public abstract InputObjectState read_committed (Uid u, String name)
+throws ObjectStoreException;
+public abstract boolean write_uncommitted (Uid u, String name,
+OutputObjectState os) throws ObjectStoreException;
+. . .
+};</screen>
+
+ <para>When a transactional object is committing it is necessary for it to make certain state changes persistent in order that it can recover in the event of a failure and either continue to commit, or rollback. When using <emphasis>Transactional Objects for Java</emphasis>, <emphasis>TxCore</emphasis> will take care of this automatically. To guarantee ACID properties, these state changes must be flushed to the persistence store implementation before the transaction can proceed to commit; if they are not, the application may assume that the transaction has committed when in fact the state changes may still reside within an operating system cache, and may be lost by a subsequent machine failure. By default, <emphasis>TxCore</emphasis> ensures that such state changes are flushed. However, doing so can impose a significant performance penalty on the application. To prevent transactional object state flushes, set the <literal>com.arjuna.ats.arjuna.objectstore.objectStore!
Sync</literal> variable to OFF.</para>
+
+ </section>
+
+ <section><title>Selecting an object store implementation</title>
+
+ <para>
+ <emphasis>TxCore</emphasis> comes with support for several different object store implementations. The Appendix describes these implementations, how to select and configure a given implementation (using the <literal>com.arjuna.ats.arjuna.objectstore.objectStoreType</literal> property variable) on a per object basis, and indicates how additional implementations can be provided.
+ </para>
+
+ </section>
+
+ <section>
+
+ <title>StateManager</title>
+
+ <para>The <emphasis>TxCore</emphasis> class <classname>StateManager</classname> manages the state of an object and provides all of the basic support mechanisms required by an object for state management purposes. <classname>StateManager</classname> is responsible for creating and registering appropriate resources concerned with the persistence and recovery of the transactional object. If a transaction is nested, then <classname>StateManager</classname> will also propagate these resources between child transactions and their parents at commit time.</para>
+
+ <para>
+ Objects in <emphasis>TxCore</emphasis> are assumed to be of three possible basic flavours. They may simply be recoverable, in which case <classname>StateManager</classname> will attempt to generate and maintain appropriate recovery information for the object (as instances of the class <classname>Input/OutputObjectState</classname>) . Such objects have lifetimes that do not exceed the application program that creates them. Objects may be recoverable and persistent, in which case 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> will attempt to automatically load (unload) any existing persistent state for the object by calling the <command>activate</command> (<command>deactivate</command>) operation at appropriate times. Finally, objects may possess none of these capabilities in which case no recovery information is ever !
kept nor is object activation/deactivation ever automatically attempted. This object property is selected at object construction time and cannot be changed thereafter. Thus an object cannot gain (or lose) recovery capabilities at some arbitrary point during its lifetime.
+ </para>
+
+ <screen>public class ObjectStatus
+{
+ public static final int PASSIVE;
+ public static final int PASSIVE_NEW;
+ public static final int ACTIVE;
+ public static final int ACTIVE_NEW;
+ public static final int UNKNOWN_STATUS;
+};
+
+public class ObjectType
+{
+ public static final int RECOVERABLE;
+ public static final int ANDPERSISTENT;
+ public static final int NEITHER;
+};
+
+public abstract class StateManager
+{
+ public synchronized boolean activate ();
+ public synchronized boolean activate (String storeRoot);
+ public synchronized boolean deactivate ();
+ public synchronized boolean deactivate (String storeRoot, boolean commit);
+
+ public synchronized void destroy ();
+
+ public final Uid get_uid ();
+
+ public boolean restore_state (InputObjectState, int ObjectType);
+ public boolean save_state (OutputObjectState, int ObjectType);
+ public String type ();
+ . . .
+
+ protected StateManager ();
+ protected StateManager (int ObjectType, ObjectName attr);
+ protected StateManager (Uid uid);
+ protected StateManager (Uid uid, ObjectName attr);
+ . . .
+
+ protected final void modified ();
+ . . .
+};
+
+public class ObjectModel
+{
+ public static final int SINGLE;
+ public static final int MULTIPLE;
+};</screen>
+
+ <para>If an object is recoverable (or persistent) then <classname>StateManager</classname> will invoke the operations <command>save_state</command> (while performing <command>deactivation</command>), <command>restore_state</command> (while performing activate) and type at various points during the execution of the application. These operations must be implemented by the programmer since <classname>StateManager</classname> does not have access to a runtime description of the layout of an arbitrary Java object in memory and thus cannot implement a default policy for converting the in memory version of the object to its passive form. However, the capabilities provided by <classname>Input/OutputObjectState</classname> make the writing of these routines fairly simple. For example, the <command>save_state</command> implementation for a class <classname>Example</classname> that had member variables called A, B and C could simply be the following:</para>
+
+ <screen>public boolean save_state ( OutputObjectState os, int ObjectType )
+{
+ if (!super.save_state(os, ObjectType))
+ return false;
+
+ try
+ {
+ os.packInt(A);
+ os.packString(B);
+ os.packFloat(C);
+
+ return true;
+ }
+ catch (IOException e)
+ {
+ return false;
+ }
+}</screen>
+
+ <para>In order to support crash recovery for persistent objects it is necessary for all <command>save_state</command> and <command>restore_state</command> methods of user objects to call <command>super.save_state</command> and <command>super.restore_state</command>.</para>
+
+ <note><para>The type method is used to determine the location in the object store where the state of instances of that class will be saved and ultimately restored. This can actually be any valid string. However, you should avoid using the hash character (#) as this is reserved for special directories that <emphasis>TxCore</emphasis> requires.</para></note>
+
+ <para>The <command>get_uid</command> operation of <classname>StateManager</classname> provides read only access to an object’s internal system name for whatever purpose the programmer requires (such as registration of the name in a name server). The value of the internal system name can only be set when an object is initially constructed - either by the provision of an explicit parameter or by generating a new identifier when the object is created.</para>
+
+ <para>The <command>destroy</command> method can be used to remove the object’s state from the object store. This is an atomic operation, and therefore will only remove the state if the top-level transaction within which it is invoked eventually commits. The programmer must obtain exclusive access to the object prior to invoking this operation.</para>
+
+ <para>Since object recovery and persistence essentially have complimentary requirements (the only difference being where state information is stored and for what purpose) <classname>StateManager</classname> effectively combines the management of these two properties into a single mechanism. That is, it uses instances of the class Input/OutputObjectState both for recovery and persistence purposes. An additional argument passed to the <command>save_state</command> and <command>restore_state</command> operations allows the programmer to determine the purpose for which any given invocation is being made thus allowing different information to be saved for recovery and persistence purposes.</para>
+
+
+ </section>
+
+ <section>
+ <title>Object Models</title>
+
+ <para><emphasis>TxCore</emphasis> supports two models for objects, which as we shall show affect how an objects state and concurrency control are implemented:</para>
+
+ <itemizedlist>
+ <listitem><para><termdef>SINGLE</termdef>: only a single copy of the object exists within the application; this will reside within a single JVM, and all clients must address their invocations to this server. This model provides better performance, but represents a single point of failure, and in a multi-threaded environment may not protect the object from corruption if a single thread fails.</para>
+
+ <mediaobject id="figure_3">
+ <imageobject>
+ <imagedata align="center" fileref="images/image3.png" />
+ </imageobject>
+ <caption> Single Object Model</caption>
+ </mediaobject>
+
+ </listitem>
+ <listitem><para>MULTIPLE: logically a single instance of the object exists, but copies of it are distributed across different JVMs; the performance of this model is worse than the SINGLE model, but it provides better failure isolation.</para>
+
+
+ <mediaobject id="figure_4">
+ <imageobject>
+ <imagedata align="center" fileref="images/image4.png" />
+ </imageobject>
+ <caption> Multiple Object Model</caption>
+ </mediaobject>
+ </listitem>
+ </itemizedlist>
+
+ <para>The default model is SINGLE. The programmer can override this on a per object basis by providing an appropriate instance of the <classname>com.arjuna.ats.arjuna.gandiva.ObjectName</classname> class at object construction.</para>
+
+ <note><para>The model can be changed between each successive instantiation of the object, i.e., it need not be the same during the object's lifetime.</para></note>
+
+ <para>
+ To provide a suitable <classname>ObjectName</classname> class, it is necessary to perform the following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>create a new instance of <classname>ObjectName</classname>.</para></listitem>
+ <listitem><para>set the object model attribute using the <literal>com.arjuna.ats.arjuna.ArjunaNames.StateManager_objectModel()</literal> name.</para></listitem>
+ </itemizedlist>
+
+ <para>For example:</para>
+
+ <programlisting>{
+ ObjectName attr = new ObjectName(“SNS:myObjectName”);
+
+ attr.setLongAttribute(ArjunaNames.StateManager_objectModel(),
+ ObjectModel.SINGLE);
+
+ AtomicObject obj = new AtomicObject(ObjectType.ANDPERSISTENT, attr);
+ }</programlisting>
+
+
+
+ </section>
+
+ <section>
+ <title>Summary</title>
+
+ <para>In summary, the <emphasis>TxCore</emphasis> class <classname>StateManager</classname> manages the state of an object and provides all of the basic support mechanisms required by an object for state management purposes. Some operations must be defined by the class developer. These operations are: <command>save_state</command>, <command>restore_state</command>, and <command>type</command>.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>boolean save_state (OutputObjectState state, int ObjectType)</literal></term>
+ <listitem><para>Invoked whenever the state of an object might need to be saved for future use - primarily for recovery or persistence purposes. The <literal>ObjectType</literal> parameter indicates the reason that <command>save_state</command> was invoked by <emphasis>TxCore</emphasis>. This enables the programmer to save different pieces of information into the <classname>OutputObjectState</classname> supplied as the first parameter depending upon whether the state is needed for recovery or persistence purposes. For example, pointers to other <emphasis>TxCore</emphasis> objects might be saved simply as pointers for recovery purposes but as Uid’s for persistence purposes. As shown earlier, the <classname>OutputObjectState</classname> class provides convenient operations to allow the saving of instances of all of the basic types in Java. In order to support crash recovery for persistent objects it is necessary for all <command>save_state</command> metho!
ds to call <command>super.save_state</command>.</para>
+
+ <note><para><command>save_state</command> assumes that an object is internally consistent and that all variables saved have valid values. It is the programmer's responsibility to ensure that this is the case.</para></note></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>boolean restore_state (InputObjectState state, int ObjectType)</literal></term>
+ <listitem><para>Invoked whenever the state of an object needs to be restored to the one supplied. Once again the second parameter allows different interpretations of the supplied state. In order to support crash recovery for persistent objects it is necessary for all <command>restore_state</command> methods to call <command>super.restore_state</command>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>String type ()</literal></term>
+ <listitem><para>The <emphasis>TxCore</emphasis> persistence mechanism requires a means of determining the type of an object as a string so that it can save/restore the state of the object into/from the object store. By convention this information indicates the position of the class in the hierarchy. For example, “/<classname>StateManager</classname>/<classname>LockManager</classname>/<classname>Object</classname>”.</para>
+
+ <note><para>The type method is used to determine the location in the object store where the state of instances of that class will be saved and ultimately restored. This can actually be any valid string. However, you should avoid using the hash character (#) as this is reserved for special directories that <emphasis>TxCore</emphasis> requires.</para></note></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section>
+ <title>Example</title>
+
+ <para>
+ Consider the following basic <classname>Array</classname> class derived from the <classname>StateManager</classname> class (in this example, to illustrate saving and restoring of an object’s state, the highestIndex variable is used to keep track of the highest element of the array that has a non-zero value):
+ </para>
+
+ <programlisting>public class Array extends StateManager
+{
+ public Array ();
+ public Array (Uid objUid);
+ public void finalize ( super.terminate(); };
+
+ /* Class specific operations. */
+
+ public boolean set (int index, int value);
+ public int get (int index);
+
+ /* State management specific operations. */
+
+ public boolean save_state (OutputObjectState os, int ObjectType);
+ public boolean restore_state (InputObjectState os, int ObjectType);
+ public String type ();
+
+ public static final int ARRAY_SIZE = 10;
+
+ private int[] elements = new int[ARRAY_SIZE];
+ private int highestIndex;
+ };</programlisting>
+
+ <para>
+ The <command>save_state</command>, <command>restore_state</command> and <command>type</command> operations can be defined as follows:
+ </para>
+
+ <programlisting>/* Ignore ObjectType parameter for simplicity */
+
+public boolean save_state (OutputObjectState os, int ObjectType)
+{
+ if (!super.save_state(os, ObjectType))
+ return false;
+
+ try
+ {
+ packInt(highestIndex);
+
+ /*
+ * Traverse array state that we wish to save. Only save active elements
+ */
+
+ for (int i = 0; i <= highestIndex; i++)
+ os.packInt(elements[i]);
+
+ return true;
+ }
+ catch (IOException e)
+ {
+ return false;
+ }
+}
+
+public boolean restore_state (InputObjectState os, int ObjectType)
+{
+ if (!super.restore_state(os, ObjectType))
+ return false;
+
+ try
+ {
+ int i = 0;
+
+ highestIndex = os.unpackInt();
+
+ while (i < ARRAY_SIZE)
+ {
+ if (i <= highestIndex)
+ elements[i] = os.unpackInt();
+ else
+ elements[i] = 0;
+ i++;
+ }
+
+ return true;
+ }
+ catch (IOException e)
+ {
+ return false;
+ }
+}
+
+public String type ()
+{
+ return "/StateManager/Array";
+}</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>Lock management and concurrency control</title>
+
+ <para>Concurrency control information within <emphasis>TxCore</emphasis> is maintained by locks. Locks which are required to be shared between objects in different processes may be held within a lock store, similar to the object store facility presented previously. The lock store provided with <emphasis>TxCore</emphasis> deliberately has a fairly restricted interface so that it can be implemented in a variety of ways. For example, lock stores are implemented in shared memory; on the Unix file system (in several different forms); and as a remotely accessible store. More information about the object stores available in <emphasis>TxCore</emphasis> can be found in the Appendix.</para>
+
+ <note><para>As with all <emphasis>TxCore</emphasis> classes the default lock stores are pure Java implementations; to access the shared memory and other more complex lock store implementations it is necessary to use native methods.</para></note>
+
+ <programlisting>public class LockStore
+{
+ public abstract InputObjectState read_state (Uid u, String tName)
+ throws LockStoreException;
+
+ public abstract boolean remove_state (Uid u, String tname);
+ public abstract boolean write_committed (Uid u, String tName,
+ OutputObjectState state);
+ };</programlisting>
+
+ <section>
+ <title>Selecting a lock store implementation</title>
+
+ <para><emphasis>TxCore</emphasis> comes with support for several different object store implementations. If the object model being used is SINGLE, then no lock store is required for maintaining locks, since the information about the object is not exported from it. However, if the MULTIPLE model is used, then different run-time environments (processes, Java virtual machines) may need to share concurrency control information. The implementation type of the lock store to use can be specified for all objects within a given execution environment using the <literal>com.arjuna.ats.txoj.lockstore.lockStoreType</literal> property variable. Currently this can have one of the following values:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>BasicLockStore</term>
+ <listitem><para>This is an in-memory implementation which does not, by default, allow sharing of stored information between execution environments. The application programmer is responsible for sharing the store information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>BasicPersistentLockStore</term>
+ <listitem><para>This is the default implementation, and stores locking information within the local file system. Therefore execution environments that share the same file store can share concurrency control information. The root of the file system into which locking information is written is the <filename>LockStore</filename> directory within the <emphasis>TxCore</emphasis> installation directory. This can be overridden at runtime by setting the <literal>com.arjuna.ats.txoj.lockstore.lockStoreDir</literal> property variable accordingly, or placing the location within the <literal>CLASSPATH</literal>:</para>
+
+ <para><command>java -D com.arjuna.ats.txoj.lockstore.lockStoreDir=/var/tmp/LockStore myprogram</command></para>
+
+ <para>or</para>
+
+ <para><command>java –classpath $CLASSPATH;/var/tmp/LockStore myprogram</command></para>
+
+ <para>If neither of these approaches is taken, then the default location will be at the same level as the <filename>etc</filename> directory of the installation.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+
+ </section>
+
+ <section>
+ <title>LockManager</title>
+
+ <para>The concurrency controller is implemented by the class <classname>LockManager</classname> which provides sensible default behaviour while allowing the programmer to override it if deemed necessary by the particular semantics of the class being programmed. The primary programmer interface to the concurrency controller is via the setlock operation. By default, the <emphasis>TxCore</emphasis> runtime system enforces strict two-phase locking following a multiple reader, single writer policy on a per object basis. Lock acquisition is 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 normally 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>
+
+ <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, if a request to set a write lock is granted, then <classname>LockManager</classname> invokes modified directly assuming 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 <command>activate</command> to be invoked.</para>
+
+ <para>Therefore, <classname>LockManager</classname> is directly responsible for activating/de-activating persistent objects, and registering <classname>Resources</classname> for managing concurrency control. By driving the <classname>StateManager</classname> class, it is also responsible for registering <classname>Resources</classname> for persistent/recoverable state manipulation and object recovery. The application programmer simply sets appropriate locks, starts and ends transactions, and extends the <command>save_state</command> and <command>restore_state</command> methods of <classname>StateManager</classname>.</para>
+
+ <programlisting>public class LockResult
+{
+public static final int GRANTED;
+public static final int REFUSED;
+public static final int RELEASED;
+};
+
+public class ConflictType
+{
+public static final int CONFLICT;
+public static final int COMPATIBLE;
+public static final int PRESENT;
+};
+
+public abstract class LockManager extends StateManager
+{
+public static final int defaultTimeout;
+public static final int defaultRetry;
+public static final int waitTotalTimeout;
+
+public synchronized int setlock (Lock l);
+public synchronized int setlock (Lock l, int retry);
+public synchronized int setlock (Lock l, int retry, int sleepTime);
+public synchronized boolean releaselock (Uid uid);
+
+/* abstract methods inherited from StateManager */
+
+public boolean restore_state (InputObjectState os, int ObjectType);
+public boolean save_state (OutputObjectState os, int ObjectType);
+public String type ();
+
+protected LockManager ();
+protected LockManager (int ObjectType, ObjectName attr);
+protected LockManager (Uid storeUid);
+protected LockManager (Uid storeUid, int ObjectType, ObjectName attr);
+. . .
+};</programlisting>
+
+ <para>The <command>setlock</command> operation must be parameterised with the type of lock required (<literal>READ</literal> / <literal>WRITE</literal>), and the number of retries to acquire the lock before giving up. If a lock conflict occurs, one of the following scenarios will take place:</para>
+
+ <para>
+ If the retry value is equal to <literal>LockManager.waitTotalTimeout</literal>, then the thread which called <command>setlock</command> will be blocked until the lock is released, or the total timeout specified has elapsed, and in which <literal>REFUSED</literal> will be returned.
+ </para>
+
+ <para>If the lock cannot be obtained initially then <classname>LockManager</classname> will try for the specified number of retries, waiting for the specified timeout value between each failed attempt. The default is 100 attempts, each attempt being separated by a 0.25 seconds delay; the time between retries is specified in micro-seconds.</para>
+
+ <para>If a lock conflict occurs the current implementation simply times out lock requests, thereby preventing deadlocks, rather than providing a full deadlock detection scheme. If the requested lock is obtained, the setlock operation will return the value <literal>GRANTED</literal>, otherwise the value <literal>REFUSED</literal> is returned. It is the responsibility of the programmer to ensure that the remainder of the code for an operation is only executed if a lock request is granted. Below are examples of the use of the <command>setlock</command> operation.</para>
+
+ <programlisting>res = setlock(new Lock(WRITE), 10);
+ // Will attempt to set a
+ // write lock 11 times (10
+ // retries) on the object
+ // before giving up.
+
+res = setlock(new Lock(READ), 0);
+ // Will attempt to set a read
+ // lock 1 time (no retries) on
+ // the object before giving up.
+
+res = setlock(new Lock(WRITE);
+ // Will attempt to set a write
+ // lock 101 times (default of
+ // 100 retries) on the object
+ // before giving up.</programlisting>
+
+ <para>The concurrency control mechanism is integrated into the atomic action mechanism, thus ensuring that as locks are granted on an object appropriate information is registered with the currently running atomic action to ensure that the locks are released at the correct time. This frees the programmer from the burden of explicitly freeing any acquired locks if they were acquired within atomic actions. However, if locks are acquired on an object <emphasis>outside</emphasis> of the scope of an atomic action, it is the programmer's responsibility to release the locks when required, using the corresponding <command>releaselock</command> operation.</para>
+
+ </section>
+
+ <section>
+ <title>Locking policy</title>
+
+ <para>Unlike many other systems, locks in <emphasis>TxCore</emphasis> are not special system types. Instead they are simply instances of other <emphasis>TxCore</emphasis> objects (the class <classname>Lock</classname> which is also derived from <classname>StateManager</classname> so that locks may be made persistent if required and can also be named in a simple fashion). Furthermore, <classname>LockManager</classname> deliberately has no knowledge of the semantics of the actual policy by which lock requests are granted. Such information is maintained by the actual <classname>Lock</classname> class instances which provide operations (the <literal>conflictsWith</literal> operation) by which <classname>LockManager</classname> can determine if two locks conflict or not. This separation is important in that it allows the programmer to derive new lock types from the basic <classname>Lock</classname> class and by providing appropriate definitions of the confli!
ct operations enhanced levels of concurrency may be possible.</para>
+
+ <programlisting>public class LockMode
+{
+ public static final int READ;
+ public static final int WRITE;
+};
+
+public class LockStatus
+{
+ public static final int LOCKFREE;
+ public static final int LOCKHELD;
+ public static final int LOCKRETAINED;
+};
+
+public class Lock extends StateManager
+{
+ public Lock (int lockMode);
+
+ public boolean conflictsWith (Lock otherLock);
+ public boolean modifiesObject ();
+
+ public boolean restore_state (InputObjectState os, int ObjectType);
+ public boolean save_state (OutputObjectState os, int ObjectType);
+ public String type ();
+ . . .
+};</programlisting>
+
+ <para>The <classname>Lock</classname> class provides a <command>modifiesObject</command> operation which <classname>LockManager</classname> uses to determine if granting this locking request requires a call on modified. This operation is provided so that locking modes other than simple read and write can be supported. The supplied <classname>Lock</classname> class supports the traditional multiple reader/single writer policy.</para>
+
+ </section>
+
+ <section>
+ <title>Object construction and destruction</title>
+
+ <para>Recall that <emphasis>TxCore</emphasis> objects can be recoverable; recoverable and persistent; or neither. Additionally each object possesses a unique internal name. These attributes can only be set when that object is constructed. Thus <classname>LockManager</classname> provides two protected constructors for use by derived classes, each of which fulfils a distinct purpose:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><command>LockManager ()</command></term>
+ <listitem><para>This constructor allows the creation of new objects, that is, no prior state is assumed to exist.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>LockManager (int ObjectType, ObjectName attr)</command></term>
+ <listitem><para>As above, this constructor allows the creation of new objects, that is, no prior state is assumed to exist. The <literal>ObjectType</literal> parameter determines whether an object is simply recoverable (indicated by <literal>RECOVERABLE</literal>); recoverable and persistent (indicated by <literal>ANDPERSISTENT</literal>) or neither (<literal>NEITHER</literal>). If an object is marked as being persistent then the state of the object will be stored in one of the object stores. The shared parameter only has meaning if it is <literal>RECOVERABLE</literal>; if <literal>attr</literal> is not null and the object model is <literal>SINGLE</literal> (the default behaviour) then the recoverable state of the object is maintained within the object itself (i.e., it has no external representation), otherwise an in-memory (volatile) object store is used to store the state of the object between atomic actions. </para>
+
+ <para>Constructors for new persistent objects should make use of atomic actions within themselves. This will ensure that the state of the object is automatically written to the object store either when the action in the constructor commits or, if an enclosing action exists, when the appropriate top-level action commits. Later examples in this chapter illustrate this point further.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>LockManager(Uid objUid)</command></term>
+ <listitem><para>This constructor allows access to an existing persistent object, whose internal name is given by the <literal>objUid</literal> parameter. Objects constructed using this operation will normally have their prior state (identified by <literal>objUid</literal>) loaded from an object store automatically by the system.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>LockManager(Uid objUid, ObjectName attr)</command></term>
+ <listitem><para>As above, this constructor allows access to an existing persistent object, whose internal name is given by the <literal>objUid</literal> parameter. Objects constructed using this operation will normally have their prior state (identified by <literal>objUid</literal>) loaded from an object store automatically by the system. If the attr parameter is not null, and the object model is <literal>SINGLE</literal> (the default behaviour), then the object will not be reactivated at the start of each top-level transaction.</para>
+
+ <para>The destructor of a programmer-defined class must invoke the inherited operation terminate to inform the state management mechanism that the object is about to be destroyed otherwise unpredictable results may occur.</para>
+
+ <para>Because <classname>LockManager</classname> inherits from <classname>StateManager</classname>, it will pass any supplied <classname>ObjectName</classname> instance to the <classname>StateManager</classname> class. As such, it is possible to set the <classname>StateManager</classname> object model as described earlier.</para></listitem>
+ </varlistentry>
+
+
+
+
+ </variablelist>
+
+ </section>
+
+
+ </section>
+</chapter>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_02.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_03.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_03.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_03.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,247 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+ <title>General Transaction Issues</title>
+
+ <section>
+
+ <title>Advanced transaction issues with TxCore</title>
+
+ <para>Atomic actions (transactions) can be used by both application programmers and class developers. Thus entire operations (or parts of operations) can be made atomic as required by the semantics of a particular operation. This chapter will describe some of the more subtle issues involved with using transactions in general and <emphasis>TxCore</emphasis> in particular.</para>
+
+ <section>
+ <title>Checking transactions</title>
+
+ <para>In a multi-threaded application, multiple threads may be associated with a transaction during its lifetime, i.e., the thread’s share the context. In addition, it is possible that if one thread terminates a transaction other threads may still be active within it. In a distributed environment, it can be difficult to guarantee that all threads have finished with a transaction when it is terminated. By default, <emphasis>TxCore</emphasis> will issue a warning if a thread terminates a transaction when other threads are still active within it; however, it will allow the transaction termination to continue. Other solutions to this problem are possible, e.g., blocking the thread which is terminating the transaction until all other threads have disassociated themselves from the transaction context. Therefore, <emphasis>TxCore</emphasis> provides the <classname>com.arjuna.ats.arjuna.coordinator.CheckedAction</classname> class, which allows the thread/transaction t!
ermination policy to be overridden. Each transaction has an instance of this class associated with it, and application programmers can provide their own implementations on a per transaction basis.</para>
+
+ <programlisting>public class CheckedAction
+{
+public CheckedAction ();
+
+public synchronized void check (boolean isCommit, Uid actUid,
+BasicList list);
+};</programlisting>
+
+ <para>When a thread attempts to terminate the transaction and there are active threads within it, the system will invoke the check method on the transaction’s <classname>CheckedAction</classname> object. The parameters to the check method are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>isCommit</term>
+ <listitem><para>Indicates whether the transaction is in the process of committing or rolling back.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>actUid</term>
+ <listitem><para>The transaction identifier.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>list</term>
+ <listitem><para>a list of all of the threads currently marked as active within this transaction.</para></listitem>
+ </varlistentry>
+
+
+ </variablelist>
+
+ <para>When check returns, the transaction termination will continue. Obviously the state of the transaction at this point may be different from that when check was called, e.g., the transaction may subsequently have been committed.</para>
+
+ </section>
+
+ <section>
+ <title>Statistics gathering</title>
+
+ <para>By default, the JBossTS does not maintain any history information about transactions. However, by setting the <literal>com.arjuna.ats.arjuna.coordinator.enableStatistics</literal> property variable to YES, the transaction service will maintain information about the number of transactions created, and their outcomes. This information can be obtained during the execution of a transactional application via the <classname>com.arjuna.TxCore.Atomic.TxStats</classname> class:</para>
+
+ <programlisting>public class TxStats
+{
+
+/**
+* Returns the number of transactions (top-level and nested)
+* created so far.
+*/
+
+public static int numberOfTransactions ();
+
+/**
+* Returns the number of nested (sub) transactions created so far.
+*/
+
+public static int numberOfNestedTransactions ();
+
+/**
+* Returns the number of transactions which have terminated with
+* heuristic outcomes.
+*/
+
+public static int numberOfHeuristics ();
+
+/**
+* Returns the number of committed transactions.
+*/
+
+public static int numberOfCommittedTransactions ();
+
+/**
+* Returns the number of transactions which have rolled back.
+*/
+
+public static int numberOfAbortedTransactions ();
+
+}</programlisting>
+
+
+ </section>
+
+ <section>
+ <title>Last resource commit optimisation</title>
+
+ <para>In some cases it may be necessary to enlist participants that aren’t two-phase commit aware into a two-phase commit transaction. If there is only a single resource then there is no need for two-phase commit. However, what if there are multiple resources in the transaction? In this case, the Last Resource Commit optimization (LRCO) comes into play. It is possible for a single resource that is one-phase aware (i.e., can only commit or roll back, with no prepare), to be enlisted in a transaction with two-phase commit aware resources. The coordinator treats the one-phase aware resource slightly differently, in that it executes the prepare phase on all other resource first, and if it then intends to commit the transaction it passes control to the one-phase aware resource. If it commits, then the coordinator logs the decision to commit and attempts to commit the other resources as well.</para>
+
+ <para>In order to utilise the LRCO, your participant must implement the <classname>com.arjuna.ats.arjuna.coordinator.OnePhase</classname> interface and be registered with the transaction through the <command>BasicAction</command>.add operation; since this operation expects instances of <classname>AbstractRecord</classname>, you must create an instance <classname>com.arjuna.ats.arjuna.LastResourceRecord</classname> and give your participant as the constructor parameter, as shown below:</para>
+
+ <programlisting>try
+ {
+ boolean success = false;
+ AtomicAction A = new AtomicAction();
+ OnePhase opRes = new OnePhase(); // used OnePhase interface
+
+ System.err.println("Starting top-level action.");
+
+ A.begin();
+ A.add(new LastResourceRecord(opRes));
+ A.add(new ShutdownRecord(ShutdownRecord.FAIL_IN_PREPARE));
+
+ A.commit();</programlisting>
+
+ </section>
+
+ <section>
+ <title>Nested transactions</title>
+
+ <para>There are no special constructs for nesting of transactions: if an action is begun while another action is running then it is automatically nested. This allows for a modular structure to applications, whereby objects can be implemented using atomic actions within their operations without the application programmer having to worry about the applications which use them, i.e., whether or not the applications will use atomic actions as well. Thus, in some applications actions may be top-level, whereas in others they may be nested. Objects written in this way can then be shared between application programmers, and <emphasis>TxCore</emphasis> will guarantee their consistency.</para>
+
+ <para>If a nested action is aborted then all of its work will be undone, although strict two-phase locking means that any locks it may have obtained will be retained until the top-level action commits or aborts. If a nested action commits then the work it has performed will only be committed by the system if the top-level action commits; if the top-level action aborts then all of the work will be undone.</para>
+
+ <para>The committing or aborting of a nested action does not automatically affect the outcome of the action within which it is nested. This is application dependant, and allows a programmer to structure atomic actions to contain faults, undo work, etc.</para>
+ </section>
+
+ <section>
+ <title>Asynchronously committing a transaction</title>
+
+ <para>By default, JBossTS executes the commit protocol of a top-level transaction in a synchronous manner, i.e., all registered resources will be told to prepare in order by a single thread, and then they will be told to commit or rollback. This has several possible disadvantages:</para>
+
+ <itemizedlist>
+ <listitem><para>In the case of many registered resources, the prepare operating can logically be invoked in parallel on each resource. The disadvantage is that if an “early” resource in the list of registered resource forces a rollback during prepare, possibly many prepare operations will have been made needlessly.</para></listitem>
+ <listitem><para>In the case where heuristic reporting is not required by the application, the second phase of the commit protocol can be done asynchronously, since its success or failure is not important.</para></listitem>
+ </itemizedlist>
+
+ <para>Therefore, <emphasis>JBossTS</emphasis> provides runtime options to enable possible threading optimizations. By setting the <literal>com.arjuna.ats.arjuna.coordinator.asyncPrepare</literal> environment variable to <literal>YES</literal>, during the prepare phase a separate thread will be created for each registered participant within the transaction. By setting <literal>com.arjuna.ats.arjuna.coordinator.asyncCommit</literal> to <literal>YES</literal>, a separate thread will be created to complete the second phase of the transaction if knowledge about heuristics outcomes is not required.</para>
+
+
+ </section>
+
+ <section>
+ <title>Independent top-level transactions</title>
+
+ <para>In addition to normal top-level and nested atomic actions <emphasis>TxCore</emphasis> also supports independent top-level actions, which can be used to relax strict serialisability in a controlled manner. An independent top-level action can be executed from anywhere within another atomic action and behaves exactly like a normal top-level action, that is, its results are made permanent when it commits and will not be undone if any of the actions within which it was originally nested abort.</para>
+
+ <mediaobject id="figure_5">
+ <imageobject>
+ <imagedata align="center" fileref="images/image5.png" />
+ </imageobject>
+ <caption> Independent Top-Level Action</caption>
+ </mediaobject>
+
+ <para><xref linkend="figure_5"/> shows a typical nesting of atomic actions, where action B is nested within action A. Although atomic action C is logically nested within action B (it had its Begin operation invoked while B was active) because it is an independent top-level action, it will commit or abort independently of the other actions within the structure. Because of the nature of independent top-level actions they should be used with caution and only in situations where their use has been carefully examined.</para>
+
+ <para>Top-level actions can be used within an application by declaring and using instances of the class <classname>TopLevelTransaction</classname>. They are used in exactly the same way as other transactions.</para>
+
+ </section>
+
+ <section>
+ <title>Transactions within save_state and restore_state</title>
+
+ <para>Caution must be exercised when writing the <command>save_state</command> and <command>restore_state</command> operations to ensure that no atomic actions are started (either explicitly in the operation or implicitly through use of some other operation). This restriction arises due to the fact that <emphasis>TxCore</emphasis> may invoke <command>restore_state</command> as part of its commit processing resulting in the attempt to execute an atomic action during the commit or abort phase of another action. This might violate the atomicity properties of the action being committed (aborted) and is thus discouraged.</para>
+
+ </section>
+
+ <section>
+ <title>Example</title>
+
+ <para>If we consider the Array example given previously, the set and get operations could be implemented as shown below.</para>
+
+ <note><para>This is a simplification of the code, ignoring error conditions and exceptions.</para></note>
+
+ <programlisting>public boolean set (int index, int value)
+{
+ boolean result = false;
+ AtomicAction A = new AtomicAction();
+
+ A.begin();
+
+ // We need to set a WRITE lock as we want to modify the state.
+
+ if (setlock(new Lock(LockMode.WRITE), 0) == LockResult.GRANTED)
+ {
+ elements[index] = value;
+ if ((value > 0) &&(index > highestIndex))
+ highestIndex = index;
+ A.commit(true);
+ result = true;
+ }
+ else
+ A.rollback();
+
+ return result;
+}
+
+public int get (int index) // assume -1 means error
+{
+ AtomicAction A = new AtomicAction();
+
+ A.begin();
+
+ // We only need a READ lock as the state is unchanged.
+
+ if (setlock(new Lock(LockMode.READ), 0) == LockResult.GRANTED)
+ {
+ A.commit(true);
+
+ return elements[index];
+ }
+ else
+ A.rollback();
+
+ return -1;
+}</programlisting>
+
+ </section>
+
+ <section>
+ <title>Garbage collecting objects</title>
+
+ <para>Java objects are deleted when the garbage collector determines that they are no longer required. Deleting an object that is currently under the control of a transaction must be approached with caution since if the object is being manipulated within a transaction its fate is effectively determined by the transaction. Therefore, regardless of the references to a transactional object maintained by an application, <emphasis>TxCore</emphasis> will always retain its own references to ensure that the object is not garbage collected until after any transaction has terminated.</para>
+
+ </section>
+
+ <section>
+ <title>Transaction timeouts</title>
+
+ <para>By default transactions live until they are terminated by the application that created them or a failure occurs. However, it is possible to set a timeout (in seconds) on a per transaction basis such that if the transaction has not terminated before the timeout expires it will be automatically rolled back.</para>
+
+ <para>In <emphasis>TxCore</emphasis>, the timeout value is provided as a parameter to the <classname>AtomicAction</classname> constructor. If a value of <literal>AtomicAction.NO_TIMEOUT</literal> is provided (the default) then the transaction will not be automatically timed out. Any other positive value is assumed to the timeout for the transaction (in seconds). A value of zero is taken to be a global default timeout, which can be provided by the property <literal>com.arjuna.ats.arjuna.coordinator.defaultTimeout</literal>. Unless changed the default value is 60 seconds.</para>
+
+ <para>When a top-level transaction is created with a non-zero timeout, it is subject to being rolled back if it has not completed within the specified number of seconds. <emphasis>JBossTS</emphasis> uses a separate reaper thread which monitors all locally created transactions, and forces them to roll back if their timeouts elapse. To prevent this thread from consuming application time, it only runs periodically. The default checking period is 120000 milliseconds, but can be overridden by setting the <literal>com.arjuna.ats.arjuna.coordinator.txReaperTimeout</literal> property variable to another valid value, in microseconds. Alternatively, if the <literal>com.arjuna.ats.arjuna.coordinator.txReaperMode</literal> is set to <literal>DYNAMIC</literal>, the transaction reaper will wake whenever a transaction times out. This has the advantage of terminating transactions early, but may suffer from continually rescheduling the reaper thread.</para>
+
+ <para>If a value of 0 is specified for the timeout of a top-level transaction (or no timeout is specified), then <emphasis>JBossTS</emphasis> will not impose any timeout on the transaction, i.e., it will be allowed to run indefinitely. This default timeout can be overridden by setting the <literal>com.arjuna.ats.arjuna.coordinator.defaultTimeout</literal> property variable when using <emphasis>ArjunaCore</emphasis> or <emphasis>ArjunaJTS</emphasis>, or <literal>com.arjuna.ats.jts.defaultTimeout</literal> if using <emphasis>ArjunaJTS</emphasis>, to the required timeout value in seconds.</para>
+
+
+ </section>
+
+
+ </section>
+
+
+</chapter>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_03.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_04.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_04.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_04.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,92 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+ <title>Hints and tips</title>
+
+ <section>
+ <title>General</title>
+
+ <section>
+ <title>Using transactions in constructors</title>
+
+ <para>Examples throughout this manual have used 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. Recall that 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, then the newly created object is written to the store and becomes available immediately. If however, the constructor transaction commits but is nested because some other transaction started prior to object creation is running, then the state will be written only if all of the parent transactions commit. </para>
+
+ <para>On the other hand, if the constructor does not use transactions then it is possible for inconsistencies in the system to arise. For example, if no transaction is active when the object is created then its state will not be saved to the store until the next time the object is modified under the control of some transaction.</para>
+
+ <para>Consider this simple example:</para>
+
+ <programlisting>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</programlisting>
+
+ <para>Here the two objects are created outside of the control of the top-level action A. <literal>obj1</literal> is a new object; <literal>obj2</literal> an old existing object. When the remember operation of <literal>obj2</literal> is invoked the object will be activated and the Uid of <literal>obj1</literal> remembered. Since this action commits the persistent state of <literal>obj2</literal> could now contain the Uid of <literal>obj1</literal>. However, the state of <literal>obj1</literal> 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 some action later in the application it will never be saved. If, however, the constructor had used an atomic action the state of <literal>obj1</literal> would have automatically been saved at the time it was constructed and this inconsistency could not arise.</para>
+ </section>
+
+ <section>
+ <title>More on save_state and restore_state</title>
+
+ <para><emphasis>TxCore</emphasis> may invoke the user-defined <command>save_state</command> operation of an object effectively at any time during the lifetime of an object including during the execution of the body of the object’s constructor (particularly if it uses atomic actions). It is important, therefore, that all of the variables saved by save_state are correctly initialised.</para>
+
+ <para>Caution must be also exercised when writing the <command>save_state</command> and <command>restore_state</command> operations to ensure that no transactions are started (either explicitly in the operation or implicitly through use of some other operation). This restriction arises due to the fact that <emphasis>TxCore</emphasis> may invoke <command>restore_state</command> as part of its commit processing resulting 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 (aborted) and is thus discouraged.</para>
+
+ <para>In order to support crash recovery for persistent objects it is necessary for all <literal>save_state</literal> and <literal>restore_state</literal> methods of user objects to call <command>super.save_state</command> and <command>super.restore_state</command>.</para>
+
+ </section>
+
+ <section>
+ <title>Packing Objects</title>
+
+ <para>All of the basic types of Java (int, long, etc.) can be saved and restored from an <classname>Input/OutputObjectState</classname> instance by using the pack (and unpack) routines provided by <classname>Input/OutputObjectState</classname>. However packing and unpacking objects should be handled differently. This is because packing objects brings in the additional problems of aliasing. That is two different object references may in actual fact point at the same item. For example:</para>
+
+ <programlisting>public class Test
+{
+ public Test (String s);
+ ...
+ private String s1;
+ private String s2;
+};
+
+public Test (String s)
+{
+ s1 = s;
+ s2 = s;
+}</programlisting>
+
+ <para>Here, both s1 and s2 point at the same string and a naive implementation of <command>save_state</command> could end up by copying the string twice. From a <command>save_state</command> perspective this is simply inefficient. However, it makes <command>restore_state</command> incorrect since it would unpack the two strings into different areas of memory destroying the original aliasing information. The current version of TxCore will pack and unpack separate object references.</para>
+
+ </section>
+ </section>
+
+ <section>
+ <title>Direct use of StateManager</title>
+
+ <para>The examples throughout this manual have always derived user classes from <classname>LockManager</classname>. The reasons for this are twofold. Firstly, and most importantly, the serialisability constraints of atomic actions require it, and secondly it reduces the need for programmer intervention. However, if only access to <emphasis>TxCore</emphasis>'s persistence and recovery mechanisms is required, 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 activate, deactivate and modified, since <classname>StateManager</classname>'s constructors are effectively identical to those of <classname>LockManager</classname>.</para>
+
+ <programlisting>boolean activate ()
+boolean activate (String storeRoot)</programlisting>
+
+ <para><command>Activate</command> 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 <command>restore_state</command> is called to build the object in memory. <command>Activate</command> 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>
+
+ <programlisting>boolean deactivate ()
+boolean deactivate (String storeRoot)</programlisting>
+
+ <para>The inverse of activate. First calls <command>save_state</command> 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>
+
+ <programlisting>void modified ()</programlisting>
+
+ <para><emphasis>Must</emphasis> 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 deactivate.</para>
+ </section>
+
+
+</chapter>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_04.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_05.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_05.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_05.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,431 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+ <title>Tools</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>This chapter explains how to start and use the tools framework and what tools are available.</para>
+
+ </section>
+
+ <section>
+ <title>Starting the Transaction Service tools</title>
+
+ <para>The way to start the transaction service tools differs on the operating system being used:</para>
+
+ <formalpara>
+ <title>Windows</title>
+
+ <para>Double click on the ‘Start Tools’ link in the JBoss Transaction Service program group in the start menu.</para>
+ </formalpara>
+
+ <formalpara>
+ <title>Unix</title>
+
+ <para>
+ Start a bash shell and type:
+ </para>
+ </formalpara>
+
+ <programlisting>cd <JBossTS INSTALL DIRECTORY>
+./run-tools.sh</programlisting>
+
+ <para>Once you have done this the tools window will appear. This is the launch area for all of the tools shipped with the <emphasis>JBoss Transaction Service</emphasis>. At the top of the window you will notice a menu bar. This menu bar has four items:</para>
+
+ <formalpara>
+ <title>The <menuchoice><guimenu>File</guimenu></menuchoice> Menu</title>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>Open JMX Browser</term>
+ <listitem><para>This displays the JMX browser window (see ***Using the JMX Browser for more information on how to use the JMX browser).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Open Object Store Browser </term>
+ <listitem><para>This displays the JBossTS Object Store browser window (see ***Using the Object Store Browser for more information on how to use the Object Store browser).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Settings</term>
+ <listitem><para>This option opens the settings dialog which lets you configure the different tools available.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>Exit</term>
+ <listitem><para>This closes the tools window and exits the application, any unsaved/unconfirmed changes will be lost.</para></listitem></varlistentry>
+
+
+ </variablelist>
+
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>The <menuchoice><guimenu>Performance</guimenu></menuchoice> Menu</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>Open</term>
+ <listitem><para>This opens a performance window – see <xref linkend="Performance_Tool"/> for more information on the performance tool.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Close All</term>
+ <listitem><para>this closes all of the currently open performance windows – see <xref linkend="Performance_Tool"/> for more information on the performance tool.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>The <menuchoice><guimenu>Window</guimenu></menuchoice> Menu</title>
+ <para><variablelist>
+ <varlistentry>
+ <term>Cascade Windows</term>
+ <listitem><para>This arranges the windows in a diagonal line to you find a specific window.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>1. XXXXXXX</term>
+ <listitem><para>For each window currently visible an extra menu option will be available here. Selecting this menu option will bring the associated window to the front of the desktop.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>The <menuchoice><guimenu>Help</guimenu></menuchoice> Menu</title>
+ <para><variablelist>
+ <varlistentry>
+ <term>About</term>
+ <listitem><para>This displays the about window containing the product information.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </formalpara>
+
+
+
+ </section>
+
+ <section id="Performance_Tool">
+ <title>Using the Performance Tool</title>
+
+ <para>The performance tool can be used to display performance information about the transaction service. This information is gathered using the Performance JMX bean which means that the transaction service needs to be integrated into an Application Server to give any performance information.</para>
+
+ <para>The performance information is displayed via a multi-series graph. To view this graph simply open a performance window by selecting <menuchoice><guimenu>Performance</guimenu></menuchoice> > <menuchoice><guimenuitem>Open</guimenuitem></menuchoice></para>
+
+ <para>
+ The window now on screen contains a multi-serise graph which can display the following information:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Number of transactions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Number of committed transactions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Number of aborted transactions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Number of nested transactions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Number of heuristics raised.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ To turn these series on and off simply select the menu option from the series menu.
+ </para>
+ <para>
+ When series are turned on they appear in the legend at the bottom of the graph. The colour next to the series name (for example, Transactions Created) is the colour of the line representing that data.
+ </para>
+ <para>
+ The data shown is graphed against time. The Y-axis represents the number of transactions and the X-axis represents time.
+ </para>
+ <para>
+ At any point the sampling of data can be stopped and restarted using the <menuchoice><guimenu>Sampling</guimenu></menuchoice> menu and the data currently visible in the graph can be saved to a Comma Separate Values (CSV) file for importing the data into a spreadsheet application using the <menuchoice><guimenu>Save to .csv</guimenu></menuchoice> menu option from the <menuchoice><guimenu>Data</guimenu></menuchoice> menu.
+ </para>
+ </section>
+ <section id="JMX_Browser">
+ <title>Using the JMX Browser</title>
+ <para>
+ To open the JMX browser window click on the <menuchoice><guimenu>File</guimenu></menuchoice> menu and then click the <menuchoice><guimenu>Open JMX Browser</guimenu></menuchoice> option. The JMX browser window will then be displayed.
+ </para>
+ <para>
+ The window is made up of two main sections:the details panel and the MBean panel. The MBean panel displays the MBeans exposed by the MBean server. These are grouped by domain name. The details panel displays information about the currently selected MBean. To select an MBean just left-click it with the mouse and it will become highlighted. The information displayed in the details panel is as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The total number of MBeans registered on this server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The number of constructors exposed by this MBean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The number of attributes exposed by this MBean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The number of operations exposed by this MBean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The number of notifications exposed by this MBean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A brief description of the MBean.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ There is also a <menuchoice><guimenu>View</guimenu></menuchoice> link which when clicked displays the attributes and operations exposed by this MBean. From there you can view readable attributes, alter writeable attributes and invoke operations.
+ </para>
+ <section id="Using_Attributes_and_Operations">
+ <title>Using Attributes and Operations</title>
+ <para>
+ When the <menuchoice><guimenu>View</guimenu></menuchoice> link is clicked the View JMX Attributes and Operations window is displayed. From here you can view all readable attributes exposed by the selected MBean. You can also alter writeable attributes. If an attribute is read-only then you will not be able to alter an attributes value. To alter an attributes value just double click on the current value and enter the new value. If the <guibutton>...</guibutton> button is enabled then you can click this to view a more suitable editing method. If the attribute type is a JMX object name then clicking this button will display the JMX attributes and operations for that object.
+ </para>
+ <para>
+ At any point you can click the <guibutton>Refresh</guibutton> button to refresh the attribute values. If an exception occurs while retrieving the value of an attribute the exception will be displayed in place of the attributes value.
+ </para>
+ <para>
+ You can also invoke operations upon an MBean. A list of operations exposed by an MBean is displayed below the attributes list. To invoke an operation simply select it from the list and click the <guibutton>Invoke</guibutton> button. If the operation requires parameters a further window will be displayed, from this window you must specify values for each of the parameters required. You specify parameter values in the same way as you specify JMX attribute values. Once you have specified a value for each of the parameters click the <guibutton>Invoke</guibutton> button to perform the invocation.
+ </para>
+ <para>
+ Once the method invocation has completed its return value will be displayed.
+ </para>
+ </section>
+ <section id="Using_the_Object_Store_Browser">
+ <title>Using the Object Store Browser</title>
+ <para>
+ To open the Object Store browser window click on the <menuchoice><guimenu>File</guimenu></menuchoice> menu and then click the <menuchoice><guimenu>Open Object Store Browser</guimenu></menuchoice> option. The Object Store browser window will then be displayed.
+ </para>
+ <para>
+ The object store browser window is split into four sections:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Object Store Roots - this is a pull down of the currently avaliable object store roots. Selecting an option from the list will repopulate the hierachy view with the contents of the selected root.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Object Store Hierarchy – this is a tree which shows the current object store hierarchy. Selecting a node from this tree will display the objects stored in that location.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Objects – this is a list of icons which represent the objects stored in the selected location.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Object Details – this shows information about the currently selected object (only if the object’s type is known to the state viewer repository see Writing an OSV for information on how to write a object state viewers).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="Object_State_Viewers">
+ <title>Object State Viewers (OSV)</title>
+ <para>
+ When an object is selected in the objects pane of the main window the registered Object State Viewer (or OSV) for that object type is invoked. An OSV’s job is to make information available via the user interface to the user to show information about the selected object. Distributed with the standard tools is an OSV for Atomic Actions, the OSV displays information on the Abstract Records in it’s various lists (e.g. heuristic, failed, read-only, etc). It is also possible to write your own OSVs which can be used to display information about object types you have defined. This subject is covered next.
+ </para>
+ <formalpara>
+ <title>Writing an OSV</title>
+ <para>
+ Writing an OSV plugin allows you to extend the capabilities of the Object Store browser to show the state of user defined abstract records. An OSV plug-in is simply a class which implements the interface:
+ </para>
+ </formalpara>
+ <para>
+ <code>com.arjuna.ats.tools.objectstorebrowser.stateviewers.StateViewerInterface</code>
+ </para>
+ <para>
+ It must be packaged in a JAR within the plugins directory. This example shows how to create an OSV plugin for an abstract record subclass which looks as follows:
+ </para>
+<screen>
+public class SimpleRecord extends AbstractRecord
+{
+ private int _value = 0;
+
+ .....
+
+ public void increase()
+ {
+ _value++;
+ }
+
+ public int get()
+ {
+ return _value;
+ }
+
+ public String type()
+ {
+ return “/StateManager/AbstractRecord/SimpleRecord”;
+ }
+
+ public boolean restore_state(InputObjectState os, int i)
+ {
+ boolean returnValue = true;
+
+ try
+ {
+ _value = os.unpackInt();
+ }
+ catch (java.io.IOException e)
+ {
+ returnValue = false;
+ }
+
+ return returnValue;
+ }
+
+ public boolean save_state(OutputObjectState os, int i)
+ {
+ boolean returnValue = true;
+
+ try
+ {
+ os.packInt(_value);
+ }
+ catch (java.io.IOException e)
+ {
+ returnValue = false;
+ }
+
+ return returnValue;
+ }
+}
+</screen>
+ <para>
+ When this abstract record is viewed in the object store browser it would be nice to see the current value. This is easy to do as we can read the state into an instance of our abstract record and call <methodname>getValue()</methodname>. The following is the object store browser plug-in source code:
+ </para>
+<screen>
+public class SimpleRecordOSVPlugin implements StateViewerInterface
+{
+ /**
+ * A uid node of the type this viewer is registered against has been expanded.
+ * @param os
+ * @param type
+ * @param manipulator
+ * @param node
+ * @throws ObjectStoreException
+ */
+ public void uidNodeExpanded(ObjectStore os,
+ String type,
+ ObjectStoreBrowserTreeManipulationInterface
+ manipulator,
+ UidNode node,
+ StatePanel infoPanel)
+ throws ObjectStoreException
+ {
+ // Do nothing
+ }
+
+ /**
+ * An entry has been selected of the type this viewer is registered against.
+ *
+ * @param os
+ * @param type
+ * @param uid
+ * @param entry
+ * @param statePanel
+ * @throws ObjectStoreException
+ */
+ public void entrySelected(ObjectStore os,
+ String type,
+ Uid uid,
+ ObjectStoreViewEntry entry,
+ StatePanel statePanel)
+ throws ObjectStoreException
+ {
+ SimpleRecord rec = new SimpleRecord();
+
+ if ( rec.restore_state( os.read_committed(uid, type), ObjectType.ANDPERSISTENT ) )
+ {
+ statePanel.setData( “Value”, rec.getValue() );
+ }
+ }
+
+ /**
+ * Get the type this state viewer is intended to be registered against.
+ * @return
+ */
+ public String getType()
+ {
+ return “/StateManager/AbstractRecord/SimpleRecord”;
+ }
+}
+</screen>
+ <para>
+ The method <methodname>uidNodeExpanded</methodname> is invoked when a UID (Unique Identification) representing the given type is expanded in the object store hierarchy tree. This is not required by this plugin as this abstract record is not visible in the object store directly it is only viewable via one of the lists in an atomic action. The method <methodname>entrySelected</methodname> is invoked when an entry is selected from the object view which represents an object with the given type. In both methods the StatePanel is used to display information regarding the state of the object. The state panel has the following methods that assist in display this information:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>setInfo(String info)</methodname>: This method can be used to show general information.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>setData(String name, String value)</methodname>: This method is used to put information into the table which is displayed by the object store browser tool.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>enableDetailsButton(DetailsButtonListener listener)</methodname>: This method is used to enable the details button. The listener interface allows a plug-in to be informed when the button is pressed. It is up to the plug-in developer to decide how to display this further information.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ In this example we read the state from the object store and use the value returned by getValue() to put an entry into the state panel table. The getType() method returns the type this plug-in is to be registered against.
+ </para>
+ <para>
+ To add this plug-in to the object store browser it is necessary to package it into a JAR (Java Archive) file with a name that is prefixed with 'osbv-'. The JAR file must contain certain information within the manifest file so that the object store browser knows which classes are plug-ins. All of this can be performed using an <ulink url="http://ant.apache.org">Apache ANT</ulink> script, as follows:
+ </para>
+<screen>
+<jar jarfile="osbv-simplerecord.jar">
+ <fileset dir="build" includes="*.class”/>
+ <manifest>
+ <section name="arjuna-tools-objectstorebrowser">
+ <attribute name="plugin-classname-1" value=" SimpleRecordOSVPlugin "/>
+ </section>
+ </manifest>
+</jar>
+</screen>
+ <para>
+ Once the JAR has been created with the correct information in the manifest file it just needs to be placed in the <emphasis>bin/tools/plugins</emphasis> directory.
+ </para>
+ </section>
+ </section>
+</chapter>
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_05.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_06.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_06.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_06.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,379 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+ <title>Constructing a Transactional objects for Java application</title>
+
+ <section>
+ <title>Application construction</title>
+ <para>
+ There are two distinct phases to the development of a TxCore application:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Developing new classes with certain characteristics (for example, Persistent, Recoverable, Concurrency Controlled).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Developing the application(s) that make use of the new classes of objects.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Although these two phases may be performed in parallel and by a single person, we shall refer to the first step as the job of the class developer and the second as the job of the applications developer. The class developer will be concerned about defining appropriate <code>save_state</code> and <code>restore_state</code> operations for the class, setting appropriate locks in operations, and invoking the appropriate TxCore class constructors. The applications developer will be more concerned with defining the general structure of the application, particularly with regard to the use of atomic actions.
+ </para>
+ <para>
+ This chapter illustrates the points made in previous sections by outlining a simple application: in this case a simple FIFO Queue class for integer values will be developed. The implementation of the Queue will be with a doubly linked list structure, and it will be implemented as a single object. We shall be using this example throughout the rest of this manual to help illustrate the various mechanisms provided by TxCore. While this is an unrealistic example application it enables all of the TxCore modifications to be described without requiring in depth knowledge of the application code.
+ </para>
+ <para>
+ In the rest of this chapter we shall assume that the application is not distributed. If this is not the case, then context information must be propagated either implicitly or explicitly.
+ </para>
+ <formalpara>
+ <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 (enqueue) and to be removed from it (dequeue), and it is also possible to change or inspect the values of elements in the queue. In this example implementation, an array is used to represent the queue. A limit of <code>QUEUE_SIZE</code> elements has been imposed for this example.
+ </para>
+ </formalpara>
+ <para>
+ The Java interface definition of this simple queue class is given below:
+ </para>
+<screen>
+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;
+};
+</screen>
+ <formalpara>
+ <title>Constructors and deconstructors</title>
+ <para>
+ As stated in the previous section, to use an existing persistent object requires the use of a special constructor that is required to take the Uid of the persistent object; the implementation of such a constructor is given below:
+ </para>
+ </formalpara>
+<screen>
+public TransactionalQueue (Uid u)
+{
+ super(u);
+
+ numberOfElements = 0;
+}
+</screen>
+ <para>
+ The constructor that creates a new persistent object is similar:
+ </para>
+<screen>
+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);
+ }
+}
+</screen>
+ <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 <code>TransactionalQueue</code> 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 <code>WRITE</code> 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 queue class is only required to call the terminate operation of <methodname>LockManager</methodname>
+ </para>
+<screen>
+public void finalize ()
+{
+ super.terminate();
+}
+</screen>
+ <formalpara>
+ <title>save_state, resotre_state and type</title>
+ <para>
+ The implementations of save_state and restore_state are relatively simple for this example:
+ </para>
+ </formalpara>
+<screen>
+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;
+ }
+}
+
+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;
+ }
+}
+</screen>
+ <para>
+ Because the Queue class is derived from the <classname>LockManager</classname> class, the operation type should be:
+ </para>
+<screen>
+public String type ()
+{
+ return "/StateManager/LockManager/TransactionalQueue";
+}
+</screen>
+ <formalpara>
+ <title>enqueue/dequeue operations</title>
+ <para>
+ If the operations of the queue class are to be coded as atomic actions, then the enqueue operation could have the structure given below (the dequeue operation would be similarly structured):
+ </para>
+ </formalpara>
+<screen>
+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();
+ }
+}
+</screen>
+ <formalpara>
+ <title>queueSize</title>
+ <para>The implementation of <methodname>queueSize</methodname> is shown below:</para>
+ </formalpara>
+<screen>
+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;
+}
+</screen>
+ <formalpara>
+ <title>inspectValue/setValue operations</title>
+ <para>
+ The implementation of <methodname>inspectValue</methodname> is shown below. <methodname>setValue</methodname> is similar, and not shown.
+ </para>
+ </formalpara>
+<screen>
+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;
+}
+</screen>
+ <formalpara>
+ <title>The client</title>
+ <para>
+ Rather than show all of the code for the client, we shall concentrate on a representative portion. Before invoking operations on the object, the client must obviously first bind to it. In the local case this simply requires the client to create an instance of the object.
+ </para>
+ </formalpara>
+<screen>
+public static void main (String[] args)
+{
+TransactionalQueue myQueue = new TransactionalQueue();
+</screen>
+ <para>
+ Before invoking one of the queue’s operations, the client starts a transaction. The <methodname>queueSize</methodname> operation is shown below:
+ </para>
+<screen>
+AtomicAction A = new AtomicAction();
+int size = 0;
+
+try
+{
+ A.begin(0);
+s
+ 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!”);
+}
+</screen>
+ <formalpara>
+ <title>Comments</title>
+ <para>
+ Since the queue object is persistent, then the state of the object will survive any failures of the node on which it is located. The state of the object that will survive is that produced by the last top-level committed atomic action performed on the object. If it is the intention of an application to perform two enqueue operations atomically, for example, then this can be done by nesting the enqueue operations in another enclosing atomic action. In addition, concurrent operations on such a persistent object will be serialised, thereby preventing inconsistencies in the state of the object. However, since the elements of the queue objects are not individually concurrency controlled, certain combinations of concurrent operation invocations will be executed serially, whereas logically they could be executed concurrently. For example, modifying the states of two different elements in the queue. In the next section we address some of these issues.
+ </para>
+ </formalpara>
+ </section>
+</chapter>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_06.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_07.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_07.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_07.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,235 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+ <title>Configuration options</title>
+
+ <section>
+ <title>Options</title>
+ <para>
+ The following table shows the configuration features, with default values shown in italics. More details about each option can be found in the relevant sections of this document.
+ </para>
+ <table>
+ <title>TxCore configuration options.</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Configuration Name
+ </entry>
+ <entry>
+ Possible Values
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.storeSync
+ </entry>
+ <entry>
+ ON/OFF
+ </entry>
+ <entry>
+ Turns synchronization of the object store on or off. Use with caution.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.storeType
+ </entry>
+ <entry>
+ ShadowStore/ShadowNoFileLockStore/JDBCStore/HashedStore
+ </entry>
+ <entry>
+ Specify the type of object store implementation to use.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.hashedDirectories
+ </entry>
+ <entry>
+ 255/any integer value
+ </entry>
+ <entry>
+ Set the number of directories to hash object states over for the HashedStore object store implementation.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.txoj.lockstore.lockStoreType
+ </entry>
+ <entry>
+ BasicLockStore/BasicPersistentLockStore
+ </entry>
+ <entry>
+ Specify the type of the lock store implementation to use.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.txoj.lockstore.lockStoreDir
+ </entry>
+ <entry>
+ Windows: .\LockStore
+ Unix: ./LockStore
+ </entry>
+ <entry>
+ Specify the location of the lock store.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.objectStoreDir
+ </entry>
+ <entry>
+ Any location the application can write to.
+ </entry>
+ <entry>
+ Specify the location of the object store.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.localOSRoot
+ </entry>
+ <entry>
+ defaultStore
+ </entry>
+ <entry>
+ Specify the name of the object store root.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.actionStore
+ </entry>
+ <entry>
+ ActionStore/HashedActionStore/JDBCActionStore
+ </entry>
+ <entry>
+ The transaction log implementation to use.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.asyncCommit
+ </entry>
+ <entry>
+ YES/NO
+ </entry>
+ <entry>
+ Turns on or off (default) asynchronous commit.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.asyncPrepare
+ </entry>
+ <entry>
+ YES/NO
+ </entry>
+ <entry>
+ Turns on or off (default) asynchronous prepare.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.transactionSync
+ </entry>
+ <entry>
+ ON/OFF
+ </entry>
+ <entry>
+ Turns synchronization of the object store on or off. Use with caution.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.jdbcUserDbAccess
+ </entry>
+ <entry>
+ JDBCAccess class name
+ </entry>
+ <entry>
+ The JDBCAccess implementation to use for user-level object stores.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.objectstore.jdbcTxDbAccess
+ </entry>
+ <entry>
+ JDBCAccess class name
+ </entry>
+ <entry>
+ The JDBCAccess implementation to use for transaction object stores.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.commitOnePhase
+ </entry>
+ <entry>
+ YES/NO
+ </entry>
+ <entry>
+ Enable or disable the one-phase commit optimization.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.readonlyOptimisation
+ </entry>
+ <entry>
+ YES/NO
+ </entry>
+ <entry>
+ Enable or disable read-only optimization for the second phase abort.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.enableStatistics
+ </entry>
+ <entry>
+ YES/NO
+ </entry>
+ <entry>
+ Start/stop collecting transaction statistic information.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.startDisabled
+ </entry>
+ <entry>
+ YES/NO
+ </entry>
+ <entry>
+ Start with the transaction system enabled or disabled. Toggle via the com.arjuna.ats.arjuna.coordinator.TxControl class.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ com.arjuna.ats.arjuna.coordinator.defaultTimeout
+ </entry>
+ <entry>
+ Integer
+ </entry>
+ <entry>
+ Timeout in milliseconds
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+
+
+ </table>
+ </section>
+</chapter>
\ No newline at end of file
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Chapter_07.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.ent
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.ent (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.ent 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,3 @@
+<!ENTITY HOLDER "Red Hat, Inc">
+<!ENTITY YEAR "2008">
+<!ENTITY VERSION "4.3.0.CP01">
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.ent
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.xml (rev 0)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.xml 2008-06-05 22:42:10 UTC (rev 74206)
@@ -0,0 +1,19 @@
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<book>
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!-- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Chapter_02.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Chapter_03.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Chapter_04.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Chapter_05.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Chapter_06.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Chapter_07.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Appendix_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Appendix_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!-- <xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+</book>
+
Property changes on: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/JBoss_TS_Programmers_Guide.xml
___________________________________________________________________
Name: svn:executable
+ *
More information about the jboss-cvs-commits
mailing list