[jboss-svn-commits] JBL Code SVN: r36903 - in labs/jbosstm/trunk: ArjunaJTA/docs/quick_start/en-US and 6 other directories.

jboss-svn-commits at lists.jboss.org jboss-svn-commits at lists.jboss.org
Wed Apr 13 09:34:34 EDT 2011 

Author: tomjenkinson
Date: 2011-04-13 09:34:33 -0400 (Wed, 13 Apr 2011)
New Revision: 36903

Added:
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/About_This_Guide.xml
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Author_Group.xml
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Book_Info.xml
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.ent
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Preface.xml
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Quick_Start_to_JTS_OTS.xml
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Revision_History.xml
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/initORB.java
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/interposition.gif
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/shutdownORB.java
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/images/
   labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/publican.cfg
Removed:
   labs/jbosstm/trunk/ArjunaJTS/docs/user_guide/
Modified:
   labs/jbosstm/trunk/ArjunaCore/docs/arjunacore_failure_recovery_guide/en-US/About_This_Guide.xml
   labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Author_Group.xml
   labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Quick_Start_to_JTA.xml
   labs/jbosstm/trunk/ArjunaJTS/build.xml
   labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/Author_Group.xml
Log:
JBTM-820 added the quick start as a docbook

Modified: labs/jbosstm/trunk/ArjunaCore/docs/arjunacore_failure_recovery_guide/en-US/About_This_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/arjunacore_failure_recovery_guide/en-US/About_This_Guide.xml	2011-04-13 13:08:25 UTC (rev 36902)
+++ labs/jbosstm/trunk/ArjunaCore/docs/arjunacore_failure_recovery_guide/en-US/About_This_Guide.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -1,13 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Failure_Recover_Guide.ent">
-<!ENTITY PRODUCT "JBoss Transactions">
-<!ENTITY BOOKID "ArjunaCore_Failure_Recover_Guide">
-<!ENTITY VERSION "4.15">
-<!ENTITY YEAR "2011">
-<!ENTITY HOLDER "JBoss.org">
-<!ENTITY APPSERVER "JBoss Application Server">
-<!-- <!ENTITY APPSERVER "Enterprise Application Platform Server"> -->]>
+%BOOK_ENTITIES;
+]>
 <chapter>
   <title>About This Guide</title>
   <para>

Modified: labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Author_Group.xml	2011-04-13 13:08:25 UTC (rev 36902)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Author_Group.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -36,14 +36,6 @@
     </affiliation>
     <email>kconnor at redhat.com</email>
   </author>
-  <editor>
-    <firstname>Misty</firstname>
-    <surname>Stanley-Jones</surname>
-    <affiliation>
-      <orgname>Red Hat</orgname>
-    </affiliation>
-    <email>misty at redhat.com</email>
-  </editor>
 
 </authorgroup>
 

Modified: labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Quick_Start_to_JTA.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Quick_Start_to_JTA.xml	2011-04-13 13:08:25 UTC (rev 36902)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/Quick_Start_to_JTA.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -29,11 +29,11 @@
   </section>
   <section>
     <title>Setting properties</title>
-    <para>JBossJTA has also been designed to be configurable at runtime through the use of various property attributes. These attributes can be
+    <para>&PRODUCT; has also been designed to be configurable at runtime through the use of various property attributes. These attributes can be
       provided at runtime on command line or specified through a properties file.</para>
     <section>
       <title>Specifying the object store location</title>
-      <para>JBossJTA requires an object store in order to persistently record the outcomes of transactions in the event of failures. In order to
+      <para>&PRODUCT; requires an object store in order to persistently record the outcomes of transactions in the event of failures. In order to
         specify the location of the object store it is necessary to specify the location when the application is executed; for example:</para>
       <para>
         <programlisting role="JAVA" language="Java">java –DObjectStoreEnvironmentBean.objectStoreDir=/var/tmp/ObjectStore myprogram</programlisting>
