[jboss-svn-commits] JBL Code SVN: r35756 - in labs/jbosstm/trunk/ArjunaJTS/docs: ArjunaJTS_Installation_And_Administration_Guide and 2 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Oct 26 20:07:47 EDT 2010
Author: misty at redhat.com
Date: 2010-10-26 20:07:46 -0400 (Tue, 26 Oct 2010)
New Revision: 35756
Added:
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.ent
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Author_Group.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Book_Info.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Chapter.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Initializing_JBossTS_Applications.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Introduction.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Logging.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ORB_Specific_Configurations.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/OTS_Java_EE_Transaction_Service_Management.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preface.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Revision_History.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Component.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Transaction_Management.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/images/
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/publican.cfg
Log:
JBTM-813 Added ArjunaJTS Installation and Administration Guide
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,13 @@
+<?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 "ArjunaJTS_Installation__And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Additional JAR Requirements</title>
+ <para>
+ To use all of the facilities available within ArjunaJTS, you need to add all of the JAR files contained in the
+ <filename>lib/</filename> directory of the distribution to the <varname>CLASSPATH</varname>.
+ </para>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,17 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>ArjunaJTS Runtime Information</title>
+ <para>
+ Compile-time configuration information is available via class
+ <classname>com.arjuna.common.util.ConfigurationInfo</classname>. Runtime configuration is embodied in the various
+ <!-- Should this be <classname><replaceable>name</replaceable>EnvironmentBean</classname> classes?
+ --><name>EnvironmentBean classes, see the configuration section of the user guide. These beans have
+ corresponding <!--<interfacename>MBean</interfacename>? -->MBean interfaces and may be linked to JMX for remote
+ inspection of the configuration if desired.
+ </para>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.ent (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.ent 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,4 @@
+<!ENTITY PRODUCT "ArjunaJTS">
+<!ENTITY BOOKID "ArjunaJTS_Installation_And_Administration_Administration_Guide">
+<!ENTITY YEAR "2010">
+<!ENTITY HOLDER "JBoss.org">
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ArjunaJTS_Installation_And_Administration_Guide.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,38 @@
+<?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 "ArjunaJTS_Installation_And_Administration_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" />
+ <part>
+ <title>Installation</title>
+ <xi:include href="Preparing_Your_System.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Operating_System_Services.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Web_Service_Component.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="ObjectStore_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Additional_JAR_Requirements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Setting_Properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </part>
+ <part>
+ <title>Administration</title>
+ <!-- <xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
+ <xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Starting_And_Stopping_Transaction_Manager.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="ObjectStore_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="OTS_Java_EE_Transaction_Service_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Web_Service_Transaction_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="ArjunaCore_Runtime_Information.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Failure_Recovery_Administration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="ORB_Specific_Configurations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Initializing_JBossTS_Applications.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Errors_And_Exceptions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+ </part>
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index />
+</book>
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Author_Group.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Author_Group.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,49 @@
+<?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 "ArjunaJTS_Installation_And_Administration_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>
+ <editor>
+ <firstname>Misty</firstname>
+ <surname>Stanley-Jones</surname>
+ <affiliation>
+ <orgname>Red Hat</orgname>
+ </affiliation>
+ <email>misty at redhat.com</email>
+ </editor>
+
+</authorgroup>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Book_Info.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Book_Info.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,28 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<bookinfo id="book-ArjunaJTS_Installation_And_Administration_Guide">
+ <title>ArjunaJTS Installation And Administration Guide</title>
+ <subtitle>Installation and Administration of the ArjunaJTS toolkit, used as part of the ArjunaCore Transaction Service</subtitle>
+ <productname>ArjunaJTS</productname>
+ <productnumber>4.13.0</productnumber>
+ <edition>1</edition>
+ <pubsnumber>1</pubsnumber>
+ <!--
+ <abstract> <para> A short overview and summary of the book's subject and purpose, traditionally no more than
+ one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in
+ the description field of the book's RPM spec file. </para> </abstract>
+ -->
+ <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/ArjunaJTS_Installation_And_Administration_Guide/en-US/Chapter.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Chapter.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Chapter.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,10 @@
+<?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_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title></title>
+
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,51 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title></title>
+
+ <para>
+ This section covers the types and causes of errors and exceptions which may be thrown or reported during a transactional
+ application.
+ </para>
+ <variablelist>
+ <title>Errors and Exceptions</title>
+ <varlistentry>
+ <term><literal>NO_MEMORY</literal></term>
+ <listitem>
+ <para>
+ The application has run out of memory, and has thrown an <systemitem>OutOfMemoryError</systemitem>
+ exception. <application>ArjunaJTS</application> has attempted to do some cleanup, by running the garbage
+ collector, before re-throwing the exception. This is probably a transient problem and retrying the invocation
+ should succeed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>com.arjuna.ats.arjuna.exceptions.FatalError</literal></term>
+ <listitem>
+ <para>
+ An error has occurred, and the error is of such severity that that the transaction system must shut
+ down. Prior to this error being thrown the transaction service ensures that all running transactions have
+ rolled back. If an application catches this error, it should tidy up and exit. If further work is attempted,
+ application consistency may be violated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>com.arjuna.ats.arjuna.exceptions.ObjectStoreError</literal></term>
+ <listitem>
+ <para>
+ An error occurred while the transaction service attempted to use the object store. Further forward progress is
+ not possible.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Object store warnings about access problems on states may occur during the normal execution of crash recovery. This
+ is the result of multiple concurrent attempts to perform recovery on the same transaction. It can be safely ignored.
+ </para>
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,210 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Failure Recovery Administration</title>
+
+ <para>
+ The failure recovery subsystem of ArjunaJTS will ensure that results of a transaction are applied consistently to
+ all resources affected by the transaction, even if any of the application processes or the machine hosting them
+ crash or lose network connectivity. In the case of machine (system) crash or network failure, the recovery will not
+ take place until the system or network are restored, but the original application does not need to be
+ restarted. Recovery responsibility is delegated to <xref linkend="recovery-manager" />. Recovery after failure
+ requires that information about the transaction and the resources involved survives the failure and is accessible
+ afterward: this information is held in the <systemitem>ActionStore</systemitem>, which is part of the
+ <systemitem>ObjectStore</systemitem>.
+ </para>
+ <warning>
+ <para>
+ If the <systemitem>ObjectStore</systemitem> is destroyed or modified, recovery may not be possible.
+ </para>
+ </warning>
+ <para>
+ Until the recovery procedures are complete, resources affected by a transaction that was in progress at the time of
+ the failure may be inaccessible. For database resources, this may be reported as tables or rows held by “in-doubt
+ transactions”. For <application>TransactionalObjects for Java</application> resources, an attempt to activate the
+ <systemitem>Transactional Object</systemitem> (as when trying to get a lock) will fail.
+ </para>
+
+ <section id="recovery-manager">
+ <title>The Recovery Manager</title>
+
+ <para>
+ The failure recovery subsystem of ArjunaJTS requires that the stand-alone Recovery Manager process be running for
+ each <systemitem>ObjectStore</systemitem> (typically one for each node on the network that is running ArjunaJTS
+ applications). The <filename>RecoveryManager</filename> file is located in the arjunaJTS JAR file within the
+ package <package>com.arjuna.ats.arjuna.recovery.RecoveryManager</package>. To start the Recovery Manager issue the
+ following command:
+ </para>
+ <screen>
+ <command>java com.arjuna.ats.arjuna.recovery.RecoveryManager</command>
+ </screen>
+ <para>
+ If the <parameter>-test</parameter> flag is used with the Recovery Manager then it will display a
+ <literal>Ready</literal> message when initialized, i.e.,
+ </para>
+ <screen>
+ <command>java com.arjuna.ats.arjuna.recovery.RecoveryManager -test</command>
+ </screen>
+ </section>
+
+ <section>
+ <title>Configuring the Recovery Manager</title>
+ <para>
+ The RecoveryManager reads the properties defined in the <filename>jbossts-properties.xml</filename> file.
+ </para>
+ <para>
+ A default version of <filename>jbossts-properties.xml</filename> is supplied with the distribution. This can
+ be used without modification, except possibly the debug tracing fields, as shown in <xref
+ linkend="recovery-manager-output" />.
+ </para>
+ </section>
+
+ <section id="recovery-manager-output">
+ <title>Output</title>
+
+ <para>
+ It is likely that installations will want to have some form of output from the RecoveryManager, to provide a
+ record of what recovery activity has taken place. RecoveryManager uses the logging mechanism provided by
+ <application>jboss logging</application>, which provides a high level interface that
+ hides differences that exist between existing logging APIs such Jakarta log4j or JDK logging API.
+ </para>
+ <para>
+ The configuration of <application>jboss logging</application> depends on the underlying logging framework
+ that is used, which is determined by the availability and ordering of alternatives on the classpath. Please
+ consult the jboss logging documentation for details. Each log message has an associated
+ log Level, that gives the importance and urgency of a log message. The set of possible Log Levels, in order of
+ least severity, and highest verbosity, is:
+ </para>
+ <orderedlist>
+ <listitem><para><literal>TRACE</literal></para></listitem>
+ <listitem><para><literal>DEBUG</literal></para></listitem>
+ <listitem><para><literal>INFO</literal></para></listitem>
+ <listitem><para><literal>WARN</literal></para></listitem>
+ <listitem><para><literal>ERROR</literal></para></listitem>
+ <listitem><para><literal>FATAL</literal></para></listitem>
+ </orderedlist>
+ <para>
+ Messages describing the start and the periodical behavior made by the RecoveryManager are output using the
+ <literal>INFO</literal> level. If other debug tracing is wanted, the finer debug or trace levels should be set
+ appropriately.
+ </para>
+ <para>
+ Setting the normal recovery messages to the <literal>INFO</literal> level allows the RecoveryManager to produce a
+ moderate level of reporting. If nothing is going on, it just reports the entry into each module for each periodic
+ pass. To disable <literal>INFO</literal> messages produced by the Recovery Manager, the logging level could be set
+ to the higher level of <literal>ERROR</literal>, which means that the RecoveryManager will only produce
+ <literal>ERROR</literal>, <literal>WARNING</literal>, or <literal>FATAL</literal> messages.
+ </para>
+ </section>
+
+ <section>
+ <title>Periodic Recovery</title>
+ <para>
+ The RecoveryManager scans the ObjectStore and other locations of information, looking for transactions and
+ resources that require, or may require recovery. The scans and recovery processing are performed by recovery
+ modules. These recovery modules are instances of classes that implement the
+ <interfacename>com.arjuna.ats.arjuna.recovery.RecoveryModule interface</interfacename>. Each module has
+ responsibility for a particular category of transaction or resource. The set of recovery modules used is
+ dynamically loaded, using properties found in the RecoveryManager property file.
+ </para>
+ <para><!-- Rewrite this as a procedure --> The interface has two methods:
+ <methodname>periodicWorkFirstPass</methodname> and <methodname>periodicWorkSecondPass</methodname>. At an interval
+ defined by property <property>com.arjuna.ats.arjuna.recovery.periodicRecoveryPeriod</property>, the RecoveryManager
+ calls the first pass method on each property, then waits for a brief period, defined by property
+ <property>com.arjuna.ats.arjuna.recovery.recoveryBackoffPeriod</property>. Next, it calls the second pass of each
+ module. Typically, in the first pass, the module scans the relevant part of the ObjectStore to find transactions or
+ resources that are in-doubt. An in-doubt transaction may be part of the way through the commitment process, for
+ instance. On the second pass, if any of the same items are still in-doubt, the original application process may have
+ crashed, and the item is a candidate for recovery.
+ </para>
+ <para>
+ An attempt by the RecoveryManager to recover a transaction that is still progressing in the original process is
+ likely to break the consistency. Accordingly, the recovery modules use a mechanism, implemented in the
+ <package>com.arjuna.ats.arjuna.recovery.TransactionStatusManager</package> package, to check to see if the
+ original process is still alive, and if the transaction is still in progress. The RecoveryManager only proceeds
+ with recovery if the original process has gone, or, if still alive, the transaction is completed. If a server
+ process or machine crashes, but the transaction-initiating process survives, the transaction completes, usually
+ generating a warning. Recovery of such a transaction is the responsibility of the RecoveryManager.
+ </para>
+ <para>
+ It is clearly important to set the interval periods appropriately. The total iteration time will be the sum of the
+ <property>periodicRecoveryPeriod</property> and <property>recoveryBackoffPeriod</property> properties, and the
+ length of time it takes to scan the stores and to attempt recovery of any in-doubt transactions found, for all the
+ recovery modules. The recovery attempt time may include connection timeouts while trying to communicate with
+ processes or machines that have crashed or are inaccessible. There are mechanisms in the recovery system to avoid
+ trying to recover the same transaction indefinitely. The total iteration time affects how long a resource will
+ remain inaccessible after a failure. – <property>periodicRecoveryPeriod</property> should be set accordingly. Its
+ default is 120 seconds. The <property>recoveryBackoffPeriod</property> can be comparatively short, and defaults to
+ 10 seconds. –Its purpose is mainly to reduce the number of transactions that are candidates for recovery and which
+ thus require a call to the original process to see if they are still in progress.
+ </para>
+ <note>
+ <para>
+ In previous versions of <application>ArjunaJTS</application>, there was no contact mechanism, and the back-off
+ period needed to be long enough to avoid catching transactions in flight at all. From 3.0, there is no such
+ risk.
+ </para>
+ </note>
+ <para>
+ Two recovery modules, implementations of the
+ <interfacename>com.arjuna.ats.arjuna.recovery.RecoveryModule</interfacename> interface, are supplied with
+ <application>ArjunaJTS</application>. These modules support various aspects of transaction recovery, including
+ JDBC recovery. It is possible for advanced users to create their own recovery modules and register them with the
+ Recovery Manager. The recovery modules are registered with the RecoveryManager using
+ <methodname>RecoveryEnvironmentBean.recoveryExtensions</methodname>. These will be invoked on each pass of the
+ periodic recovery in the sort-order of the property names – it is thus possible to predict the ordering, but a
+ failure in an application process might occur while a periodic recovery pass is in progress. The default Recovery
+ Extension settings are:
+ </para>
+ <programlisting language="XML" role="XML"><xi:include href="extras/default_recovery_extension_settings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+
+ </section>
+
+ <section>
+ <title>Expired Entry Removal</title>
+
+ <para>
+ The operation of the recovery subsystem cause some entries to be made in the ObjectStore that are not removed in
+ normal progress. The RecoveryManager has a facility for scanning for these and removing items that are very
+ old. Scans and removals are performed by implementations of the
+ <interfacename>com.arjuna.ats.arjuna.recovery.ExpiryScanner</interfacename> interface. These implementations are
+ loaded by giving the class names as the value of a property
+ <property>RecoveryEnvironmentBean.expiryScanners</property>. The RecoveryManager calls the
+ <methodname>scan()</methodname><!-- I don't like using brackets unless the method never has any parameters -->
+ method on each loaded Expiry Scanner implementation at an interval determined by the property
+ <property>RecoveryEnvironmentBean.expiryScanInterval</property>. This value is given in hours, and defaults to
+ 12hours. An <property>expiryScanInterval</property> value of zero suppresses any expiry scanning. If the value
+ supplied is positive, the first scan is performed when RecoveryManager starts. If the value is negative, the first
+ scan is delayed until after the first interval, using the absolute value.
+ </para>
+ <para>
+ The kinds of item that are scanned for expiry are:
+ </para>
+ <variablelist> <!-- Why is this presented as a list? -->
+ <varlistentry>
+ <term>TransactionStatusManager items</term>
+ <listitem>
+ <para>
+ One TransactionStatusManager item is created by every application process that uses
+ <application>ArjunaJTS</application>. It contains the information that allows the RecoveryManager to
+ determine if the process that initiated the transaction is still alive, and its status. The expiry time for
+ these items is set by the property
+ <property>com.arjuna.ats.arjuna.recovery.transactionStatusManagerExpiryTime</property>, expressed in
+ hours. The default is 12, and 0 (zero) means never to expire.The expiry time should be greater than the
+ lifetime of any single processes using <application>ArjunaJTS</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The Expiry Scanner properties for these are:
+ </para>
+ <programlisting language="XML" role="XML"> <xi:include href="extras/expiry_scanner_properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+
+ </section>
+
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Initializing_JBossTS_Applications.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Initializing_JBossTS_Applications.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Initializing_JBossTS_Applications.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,16 @@
+<?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_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Initializing JBossTS Applications</title>
+ <para>
+ JBossTS most be initialized correctly before any application object is created. To guarantee this, use the
+ <methodname>initORB</methodname> and <methodname>create_POA</methodname> methods described in the <citetitle>Orb
+ Portability Guide</citetitle>. Consult the Orb Portability Guide if you need to use the underlying
+ <methodname>ORB_init</methodname> and <methodname>create_POA</methodname> methods provided by the ORB instead of the
+ JBossTS methods.
+ </para>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Introduction.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Introduction.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Introduction.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,61 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Introduction</title>
+ <para>
+ Since the release of JBossTS 4.1, the Web Services Transaction product has been merged into JBoss
+ Transactions. JBoss Transactions is thus a single product that is compliant with all of the major distributed transaction
+ standards and specifications.
+ </para>
+ <para>
+ Knowledge of Web Services is not required to administer a JBoss Transactions installation that only uses the
+ CORBA/J2EE component, nor is knowledge of CORBA required to use the Web Services component. This, administrative
+ tasks are separated when they touch only one component or the other.
+ </para>
+ <para>
+ Apart from ensuring that the run-time system is executing normally, there is little continuous administration needed
+ for the ArjunaJTS software. Refer to <xref linkend="important_points_for_administrators" /> for some specific
+ concerns.
+ </para>
+ <itemizedlist id="important_points_for_administrators">
+ <title>Important Points for Administrators</title>
+ <listitem>
+ <para>
+ The present implementation of the ArjunaJTS system provides no security or protection for data. The objects
+ stored in the ArjunaJTS object store are (typically) owned by the user who ran the application that created
+ them. The Object Store and Object Manager facilities make no attempt to enforce even the limited form of
+ protection that Unix/Windows provides. There is no checking of user or group IDs on access to objects for either
+ reading or writing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Persistent objects created in the Object Store never go away unless the StateManager.destroy method is invoked
+ on the object or some application program explicitly deletes them. This means that the Object Store gradually
+ accumulates garbage (especially during application development and testing phases). At present we have no
+ automated garbage collection facility. Further, we have not addressed the problem of dangling references. That
+ is, a persistent object, A, may have stored a Uid for another persistent object, B, in its passive
+ representation on disk. There is nothing to prevent an application from deleting B even though A still contains
+ a reference to it. When A is next activated and attempts to access B, a run-time error will occur.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There is presently no support for version control of objects or database reconfiguration in the event of class
+ structure changes. This is a complex research area that we have not addressed. At present, if you change the
+ definition of a class of persistent objects, you are entirely responsible for ensuring that existing instances
+ of the object in the Object Store are converted to the new representation. The ArjunaJTS software can neither
+ detect nor correct references to old object state by new operation versions or vice versa.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Object store management is critically important to the transaction service.
+ </para>
+ </listitem>
+ </itemizedlist>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Logging.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Logging.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Logging.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,34 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Logging</title>
+ <para>
+ The recovery manager and the transaction server services produce log files which are located in the <filename>services/logs/</filename> directory. Two log files are created per service.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><filename><replaceable>service-name</replaceable>-service.log</filename></term>
+ <listitem>
+ <para>
+ Contains information regarding whether the service is stopped, started, restarted, or in another state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename><replaceable>service-name</replaceable>.log</filename></term>
+ <listitem>
+ <para>
+ Contains information logged from the actual service.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ To configure what information is logged in these files, edit the appropriate LOG4J configuration files located in
+ <filename>services/config/</filename>.
+ </para>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ORB_Specific_Configurations.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ORB_Specific_Configurations.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ORB_Specific_Configurations.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,82 @@
+<?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_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>ORB-specific Configurations</title>
+
+ <section>
+ <title>JacORB</title>
+ <para>
+ For JacORB to function correctly it needs a valid <filename>jacorb.properties</filename> or
+ <filename>.jacorb_properties</filename> file in one of the following places, in searched order:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The classpath
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The home directory of the user running the JBoss Transaction Service. The home directory is retrieved using
+ <methodname>System.getProperty( “user.home” );</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The current directory
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>lib/</filename> directory of the JDK used to run your application. This is retrieved using
+ <methodname>System.getProperty(“java.home” );</methodname>
+ </para>
+ </listitem>
+ </orderedlist>
+ <note>
+ <para>
+ A template <filename>jacorb.properties</filename> file is located in the JacORB installation directory.
+ </para>
+ </note>
+ <para>
+ Within the JacORB properties file there are two important properties which must be tailored to suit your
+ application.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ jacorb.poa.thread_pool_max
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ jacorb.poa.thread_pool_min
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ These properties specify the minimum and maximum number of request processing threads that JacORB uses in its
+ thread pool. If no threads are available, may block until a thread becomes available.. For more information on
+ configuring JacORB, refer to the JacORB documentation.
+ </para>
+ <important>
+ <para>
+ JacORB includes its own implementation of the classes defined in the <filename>CosTransactions.idl</filename>
+ file. Unfortunately these are incompatible with the version shipped with JBossTS. Therefore, the JBossTS jar
+ files absolutely must appear in the CLASSPATH before any JacORB jars.
+ </para>
+ </important>
+ <para>
+ When running the recovery manager, it should always uses the same well-known port for each machine on which it
+ runs. Do not use the <varname>OAPort</varname> property provided by JacORB unless the recovery manager has its own
+ <filename>jacorb.properties</filename> file or the property is provided on the command line when starting the
+ recovery manager. If the recovery manager and other components of JBossTS share the same
+ <filename>jacorb.properties</filename> file, use the <varname>JTSEnvironmentBean.recoveryManagerPort</varname> and
+ <varname>JTSEnvironmentBean.recoveryManagerAddress</varname> properties.
+ </para>
+ </section>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/OTS_Java_EE_Transaction_Service_Management.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/OTS_Java_EE_Transaction_Service_Management.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/OTS_Java_EE_Transaction_Service_Management.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,276 @@
+<?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_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>OTS and Java EE Transaction Service Management</title>
+
+ <section>
+ <title>Starting the run-time system</title>
+ <para>
+ The JBossTS run-time support consists of run-time packages and the OTS transaction manager server. By default,
+ JBossTS does not use a separate transaction manager server. Instead, transaction managers are co-located with each
+ application process to improve performance and improve application fault-tolerance by reducing application
+ dependency on other services.
+ </para>
+ <para>
+ When running applications which require a separate transaction manager, set the
+ <varname>JTSEnvironmentBean.transactionManager</varname> environment variable to value <literal>YES</literal>. The system locates the
+ transaction manager server in a manner specific to the ORB being used. This method may be any of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Being registered with a name server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Being added to the ORB’s initial references.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Via a JBossTS specific references file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ By the ORB’s specific location mechanism (if applicable).
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You override the default registration mechanism by using the
+ <varname>OrbPortabilityEnvironmentBean.resolveService</varname> environment variable, which takes the following
+ values:
+ </para>
+ <table>
+ <title>Possible values of <varname>OrbPortabilityEnvironmentBean.resolveService</varname></title>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>CONFIGURATION_FILE</entry>
+ <entry>
+ <para>
+ This is the default, and causes the system to use the <filename>CosServices.cfg</filename> file.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>NAME_SERVICE</entry>
+ <entry>
+ <para>
+ JBossTS attempts to use a name service to register the transaction factory. If this is not supported, an
+ exception is thrown.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>BIND_CONNECT</entry>
+ <entry>
+ <para>
+ JBossTS uses the ORB-specific bind mechanism. If this is not supported, an exception is thrown.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>RESOLVE_INITIAL_REFERENCES</entry>
+ <entry>
+ <para>
+ JBossTS attempts to register the transaction service with the ORB's initial service references. If the
+ ORB does not support this, an exception is thrown, and another option must be used.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <section>
+ <title>OTS configuration file</title>
+ <para>
+ Similar to the <systemitem>resolve_initial_references</systemitem>, JBossTS supports an initial reference file
+ where references for specific services can be stored and used at runtime. The file,
+ <filename>CosServices.cfg</filename>, consists of two columns: the service name (in the case of the OTS server
+ TransactionService), and the IOR, separated by a single space. <filename>CosServices.cfg</filename> is located
+ at runtime by the following <varname>OrbPortabilityEnvironmentBean</varname> properties:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><varname>initialReferencesRoot</varname></entry>
+ <entry>
+ <para>
+ The directory where the file is located, defaulting to the current working directory.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><varname>initialReferencesFile</varname></entry>
+ <entry>
+ <para>
+ The name of the configuration file itself, <literal>CosServices.cfg</literal> by default.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ The OTS server automatically registers itself in the <filename>CosServices.cfg</filename> file if the
+ <varname>OrbPortabilityEnvironmentBean</varname> option is used, creating the file if necessary. Stale
+ information is also automatically removed. Machines sharing the same transaction server should have access to
+ this file, or a copy of it locally.
+ </para>
+ <example>
+ <title>Example ORB reference file settings</title>
+ <screen>
+ <varname>OrbPortabilityEnvironmentBean.initialReferencesFile</varname>=<literal>myFile</literal>
+ <varname>OrbPortabilityEnvironmentBean.initialReferencesRoot</varname>=<literal>/tmp</literal>
+ </screen>
+ </example>
+ </section>
+
+
+ <section>
+ <title>Name service</title>
+ <para>
+ If your ORB supports a name service, and JBossTS is configured to use it, the transaction manager is registered
+ with it automatically. There is no further work required.
+ </para>
+ <note>
+ <para>
+ This option is not used for JacORB
+ </para>
+ </note>
+ </section>
+
+
+ <section>
+ <title>resolve_initial_references</title>
+ <para>
+ Currently this option is only supported for JacORB.
+ </para>
+ </section>
+
+ <section>
+ <title>Resolution services supported per ORB</title>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Resolution Mechanism</entry>
+ <entry>ORB</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>OTS configuration file</entry>
+ <entry>All available ORBs</entry>
+ </row>
+ <row>
+ <entry>Name Service</entry>
+ <entry>JacORB</entry>
+ </row>
+ <row>
+ <entry>resolve_initial_references</entry>
+ <entry>JacORB</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+ </section>
+
+ <section>
+ <title>XA Specific management</title>
+ <para>
+ Each XA Xid that JBossTS creates must have a unique node identifier encoded within it. JBossTS only recovers
+ transactions and states that match a specified node identifier. Provide the node identifier with the
+ <varname>CoreEnvironmentBean.nodeIdentifier</varname> property. This value must be unique across your JBossTS
+ instances. If you do not provide a value, JBossTS generates one and reports the value via the logging
+ infrastructure.
+ </para>
+ <para>
+ When running XA recovery, you need to specify which types of Xid JBossTS can recover. Use the
+ <varname>JTAEnvironmentBean.xaRecoveryNodes</varname> property to provide one or more values, in a space-separated
+ list.
+ </para>
+ <important>
+ <para>
+ A value of ‘*’ forces JBossTS to recover, and possibly rollback, all transactions, regardless of their node
+ identifier. Use this value with extreme caution.
+ </para>
+ </important>
+ </section>
+
+ <section>
+ <title>Selecting the JTA implementation</title>
+ <para>
+ Two variants of the JTA implementation are now provided and accessible through the same interface. These are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Purely local JTA</term>
+ <listitem>
+ <para>
+ Only non-distributed JTA transactions can be executed. This is the only version available with the JBossJTA
+ product.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Remote, CORBA-based JTA</term>
+ <listitem>
+ <para>
+ Distributed JTA transactions can be executed. This version is only available with the JBossTS product and
+ requires a supported CORBA ORB.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Both of these implementations are fully compatible with the transactional JDBC driver provided with JBossTS.
+ </para>
+ <procedure>
+ <title>Selecting the local JTA implementation</title>
+ <step>
+ <para>
+ Set the property <varname>JTAEnvironmentBean.jtaTMImplementation</varname> to value
+ <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple</literal>.
+ </para>
+ </step>
+ <step>
+ <para>
+ Set the property <varname>JTAEnvironmentBean.jtaUTImplementation</varname> to value
+ <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple</literal>.
+ </para>
+ </step>
+ </procedure>
+ <note>
+ <para>
+ These settings are the default values for the properties and do not need to be specified if the local
+ implementation is required.
+ </para>
+ </note>
+ <procedure>
+ <title>Selecting the remote JTA implementation</title>
+ <step>
+ <para>
+ Set the property <varname>JTAEnvironmentBean.jtaTMImplementation</varname> to value
+ <literal>com.arjuna.ats.internal.jta.transaction.jts..TransactionManagerImple</literal>.
+ </para>
+ </step>
+ <step>
+ <para>
+ Set the property <varname>JTAEnvironmentBean.jtaUTImplementation</varname> to value
+ <varname>com.arjuna.ats.internal.jta.transaction.jts.UserTransactionImple</varname>.
+ </para>
+ </step>
+ </procedure>
+ </section>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,73 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>ObjectStore Management</title>
+ <para><!-- This is duplicate content from the Installation Guide --> Within the transaction service installation, the
+ object store is updated regularly whenever transactions are created, or when <application>Transactional Objects for
+ Java</application> is used. In a failure-free environment, the only object states which should reside within the
+ object store are those representing objects created with the <application>Transactional Objects for Java</application>
+ API.
+ </para>
+ <para>
+ However, if failures occur, transaction logs may remain in the object store until crash recovery facilities have
+ resolved the transactions they represent. As such it is very important that the contents of the object store are not
+ deleted without due care and attention, as this will make it impossible to resolve in doubt transactions. In
+ addition, if multiple users share the same object store it is important that they realize this and do not simply
+ delete the contents of the object store assuming it is an exclusive resource.
+ </para>
+
+ <section>
+ <title>Specifying the ORB to use</title>
+ <para>
+ JDK releases from 1.2.2 onwards include a minimum ORB implementation from Sun. If you use such a JDK in conjunction
+ with another ORB, you must inform the JVM which ORB to use. Specify the
+ <varname>org.omg.CORBA.ORBClass</varname> and <varname>org.omg.CORBA.ORBSingletonClass</varname> properties. In
+ earlier versions of the Transaction Manager, you needed to specify these properties explicitly, either on the command line of in the properties file. However, the ORB Portability classes ensure that these properties are
+ automatically set when required. If needed, you can still specify the values explitly. This may be necessary if
+ you are not using the ORB initialization methods.
+ </para>
+
+ </section>
+
+ <section>
+ <title>The interface repository</title>
+ <para>
+ The transaction manager ships with two <systemitem>idl</systemitem> files, which are required to build and run
+ applications. These files are <filename>CosTransactions.idl</filename> and <filename>ArjunaOTS.idl</filename>. You
+ can register them with your interface repository before running any applications. Refer to the manual for your ORB
+ for instructions on how to register the interfaces.
+ </para>
+ </section>
+
+ <section>
+ <title>Installing into a non-default location</title>
+ <procedure>
+ <title>Installing into a non-default location</title>
+ <step>
+ <para>
+ Specify the location of the OTS server configuration file, using the
+ <varname>OrbPortabilityEnvironmentBean.initialReferencesRoot</varname> property variable. See the Orb
+ Portability manual for further details.
+ </para>
+ </step>
+ <step>
+ <para>
+ Specify the location of the object store, using the
+ <varname>ObjectStoreEnvironmentBean.objectStoreDir</varname> property variable.
+ </para>
+ </step>
+ <step>
+ <para>
+ Update your <varname>CLASSPATH</varname> to reflect the location of the various JBossTS jars in
+ <filename><replaceable>JBTS_ROOT</replaceable>/lib</filename> and
+ <filename><replaceable>JBTS_ROOT</replaceable>/lib/ext</filename>.
+ </para>
+ </step>
+ </procedure>
+ </section>
+
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,160 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Operating System Services</title>
+
+ <important>
+ <para>
+ Before running any of the scripts, you must edit the <filename>recoveryservice.conf</filename> and
+ <filename>transactionservice.conf</filename> files and replace <replaceable>PUT_JACORB_HOME_HERE</replaceable>
+ with the location of your JacORB installation.
+ </para>
+ </important>
+
+ <section>
+ <title>Microsoft Windows Server</title>
+ <para>
+ Four scripts, located in the <filename>Services\bin\windows</filename> folder, install and uninstall the recovery
+ manager and transaction server services.
+ </para>
+ <variablelist>
+ <title>Installation Scripts for Microsoft Windows</title>
+ <varlistentry>
+ <term>Recovery Manager Service</term>
+ <listitem><para><filename>InstallRecoveryManagerService-NT.bat</filename></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Transaction Server</term>
+ <listitem><para><filename>InstallTransactionServiceService-NT.bat</filename></para></listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <title>Uninstallation Scripts for Microsoft Windows</title>
+ <varlistentry>
+ <term>Recovery Manager Service</term>
+ <listitem><para><filename>UninstallRecoveryManagerService-NT.bat</filename></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Transaction Server</term>
+ <listitem><para><filename>UninstallTransactionServerService-NT.bat</filename></para></listitem>
+ </varlistentry>
+ </variablelist>
+ <note>
+ <para>
+ Each of the scripts requires administrative privileges.
+ </para>
+ </note>
+ <para>
+ After running any of the scripts, a status message indicates success or failure.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Linux / UNIX</title>
+
+ <procedure>
+ <title>Installing Services in Linux / UNIX</title>
+ <step>
+ <title>Log into the system with <systemitem>root</systemitem> privileges.</title>
+ <para>
+ The installer needs these privileges to create files in <filename>/etc</filename>.
+ </para>
+ </step>
+ <step>
+ <title>Change to <filename><replaceable>JBOSS_HOME</replaceable>/services/installer</filename> directory.</title>
+ <para>
+ <filename><replaceable>JBOSS_HOME</replaceable></filename> refers to the directory where you extracted ArjunaJTS.
+ </para>
+ </step>
+ <step>
+ <title>Set the <varname>JAVA_HOME</varname> variable, if necessary.</title>
+ <para>
+ Set the <varname>JAVA_HOME</varname> variable to the <firstterm>base directory</firstterm> of the JVM the service
+ will use. The base directory is the directory above <filename>bin/java</filename>.
+ </para>
+ <substeps>
+ <step>
+ <para>Bash: <command>export JAVA_HOME="/opt/java"</command></para>
+ </step>
+ <step>
+ <para>CSH: <command>setenv JAVA_HOME="/opt/java"</command></para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <title>Run the installer script.</title>
+ <para>
+ <command>./install_service.sh</command>
+ </para>
+ </step>
+ <step>
+ <title>The start-up and shut-down scripts are installed.</title>
+ <para>Information similar to the output below is displayed.</para>
+ <screen>
+ Adding $JAVA_HOME (/opt/java) to $PATH in /opt/arjuna/ats-3.2/services/bin/solaris/recoverymanagerservice.sh Adding
+ $JAVA_HOME (/opt/java) to $PATH in /opt/arjuna/ats-3.2/services/bin/solaris/transactionserverservice.sh Installing
+ shutdown scripts into /etc/rcS.d: K01recoverymanagerservice K00transactionserverservice Installing shutdown scripts
+ into /etc/rc0.d: K01recoverymanagerservice K00transactionserverservice Installing shutdown scripts into /etc/rc1.d:
+ K01recoverymanagerservice K00transactionserverservice Installing shutdown scripts into /etc/rc2.d:
+ K01recoverymanagerservice K00transactionserverservice Installing startup scripts into /etc/rc3.d:
+ S98recoverymanagerservice S99transactionserverservice
+ </screen>
+ <para>
+ The start-up and shut-down scripts are installed for each run-level. Depending on your specific operating
+ system, you may need to explicitly enable the services for automatic start-up.
+ </para>
+ </step>
+ </procedure>
+
+ <procedure>
+ <title>Uninstalling Services in Linux / UNIX</title>
+ <step>
+ <title>Log into the system with <systemitem>root</systemitem> privileges.</title>
+ <para>
+ The installer needs these privileges to delete files in <filename>/etc</filename>.
+ </para>
+ </step>
+ <step>
+ <title>Change to <filename><replaceable>JBOSS_HOME</replaceable>/services/installer</filename> directory.</title>
+ <para>
+ <filename><replaceable>JBOSS_HOME</replaceable></filename> refers to the directory where you extracted ArjunaJTS.
+ </para>
+ </step>
+
+ <step>
+ <title>Run the installation script with the <option>-u</option> option.</title>
+ <para>
+ <command>./install_services.sh -u</command>
+ </para>
+ </step>
+ <step>
+ <title>The start-up and shut-down scripts are removed.</title>
+ <para>
+ Messages like the ones below indicate that the start-up and shut-down scripts have been removed successfully.
+ </para>
+ <screen>
+ Removing startup scripts from /etc/rc3.d:
+ S98recoverymanagerservice
+ S99transactionserverservice
+ Removing shutdown scripts from /etc/rcS.d:
+ K01recoverymanagerservice
+ K00transactionserverservice
+ Removing shutdown scripts from /etc/rc0.d:
+ K01recoverymanagerservice
+ K00transactionserverservice
+ Removing shutdown scripts from /etc/rc1.d:
+ K01recoverymanagerservice
+ K00transactionserverservice
+ Removing shutdown scripts from /etc/rc2.d:
+ K01recoverymanagerservice
+ K00transactionserverservice
+ </screen>
+ </step>
+ </procedure>
+ </section>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preface.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preface.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preface.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,24 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<preface id="pref-ArjunaCore_Administration_Guide-Preface">
+ <title>Preface</title>
+
+ <section>
+ <title>Prerequisities</title>
+ <para>
+ ArjunaJTS is the implementation of the JTS API provided for use with JBoss Transaction Manager. For more details
+ about the Transaction Manager, refer to the ArjunaCore Installation and Administration Guide, which is also
+ available from the JBoss Transactions website, <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/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,57 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Preparing Your System</title>
+ <procedure>
+ <title>Pre-Installation Steps</title>
+ <para>
+ Before installing the ArjunaJTS software, we recommend the following administrative steps be taken, assuming a default configuration for ArjunaJTS.
+ </para>
+ <step>
+ <title>Optional but recommended: Create a user and group to run JBossTS.</title>
+ <para>
+ It is recommended that you create a user and group <literal>arjuna</literal>, using the preferred method for
+ your operating system. This user runs the OTS transaction manager, ensuring proper ownership of all the
+ transaction logs and the object store, and preventing accidental deletion of these objects by any other users.
+ </para>
+ </step>
+ <step>
+ <title>Install the distribution into the required location.</title>
+ <para>
+ Typically, the distribution is extracted from a <filename>.ZIP</filename> file.
+ </para>
+ </step>
+ <step>
+ <title>Specify the Location for the Object Store</title>
+ <para>
+ ArjunaJTS requires a minimum object store for storing the outcome of transactions in the event of system crashes. The location of this should be specified in the properties file using the <property>ObjectStoreEnvironmentBean.objectStoreDir</property> key or by using environment
+ variable:
+ </para>
+ <screen><command>java –DObjectStoreEnvironmentBean.objectStoreDir =C:\temp foo.</command></screen>
+ </step>
+ <step>
+ <title>Optional: Specify the sub-directory within the Object Store root.</title>
+ <para>
+ By default, all object states will be stored within the <filename>defaultStore/</filename> sub-directory of the
+ object store root. For instance, if the object store root is
+ <filename>/usr/local/Arjuna/TransactionService/ObjectStore</filename>, the subdirectory
+ <filename>/usr/local/Arjuna/TransactionService/ObjectStore/defaultStore/</filename> is used.
+ </para>
+ <para>
+ To change this subdirectory, set the <property>ObjectStoreEnvironmentBean.localOSRoot</property> or
+ <property>com.arjuna.ats.arjuna.objectstore.localOSRoot</property> property variable accordingly.
+ </para>
+ </step>
+ <step>
+ <title>Optional: Change the JTA implementation to use JTS instead of JTA.</title>
+ <para>
+ If you plan to use the JBossTS transactional JDBC driver, or JTA with the JTS, you must change the JTA
+ implementation to use the JTS. You should consult the ArjunaJTS Development Guide or the JTA manuals for
+ details.
+ </para>
+ </step>
+ </procedure>
+</chapter>
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Revision_History.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Revision_History.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<appendix>
+ <title>Revision History</title>
+ <simpara>
+ <revhistory>
+ <revision>
+ <revnumber>0</revnumber>
+ <date>Wed Sep 1 2010</date>
+ <author>
+ <firstname>Misty</firstname>
+ <surname>Stanley-Jones</surname>
+ <email>misty at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Conversion to Docbook</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </simpara>
+</appendix>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,51 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Setting Properties</title>
+ <para>
+ ArjunaJTS 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 may be more convenient to specify them through a
+ single properties file or via <methodname>setter</methodname> methods on the
+ beans. At runtime, ArjunaJTS looks for the file
+ <filename>jbossts-properties.xml</filename>, in a specific search order.
+ </para>
+ <orderedlist>
+ <listitem><para>A location specified by a system property<!--Which one? -->, allowing the normal search path to be overridden.</para></listitem>
+ <listitem><para>The directory from which the application was executed.</para></listitem>
+ <listitem><para>The home directory of the user that launched ArjunaJTS.</para></listitem>
+ <listitem><para><varname>java.home</varname></para></listitem><!-- Is that like $JAVA_HOME? -->
+ <listitem><para>The <varname>CLASSPATH</varname>, which normally includes the installation's
+ <filename>etc/</filename> directory.</para></listitem>
+ <listitem><para>A default set of properties embedded in the <filename>JAR</filename> file.</para></listitem>
+ </orderedlist>
+ <para>
+ Where properties are defined in both the system properties by using the <parameter>-D</parameter> switch, and in the
+ properties file, the value from the system property takes precedence. This facilitates overriding individual
+ properties easily on the command line.
+ </para>
+ <para>
+ The properties file uses <filename>java.uil.Properties</filename> XML format, for example:
+ </para>
+ <programlisting>
+ <![CDATA[
+<entry key="CoordinatorEnvironmentBean.asyncCommit">NO</entry>
+<entyr key="ObjectStoreEnvironmentBean.objectStoreDir">/var/ObjectStore</entry>
+ ]]>
+ </programlisting>
+ <para>
+ You can override the name of the properties file at runtime by specifying a new file using the
+ <varname>com.arjuna.ats.arjuna.common.propertiesFile</varname> attribute variable.
+ </para>
+ <note>
+ <para>
+ Unlike earlier releases, there is no longer one properties file name per module. This properties file name key is
+ now global for all JBoss Transaction Service components in the JVM.
+ </para>
+ </note>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,42 @@
+<?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 "ArjunaJTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Starting and Stopping the Transaction Manager</title>
+ <para>
+ By default the transaction manager starts up in an active state such that new transactions can be created
+ immediately. If you wish to have more control over this it is possible to set the
+ <option>CoordinatorEnvironmentBean.startDisabled</option> configuration option to <literal>YES</literal> and in
+ which case no transactions can be created until the transaction manager is enabled via a call to method
+ <methodname>TxControl.enable</methodname>).
+ </para>
+ <para>
+ It is possible to stop the creation of new transactions at any time by calling method
+ <methodname>TxControl.disable</methodname>. Transactions that are currently executing will not be affected. By
+ default recovery will be allowed to continue and the transaction system will still be available to manage recovery
+ requests from other instances in a distributed environment. (See the Failure Recovery Guide for further
+ details). However, if you wish to disable recovery as well as remove any resources it maintains, then you can pass
+ <literal>true</literal> to method <methodname>TxControl.disable</methodname>; the default is to use
+ <literal>false</literal>.
+ </para>
+ <para>
+ If you wish to shut the system down completely then it may also be necessary to terminate the background transaction
+ reaper (see the Programmers Guide for information about what the reaper does.) In order to do this you may want to
+ first prevent the creation of new transactions (if you are not creating transactions with timeouts then this step is
+ not necessary) using method <methodname>TxControl.disable</methodname>. Then you should call method
+ <methodname>TransactionReaper.terminate</methodname>. This method takes a Boolean parameter: if
+ <literal>true</literal> then the method will wait for the normal timeout periods associated with any transactions to
+ expire before terminating the transactions; if <methodname>false</methodname> then transactions will be forced to
+ terminate (rollback or have their outcome set such that they can only ever rollback) immediately.
+ </para>
+ <note>
+ <para>
+ if you intent to restart the recovery manager later after having terminated it then you MUST use the
+ <methodname>TransactionReapear.terminate</methodname> method with asynchronous behavior set to
+ <literal>false</literal>.
+ </para>
+ </note>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Component.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Component.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Component.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,19 @@
+<?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_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Web Service Component</title>
+ <para>
+ To configure the demo application of the Web Services transactions component and standalone coordinator, edit the
+ appropriate <filename>build.xml</filename> file before running <command>ant</command>. Consult the trail map
+ accompanying these components for details.
+ </para>
+ <para>
+ When running within JBoss Application Server, it is recommended to use the <literal>all</literal> server
+ profile. Specify the profile with the <parameter>-c</parameter> switch: <command>run.sh -c all</command> in Linux,
+ or <command>run.bat -c all</command> in Microsoft Windows.
+ </para>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Transaction_Management.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Transaction_Management.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/Web_Service_Transaction_Management.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,219 @@
+<?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_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Web Service Transaction Service (XTS) Management</title>
+ <para>
+ The basic building blocks of a transactional Web Services application include the application itself, the Web
+ services that the application consumes, the Transaction Manager, and the transaction participants which support
+ those Web services. Although it is likely that different developers will be responsible for each piece, the concepts
+ are presented here so that you can see the whole picture. Often, developers produce services, or applications that
+ consume services, and system administrators run the transaction-management infrastructure.
+ </para>
+
+ <section>
+ <title>Transaction manager overview</title>
+ <para>
+ The transaction manager is a Web service which coordinates JBossTS transactions. It is the only software component
+ in JBossTS that is designed to be run directly as a network service, rather than to support end-user code. The
+ transaction manager runs as a JAXM request/response Web service.
+ </para>
+ <note>
+ <para>
+ When starting up an application server instance that has JBossTS transaction manager deployed within it, you may
+ see various “error” messages in the console or log. For example 16:53:38,850 ERROR [STDERR] Message Listener
+ Service: started, message listener jndi name activationcoordinator". These are for information purposes only and
+ are not actual errors.
+ </para>
+ </note>
+ </section>
+
+
+ <section>
+ <title>Configuring the transaction manager</title>
+ <para>
+ You can configure the Transaction Manager and related infrastructure by using three properties files:
+ <filename>wscf.xml</filename>, <filename>wst.xml</filename>, and <filename>wstx.xml</filename>. Each file is
+ located in the <filename>conf/</filename> directory. Both the demo application and the stand-alone module rely on
+ them for configuration.
+ </para>
+ <para>
+ For the most part the default values in these files are suitable. However, the
+ <varname>ObjectStoreEnvironmentBean.objectStoreDir</varname> property, which determines the location of the
+ persistent store used to record transaction state, should be modified to suit your environment. The default value
+ is <literal>C:/temp/ObjectStore</literal>. For production environments this directory should reside on
+ fault-tolerant media such as a RAID array.
+ </para>
+ <para>
+ When an application uses a standalone coordinator, you must enable and modify two additional
+ properties in <filename>wstx.xml</filename>. These properties are
+ <varname>com.arjuna.mw.wst.coordinatorURL</varname> and <varname>com.arjuna.mw.wst.terminatorURL</varname>. They specify the
+ URLs needed by client application to contact the standalone coordinator, and need to specify the correct hostname
+ and port for the stand-alone server.
+ </para>
+ <para>
+ JBossTS is extremely modular. To allow flexible deployment of individual components, the same property values
+ sometimes need to appear in more than one configuration file. Except in special circumstances, maintain consistent
+ values for properties that are defined in more than one file.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Deploying the transaction manager</title>
+ <para>
+ The JBossTS XTS component consists of a number of <filename>.jar</filename> files containing the application’s
+ class files, plus Web service (<filename>.war</filename>) files which expose the necessary services. These
+ components are typically included in an application's Enterprise Archive (<filename>.ear</filename>) file during
+ application development, as this simplifies deployment of the transaction infrastructure. For production, you can
+ install the Transaction Manager as an application in its own right, allowing for centralized configuration and
+ management at the server level, independent of specific applications. The demonstration application shipped with
+ JBossTS provides a sample deployment descriptor illustrating how the Transaction Manager components can be
+ included in an application.
+ </para>
+ <para>
+ JBossTS 4.x uses fixed endpoints for its underlying protocol communication. Therefore, problems may arise if you
+ deploy multiple applications using JBossTS to the same server concurrently. If you need to deploy several
+ transactional applications in the same server, you must deploy the Transaction Manger as a separate application,
+ rather than embedding it within the development of individual applications.
+ </para>
+ <para>
+ The <filename>coordinator/</filename> directory in the JBossTS installation can assist in the configuration and
+ deployment of a stand-alone transaction manager.
+ </para>
+ <procedure>
+ <title>Using the <filename>coordinator/</filename> diretory to configure and deploy a stand-alone transaction manager</title>
+ <step>
+ <para>
+ Install JBossTS 4.14.
+ </para>
+ </step>
+ <step>
+ <para>
+ Use a separate application server installation for the coordinator. This installation can be on a separate
+ machine. To set this up on JBoss Application Server, see <ulink
+ url="http://www.yorku.ca/dkha/jboss/docs/MultipleInstances.htm" /> for more information.
+ </para>
+ </step>
+ <step>
+ <para>
+ Install Ant 1.4 or later.
+ </para>
+ <warning>
+ <para>
+ A separate application server installation must be used, separate from the one that clients and services are
+ deployed into, to prevent conflicts between the various JBossTS components.
+ </para>
+ </warning>
+ </step>
+ <step>
+ <para>
+ Edit the <filename>build.xml</filename> included in the <filename>coordinator/</filename> directory, to point
+ to the application server installation where the transaction coordinator will be deployed and the location of
+ the JBossTS installation. The files <filename>ws-c_jaxm_web-app.xml</filename> and
+ <filename>ws-t_jaxm_web-app.xml</filename> in the <filename>dd/</filename> subdirectory of
+ <filename>coordinator/</filename> are the deployment descriptors for the WS-C and WS-T
+ <filename>war</filename> files. These files contain templated URLs. During the build phase, ant will
+ substitute the hostname and port values you specify in the <filename>build.xml</filename> into these files.
+ </para>
+ </step>
+ <step>
+ <para>
+ Run ant, with one of targets <systemitem>deploy-weblogic</systemitem>, <systemitem>deploy-jboss</systemitem>,
+ or <systemitem>deploy-webmethods</systemitem>, to create and deploy a new coordinator into the correct
+ application server installation.
+ </para>
+ </step>
+ <step>
+ <para>
+ Finally, point your client at the required coordinator. To do this, generate the demo
+ application. specifying the port and hostname of the coordinator.
+ </para>
+ </step>
+ </procedure>
+ </section>
+
+ <section>
+ <title>Deployment descriptors</title>
+ <para>
+ In general, changing the contents of the various deployment descriptors used by JBossTS is not necessary. However,
+ if you do need to modify them they are all included in the coordinator module.
+ </para>
+ <para>
+ Not all JBossTS components have ready access to the information in the deployment descriptors. Therefore, if you
+ modify the JNDI names used by any of the WS-C or WS-T deployment descriptors, you may need to inform other JBossTS
+ components at runtime, by setting an appropriate property in the <filename>wstx.xml</filename> configuration
+ file.
+ </para>
+ <important>
+ <para>
+ You need to prefix each property in this table with the string <literal>com.arjuna.mw.wst.</literal>. The
+ prefix has been removed for formatting reasons, and has been replaced by <literal>...</literal>.
+ </para>
+ </important>
+ <table>
+ <title>Deployment descriptor values and properties</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>JNDI Name</entry>
+ <entry>Property</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Activationrequester</entry>
+ <entry>...at.activationrequester</entry>
+ </row>
+ <row>
+ <entry>Activationcoordinator</entry>
+ <entry>...at.activationcoordinator</entry>
+ </row>
+ <row>
+ <entry>Completionparticipant</entry>
+ <entry>...at.completionparticipant</entry>
+ </row>
+ <row>
+ <entry>Registrationrequester</entry>
+ <entry>...at.registrationrequester</entry>
+ </row>
+ <row>
+ <entry>durable2pcdispatcher</entry>
+ <entry>...at.durable2pcdispatcher</entry>
+ </row>
+ <row>
+ <entry>durable2pcparticipant</entry>
+ <entry>...at.durable2pcparticipant</entry>
+ </row>
+ <row>
+ <entry>volatile2pcdispatcher</entry>
+ <entry>...at.volatile2pcdispatcher</entry>
+ </row>
+ <row>
+ <entry>volatile2pcparticipant</entry>
+ <entry>...at.volatile2pcparticipant</entry>
+ </row>
+ <row>
+ <entry>businessagreementwithparticipantcompletiondispatcher</entry>
+ <entry>...ba.businessagreementwpcdispatcher</entry>
+ </row>
+ <row>
+ <entry>businessagreementwithparticipantcompletionparticipant</entry>
+ <entry>...ba.businessagreementwpcparticipant</entry>
+ </row>
+ <row>
+ <entry>businessagreementwithcoordinatorcompletiondispatcher</entry>
+ <entry>...ba.businessagreementwccdispatcher</entry>
+ </row>
+ <row>
+ <entry>Businessagreementwithcoordinatorcompletionparticipant</entry>
+ <entry>...ba.businessagreementwccparticipant</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,7 @@
+<entry key="RecoveryEnvironmentBean.recoveryExtensions">
+ com.arjuna.ats.internal.arjuna.recovery.AtomicActionRecoveryModule
+ com.arjuna.ats.internal.txoj.recovery.TORecoveryModule
+ com.arjuna.ats.internal.jts.recovery.transactions.TopLevelTransactionRecoveryModule
+ com.arjuna.ats.internal.jts.recovery.transactions.ServerTransactionRecoveryModule
+ com.arjuna.ats.internal.jta.recovery.jts.XARecoveryModule
+</entry>
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,3 @@
+<entry key="RecoveryEnvironmentBean.expiryScanners">
+ com.arjuna.ats.internal.arjuna.recovery.ExpiredTransactionStatusManagerScanner
+</entry>
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/publican.cfg
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/publican.cfg (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Installation_And_Administration_Guide/publican.cfg 2010-10-27 00:07:46 UTC (rev 35756)
@@ -0,0 +1,7 @@
+# Config::Simple 4.59
+# Wed Sep 1 15:11:59 2010
+
+xml_lang: en-US
+type: Book
+brand: jboss-community
+tmp_dir: ../../build/ArjunaCore_Installation_And_Administration_Guide
More information about the jboss-svn-commits
mailing list