@@ -48,12 +48,12 @@
     <title>Demarcating Transactions</title>
     <para>The Java Transaction API consists of three elements: a high-level application transaction demarcation interface, a high-level transaction
       manager interface intended for application server, and a standard Java mapping of the X/Open XA protocol intended for transactional resource
-      manager. All of the JTA classes and interfaces occur within the javax.transaction package, and the corresponding JBossJTA implementations within
+      manager. All of the JTA classes and interfaces occur within the javax.transaction package, and the corresponding &PRODUCT; implementations within
       the com.arjuna.ats.jta package.</para>
     <section>
       <title>UserTransaction</title>
       <para>The UserTransaction interface provides applications with the ability to control transaction boundaries. </para>
-      <para>In JBossJTA, UserTransaction can be obtained from the static com.arjuna.ats.jta.UserTransaction.userTransaction() method. When obtained
+      <para>In &PRODUCT;, UserTransaction can be obtained from the static com.arjuna.ats.jta.UserTransaction.userTransaction() method. When obtained
         the UserTransaction object can be used to control transactions</para>
       <example>
         <title>User Transaction Example</title>
@@ -65,7 +65,7 @@
       <title>TransactionManager</title>
       <para>The TransactionManager interface allows the application server to control transaction boundaries on behalf of the application being
         managed.</para>
-      <para>In JBossJTA, transaction manager implementations can be obtained from the static
+      <para>In &PRODUCT;, transaction manager implementations can be obtained from the static
         com.arjuna.ats.jta.TransactionManager.transactionManager() method</para>
     </section>
     <section>
@@ -129,14 +129,14 @@
       (There is a single type of transactional driver through which any JDBC driver can be driven. This driver is
       com.arjuna.ats.jdbc.TransactionalDriver, which implements the java.sql.Driver interface.)</para>
     <para>Once the connection has been established (for example, using the java.sql.DriverManager.getConnection method), all operations on the
-      connection will be monitored by JBossJTA. Once created, the driver and any connection can be used in the same way as any other JDBC driver or
+      connection will be monitored by &PRODUCT;. Once created, the driver and any connection can be used in the same way as any other JDBC driver or
       connection.</para>
-    <para>JBossJTA connections can be used within multiple different transactions simultaneously, i.e., different threads, with different notions of
-      the current transaction, may use the same JDBC connection. JBossJTA does connection pooling for each transaction within the JDBC connection. So,
+    <para>&PRODUCT; connections can be used within multiple different transactions simultaneously, i.e., different threads, with different notions of
+      the current transaction, may use the same JDBC connection. &PRODUCT; does connection pooling for each transaction within the JDBC connection. So,
       although multiple threads may use the same instance of the JDBC connection, internally this may be using a different connection instance per
       transaction. With the exception of close, all operations performed on the connection at the application level will only be performed on this
       transaction-specific connection.</para>
-    <para>JBossJTA will automatically register the JDBC driver connection with the transaction via an appropriate resource. When the transaction
+    <para>&PRODUCT; will automatically register the JDBC driver connection with the transaction via an appropriate resource. When the transaction
       terminates, this resource will be responsible for either committing or rolling back any changes made to the underlying database via appropriate
       calls on the JDBC driver.</para>
   </section>

Modified: labs/jbosstm/trunk/ArjunaJTS/build.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/build.xml	2011-04-13 13:08:25 UTC (rev 36902)
+++ labs/jbosstm/trunk/ArjunaJTS/build.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -107,10 +107,14 @@
             <fileset dir="orbportability/docs/programmers_guide" includes="*.pdf"/>
         </copy>
 
-        <copy todir="${build.dir}/install/${dest.dir}/user_guide/" overwrite="true">
+        <copy todir="${build.dir}/install/${dest.dir}/user_guide/" overwrite="true" flatten="true">
             <fileset dir="../docs/" includes="**/*.pdf"/>
         </copy>
 
+        <copy todir="${build.dir}/install/${dest.dir}/user_guide/ArjunaCore" overwrite="true" flatten="true">
+            <fileset dir="../ArjunaCore/docs/" includes="**/*.pdf"/>
+        </copy>
+
     </target>
 
     <target name="install.scripts">

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/About_This_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/About_This_Guide.xml	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/About_This_Guide.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,26 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Quick_Start_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+  <title>About This Guide</title>
+  <para>
+    The Stand-alone Quick Start Guide contains information on how to use &PRODUCT;.
+  </para>
+  <section>
+    <title>Audience</title>
+    <para>
+      This guide is most relevant to engineers who are responsible for administering &PRODUCT;
+      installations. It is intended for
+      those who are familiar with transactions in general and the OTS/JTS and JTA in particular.
+    </para>
+  </section>
+  <section>
+    <title>Prerequisites</title>
+    <para>
+      Familiarity with the JTA, OTS, transactions and ORBs.
+    </para>
+  </section>
+</chapter>
+

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Author_Group.xml	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Author_Group.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,41 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Quick_Start_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<authorgroup>
+  <author>
+    <firstname>Mark</firstname>
+    <surname>Little</surname>
+    <affiliation>
+      <orgname>Red Hat</orgname>
+    </affiliation>
+    <email>mlittle at redhat.com</email>
+  </author>
+  <author>
+    <firstname>Jonathan</firstname>
+    <surname>Halliday</surname>
+    <affiliation>
+      <orgname>Red Hat</orgname>
+    </affiliation>
+    <email>jhallida at redhat.com</email>
+  </author>
+  <author>
+    <firstname>Andrew</firstname>
+    <surname>Dinn</surname>
+    <affiliation>
+      <orgname>Red Hat</orgname>
+    </affiliation>
+    <email>adinn at redhat.com</email>
+  </author>
+  <author>
+    <firstname>Kevin</firstname>
+    <surname>Connor</surname>
+    <affiliation>
+      <orgname>Red Hat</orgname>
+    </affiliation>
+    <email>kconnor at redhat.com</email>
+  </author>
+
+</authorgroup>
+

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Book_Info.xml	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Book_Info.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,22 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Quick_Start_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<bookinfo id="book-JBossJTS_Quick_Start_Guide">
+  <title>&PRODUCT; Quick Start Guide</title>
+  <productname>JBossJTS</productname>
+  <productnumber>4.15.0</productnumber>
+  <edition>1</edition>
+  <pubsnumber>1</pubsnumber>
+  <corpauthor>
+    <inlinemediaobject>
+      <imageobject>
+        <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
+      </imageobject>
+    </inlinemediaobject>
+  </corpauthor>
+  <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
+

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.ent	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.ent	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,7 @@
+<!ENTITY PRODUCT "JBossJTS">
+<!ENTITY BOOKID "JBossJTS_Quick_Start_Guide">
+<!ENTITY VERSION "4.15">
+<!ENTITY YEAR "2011">
+<!ENTITY HOLDER "JBoss.org">
+<!ENTITY APPSERVER "JBoss Application Server">
+<!-- <!ENTITY APPSERVER "Enterprise Application Platform Server"> -->

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,13 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Quick_Start_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<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="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="Quick_Start_to_JTS_OTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <index />
+</book>

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Preface.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Preface.xml	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Preface.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,29 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Quick_Start_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<preface id="pref-JBossJTS_Quick_Start_Guide-Preface">
+  <title>Preface</title>
+
+  <section>
+    <title>Prerequisites</title>
+    <para>
+       &PRODUCT;
+      works in conjunction with the rest of the JBoss Transactions suite. In addition to the documentation here, consult the &PRODUCT;
+      documentation, which ships as part of &PRODUCT;
+      and is also available on the JBoss Transaction Service website
+      at
+      <ulink url="http://www.jboss.org/jbosstm" />
+      .
+    </para>
+  </section>
+
+  <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
+      <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </xi:fallback>
+  </xi:include>
+</preface>
+

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Quick_Start_to_JTS_OTS.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Quick_Start_to_JTS_OTS.xml	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Quick_Start_to_JTS_OTS.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,287 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Quick_Start_Guide.ent">
+]>
+<chapter>
+  <title>Quick Start to JTS/OTS</title>
+  <section>
+    <title>Introduction</title>
+    <para>This
+      chapter will briefly cover the key features required to construct a basic OTS application using the raw OTS interfaces defined by the
+      OMG
+      specification. It is assumed that the reader is familiar with the concepts of the JTS/OTS and has read the relevant ORB specific portions of
+      the &PRODUCT;
+      Programmer’s Guide. Further topics and the advanced facilities provided by &PRODUCT;
+      will be described in subsequent sections of this
+      manual; references to chapters in the other manuals of the document set will be given in the
+      relevant sections.
+    </para>
+  </section>
+  <section>
+    <title>Package layout</title>
+    <para>The key Java packages (and corresponding jar files) for writing basic OTS applications are:</para>
+    <itemizedlist>
+      <listitem>
+        <para>com.arjuna.orbportability: this package contains the classes which constitute the ORB portability library and other useful utility
+          classes.</para>
+      </listitem>
+      <listitem>
+        <para>org.omg.CosTransactions: this package contains the classes which make up the CosTransactions.idl module.</para>
+      </listitem>
+      <listitem>
+        <para>com.arjuna.ats.jts:
+          this package contains the &PRODUCT;
+          implementations of the JTS and JTA.
+        </para>
+      </listitem>
+      <listitem>
+        <para>com.arjuna.ats.arjuna:
+          this package contains further classes necessary for the &PRODUCT;
+          implementation of the JTS.
+        </para>
+      </listitem>
+      <listitem>
+        <para>com.arjuna.ats.jta: this package contains local and remote JTA implementation support.</para>
+      </listitem>
+      <listitem>
+        <para>com.arjuna.ats.jdbc: this package contains transactional JDBC support.</para>
+      </listitem>
+    </itemizedlist>
+    <para>All
+      of these packages appear in the lib directory of the &PRODUCT;
+      installation, and should be added to the programmer’s CLASSPATH.
+    </para>
+    <para>In
+      order to fully utilize all of the facilities available within &PRODUCT;,
+      it will be necessary to add the some additional jar files to your
+      classpath. See bin/setup-env.sh or bin\setup-env.bat for details.
+    </para>
+  </section>
+  <section>
+    <title>Setting properties</title>
+    <para>&PRODUCT;
+      has been designed to be highly configurable at runtime through the use of various property attributes, which will be described in
+      subsequent
+      sections. Although these attributes can be provided at runtime on the command line, it is possible (and may be more convenient) to
+      specify them
+      through the single properties file &PRODUCT;-properties.xml.
+      At runtime &PRODUCT;
+      looks for its property file in the following order:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>a location specified by a system property, allowing the normal search path to be overridden.</para>
+      </listitem>
+      <listitem>
+        <para>the current working directory, i.e., where the application was executed from.</para>
+      </listitem>
+      <listitem>
+        <para>the user’s home directory.</para>
+      </listitem>
+      <listitem>
+        <para>java.home</para>
+      </listitem>
+      <listitem>
+        <para>the CLASSPATH, which normally includes the installations etc dir</para>
+      </listitem>
+      <listitem>
+        <para>A default set of properties embedded in the .jar file.</para>
+      </listitem>
+    </itemizedlist>
+    <para>Where properties are defined in both the system properties e.g. -Dfoo=bar and in the properties file, the value from the system property
+      takes precedence. This facilitates overriding individual properties easily on the command line.</para>
+  </section>
+  <section>
+    <title>Starting and terminating the ORB and BOA/POA</title>
+    <para>It
+      is important that &PRODUCT;
+      is correctly initialized prior to any application object being created. In order to guarantee this, the
+      programmer must use the initORB and
+      initBOA/initPOA methods of the ORBInterface class described in the ORB Portability Manual. Using the
+      ORB_init and BOA_init/create_POA methods
+      provided by the underlying ORB will not be sufficient, and may lead to incorrectly operating
+      applications. For example:
+    </para>
+    <example>
+      <title>Initialize ORB</title>
+      <programlisting role="JAVA" language="Java"> <xi:include href="extras/initORB.java" xmlns:xi="http://www.w3.org/2001/XInclude"
+        parse="text" /> </programlisting>
+    </example>
+    <para>The ORBInterface class has operations orb() and boa()/poa()/rootPoa() for returning references to the orb and boa/child POA/root POA
+      respectively after initialization has been performed. If the ORB being used does not support the BOA (e.g., Sun’s JDK 1.2) then boa() does not
+      appear in the class definition, and initBOA will do nothing.</para>
+    <para>In
+      addition, it is necessary to use shutdownOA and shutdownORB (in that order) prior to terminating an application to allow &PRODUCT;
+      to
+      perform necessary cleanup routines. shutdownOA routine will either shutdown the BOA or the POA depending upon the ORB being used.
+    </para>
+    <example>
+      <title>Shutdown ORB</title>
+      <programlisting role="JAVA" language="Java"> <xi:include href="extras/shutdownORB.java" xmlns:xi="http://www.w3.org/2001/XInclude"
+        parse="text" /> </programlisting>
+    </example>
+    <para>No further CORBA objects should be used once shutdown has been called. It will be necessary to re-initialise the BOA/POA and ORB in such an
+      event.</para>
+    <note>
+      <para>
+        In the rest of this document we shall use the term Object Adapter to mean either the Basic Object Adapter (BOA) or the Portable Object
+        Adapter (POA). In addition, where possible we shall use the ORB Portability classes which attempt to mask the differences between POA and BOA.
+      </para>
+    </note>
+  </section>
+  <section>
+    <title>Specifying the object store location</title>
+    <para>&PRODUCT;
+      requires an object store in order to persistently record the outcomes of transactions in the event of failures. In order to specify
+      the location
+      of the object store it is necessary to specify the location when the application is executed; for example:
+    </para>
+    <para>
+      <programlisting role="JAVA" language="Java">java –DObjectStoreEnvironmentBean.objectStoreDir=/var/tmp/ObjectStore myprogram</programlisting>
+    </para>
+    <para>The default location is a directory under the current execution directory.</para>
+    <para>By default, all object states will be stored within the defaultStore subdirectory of the object store root, e.g.,
+      /usr/local/Arjuna/TransactionService/ObjectStore/defaultStore. However, this subdirectory can be changed by setting the
+      ObjectStoreEnvironmentBean.localOSRoot property variable accordingly.</para>
+  </section>
+  <section>
+    <title>Implicit transaction propagation and interposition</title>
+    <para>Transactions can be created within one domain (e.g., process) and used within another. Therefore, information about a transaction (the
+      transaction context) needs to be propagated between these domains. This can be accomplished in two ways:</para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <emphasis>Explicit propagation</emphasis>
+          means that an application propagates a transaction context by passing context objects (instances of the Control interface or the
+          PropagationContext structure) defined by the Transaction Service as explicit parameters. Note, for efficiency reasons it is recommended that
+          the PropagationContext be passed, rather than the Control.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <emphasis>Implicit propagation</emphasis>
+          means that requests on objects are implicitly associated with the client’s transaction; they share the client’s transaction context. The
+          context is transmitted implicitly to the objects, without direct client intervention.
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>OTS
+      objects supporting the Control interface are standard CORBA objects. When the interface is passed as a parameter in some operation call
+      to a
+      remote server only an object reference is passed. This ensures that any operations that the remote object performs on the interface (such
+      as
+      registering resources as participants within the transaction) are performed on the real object. However, this can have substantial penalties
+      for
+      the application if it frequently uses these interfaces due to the overheads of remote invocation. To avoid this overhead &PRODUCT;
+      supports
+      interposition, whereby the server creates a local object which acts as a proxy for the remote transaction and fields all requests that
+      would
+      normally have been passed back to the originator. This surrogate registers itself with the original transaction coordinator to enable it to
+      correctly participate in the termination of the transaction. Interposed coordinators effectively form a tree structure with their parent
+      coordinators. This is shown in the figure below.
+    </para>
+    <figure>
+      <title>Interposition relationship</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/interposition.gif" format="GIF" />
+        </imageobject>
+      </mediaobject>
+    </figure>
+    <note>
+      <para>implicit transaction propagation does not imply interposition will be used at the server, but (typically) interposition requires implicit
+        propagation.</para>
+    </note>
+    <para>If
+      implicit context propagation and interposition are required, then the programmer must ensure that &PRODUCT;
+      is correctly initialised prior
+      to objects being created; obviously it is necessary for both client and server to agree on which, if any, protocol
+      (implicit or interposition)
+      is being used. Implicit context propagation is only possible on those ORBs which either support filters/interceptors,
+      or the CosTSPortability
+      interface. Currently this is JacORB and the JDK miniORB. Depending upon which type of functionality is required, the
+      programmer must perform the
+      following:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>Implicit context propagation:</para>
+        <para>set the JTSEnvironmentBean.contextPropMode property variable to CONTEXT.</para>
+      </listitem>
+      <listitem>
+        <para>Interposition: </para>
+        <para>set the JTSEnvironmentBean.contextPropMode property variable to INTERPOSITION.</para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      If using the &PRODUCT;
+      advanced API then interposition is
+      <emphasis>required</emphasis>
+      .
+    </para>
+  </section>
+  <section>
+    <title>Obtaining Current</title>
+    <para>The Current pseudo object can be obtained from the com.arjuna.ats.jts.OTSManager class using its get_current() method.</para>
+  </section>
+  <section>
+    <title>Transaction termination</title>
+    <para>It
+      is implementation dependant as to how long a Control remains able to access a transaction after it terminates. In &PRODUCT;,
+      if using the
+      Current interface then all information about a transaction is destroyed when it terminates. Therefore, the programmer should not use
+      any Control
+      references to the transaction after issuing the commit/rollback operations.
+    </para>
+    <para>However, if the transaction is terminated explicitly using the Terminator interface then information about the transaction will be removed
+      when all outstanding references to it are destroyed. However, the programmer can signal that the transaction information is no longer required
+      using the destroyControl method of the OTS class in the com.arjuna.CosTransactions package. Once the program has indicated that the transaction
+      information is no longer required, the same restrictions to using Control references apply as described above.</para>
+  </section>
+  <section>
+    <title>Transaction factory</title>
+    <para>
+      By default, &PRODUCT;
+      does not use a separate transaction manager when creating transactions through the Current interface. Each transactional
+      client essentially has
+      its own transaction manager (TransactionFactory) which is co-located with it. By setting the
+      com.arjuna.ats.jts.transactionManager property
+      variable to YES this can be overridden at runtime. The transaction factory is located in the bin
+      directory of the &PRODUCT;
+      distribution, and should be started by executing the start-transaction-service script located in
+      &lt;ats_root&gt;/bin.
+    </para>
+    <para>Typically Current locates the factory using the CosServices.cfg file. This file is similar to resolve_initial_references, and is
+      automatically updated (or created) when the transaction factory is started on a particular machine. This file must be copied to the installation
+      of all machines which require to share the same transaction factory. CosServices.cfg is located at runtime by the OrbPortabilityEnvironmentBean
+      properties initialReferencesRoot (a directory, defaulting to the current working directory) and initialReferencesFile (a name relative to the
+      directory,'CosServices.cfg' by default).</para>
+    <para>It is possible to override the default location mechanism by using the OrbPortabilityEnvironmentBean.resolveService property variable. This
+      can have one of the following values:</para>
+    <itemizedlist>
+      <listitem>
+        <para>CONFIGURATION_FILE: the default, this causes the system to use the CosServices.cfg file.</para>
+      </listitem>
+      <listitem>
+        <para>NAME_SERVICE: &PRODUCT;
+          will attempt to use a name service to locate the transaction factory. If this is not supported, an exception will
+          be thrown.
+        </para>
+      </listitem>
+      <listitem>
+        <para>BIND_CONNECT: &PRODUCT;
+          will use the ORB-specific bind mechanism. If this is not supported, an exception will be thrown.
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>If OrbPortabilityEnvironmentBean.resolveService is specified when the transaction factory is run, then the factory will register itself with
+      the specified resolution mechanism.</para>
+  </section>
+  <section>
+    <title>Recovery manager</title>
+    <para>
+      You will need to start the recovery manager subsystem to ensure that transactions are recovered despite failures. In order to do this, you
+      should run the start-recovery-manager script in &lt;ats_root&gt;/bin.
+    </para>
+  </section>
+</chapter>

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Revision_History.xml	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/Revision_History.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,27 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Quick_Start_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<appendix id="appe-JBossJTS_Quick_Start_Guide-Revision_History">
+  <title>Revision History</title>
+  <simpara>
+    <revhistory>
+      <revision>
+        <revnumber>1</revnumber>
+        <date>Wed Apr 13 2010</date>
+        <author>
+          <firstname>Tom</firstname>
+          <surname>Jenkinson</surname>
+          <email>tom.jenkinson at redhat.com</email>
+        </author>
+        <revdescription>
+          <simplelist>
+            <member>Taken from installation guide</member>
+          </simplelist>
+        </revdescription>
+      </revision>
+    </revhistory>
+  </simpara>
+</appendix>
+

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/initORB.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/initORB.java	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/initORB.java	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,5 @@
+public static void main (String[] args) {
+	ORBInterface.initORB(args, null);
+	ORBInterface.initOA();
+	//	. . .
+}
\ No newline at end of file

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/interposition.gif
===================================================================
(Binary files differ)


Property changes on: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/interposition.gif
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/shutdownORB.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/shutdownORB.java	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/extras/shutdownORB.java	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,5 @@
+public static void main (String[] args) {
+	// . . .
+	ORBInterface.shutdownOA();
+	ORBInterface.shutdownORB();
+}

Added: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/publican.cfg
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/publican.cfg	                        (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/publican.cfg	2011-04-13 13:34:33 UTC (rev 36903)
@@ -0,0 +1,8 @@
+# Config::Simple 4.59
+# Wed Sep  1 15:11:59 2010
+
+xml_lang: en-US
+type: Book
+docname: JBossJTS Quick Start Guide
+brand: jboss-community
+tmp_dir: target/publican

Modified: labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/Author_Group.xml	2011-04-13 13:08:25 UTC (rev 36902)
+++ labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/Author_Group.xml	2011-04-13 13:34:33 UTC (rev 36903)
@@ -3,12 +3,12 @@
 <!ENTITY % BOOK_ENTITIES SYSTEM "Failure_Recovery_Guide.ent">
 ]>
 <authorgroup>
-    <author>
-        <firstname>Mark</firstname>
-        <surname>Little</surname>
-        <affiliation>
-            <orgname>Red Hat</orgname>
-        </affiliation>
-        <email>mlittle at redhat.com</email>
-    </author>
+  <author>
+    <firstname>Mark</firstname>
+    <surname>Little</surname>
+    <affiliation>
+      <orgname>Red Hat</orgname>
+    </affiliation>
+    <email>mlittle at redhat.com</email>
+  </author>
 </authorgroup>

More information about the jboss-svn-commits mailing list