[jboss-svn-commits] JBL Code SVN: r35757 - in labs/jbosstm/trunk/XTS/docs: XTS_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:53:24 EDT 2010
Author: misty at redhat.com
Date: 2010-10-26 20:53:23 -0400 (Tue, 26 Oct 2010)
New Revision: 35757
Added:
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Author_Group.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Book_Info.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Chapter.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Introduction.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Logging.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preface.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Revision_History.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.ent
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/images/
labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/publican.cfg
Log:
JBTM-813 Added XTS Installation and Administration Guide, mergin the two separate guides. Pending review.
Added: labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Additional_JAR_Requirements.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,12 @@
+<?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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Additional JAR Requirements</title>
+ <para>
+ To use all of the facilities available within XTS, 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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>XTS 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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Author_Group.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Author_Group.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Book_Info.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Book_Info.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<bookinfo id="book-XTS_Installation_And_Administration_Guide">
+ <title>XTS Installation And Administration Guide</title>
+ <subtitle>Installation and Administration for the Web Services Transaction Service Manager (XTS) of the ArjunaCore Transaction Service</subtitle>
+ <productname>XTS</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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Chapter.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Chapter.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Chapter.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Errors_And_Exceptions.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,63 @@
+<?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_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Errors and Exceptions</title>
+
+ <para>
+ This section covers the types and causes of errors and exceptions which may be thrown or reported during a transactional
+ application.
+ </para>
+ <table>
+ <title>Errors and Exceptions</title>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="100px" />
+ <colspec colnum="2" colwidth="340px" />
+ <thead>
+ <row>
+ <entry>Error</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para><literal>NO_MEMORY</literal></para></entry>
+ <entry>
+ <para>
+ The application has run out of memory, and has thrown an <systemitem>OutOfMemoryError</systemitem>
+ exception. <application>XTS</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>
+ </entry>
+ </row>
+ <row>
+ <entry><para><literal>com.arjuna.ats.arjuna.exceptions.FatalError</literal></para></entry>
+ <entry>
+ <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>
+ </entry>
+ </row>
+ <row>
+ <entry><para><literal>com.arjuna.ats.arjuna.exceptions.ObjectStoreError</literal></para></entry>
+ <entry>
+ <para>
+ An error occurred while the transaction service attempted to use the object store. Further forward
+ progress is not possible.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Failure_Recovery_Administration.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Failure Recovery Administration</title>
+
+ <para>
+ The failure recovery subsystem of XTS 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 XTS 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 XTS
+ applications). The <filename>RecoveryManager</filename> file is located in the XTS 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>XTS</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>XTS</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>XTS</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>XTS</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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Introduction.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Introduction.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Introduction.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Introduction</title>
+ <para>
+ Apart from ensuring that the run-time system is executing normally, there is little continuous administration needed
+ for the XTS 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 XTS system provides no security or protection for data. The objects
+ stored in the XTS 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 XTS 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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Logging.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Logging.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Logging.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/ObjectStore_Management.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,22 @@
+<?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 "XTS_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>
+</chapter>
+
Added: labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Operating_System_Services.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,161 @@
+<?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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Operating System Services</title>
+
+ <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 XTS.
+ </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 XTS.
+ </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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preface.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preface.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preface.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<preface id="pref-ArjunaCore_Administration_Guide-Preface">
+ <title>Preface</title>
+
+ <section>
+ <title>Prerequisites</title>
+ <para>
+ XTS (XML Transaction Service) refers to the JBoss Web Service Transaction compliant transaction manager. XTS is
+ an extension of ArjunaCore, and the ArjunaCore documentation contains knowledge crucial to understanding JBoss
+ Transactions. The ArjunaCore documentation is available from the JBoss Transactions 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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Preparing_Your_System.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,43 @@
+<?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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Preparing Your System</title>
+ <procedure>
+ <title>Pre-Installation Steps</title>
+ <para>
+ Before installiqng the XTS software, we recommend the following administrative steps be taken, assuming a default
+ configuration for XTS.
+ </para>
+ <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>
+ XTS 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>
+ </procedure>
+</chapter>
Added: labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Revision_History.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Revision_History.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "ArjunaCore_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<appendix id="appe-ArjunaCore_Administration_Guide-Revision_History">
+ <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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Setting_Properties.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,49 @@
+<?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 "XTS_Installation_And_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-ArjunaCore_Installation_Guide-Test_Chapter">
+ <title>Setting Properties</title>
+ <para>
+ XTS 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, XTS 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 XTS.</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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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 "XTS_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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.ent
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.ent (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.ent 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,4 @@
+<!ENTITY PRODUCT "ArjunaCore">
+<!ENTITY BOOKID "ArjunaCore_Administration_Guide">
+<!ENTITY YEAR "2010">
+<!ENTITY HOLDER "JBoss.org">
Added: labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/XTS_Installation_And_Administration_Guide.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,30 @@
+<?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 "ArjunaCore_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="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="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="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/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -0,0 +1,4 @@
+<entry key="RecoveryEnvironmentBean.recoveryExtensions">
+ com.arjuna.ats.internal.arjuna.recovery.AtomicActionRecoveryModule
+ com.arjuna.ats.internal.txoj.recovery.TORecoveryModule
+</entry>
Added: labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/en-US/extras/expiry_scanner_properties.xml 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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/XTS/docs/XTS_Installation_And_Administration_Guide/publican.cfg
===================================================================
--- labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/publican.cfg (rev 0)
+++ labs/jbosstm/trunk/XTS/docs/XTS_Installation_And_Administration_Guide/publican.cfg 2010-10-27 00:53:23 UTC (rev 35757)
@@ -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/XTS_Installation_And_Administration_Guide
More information about the jboss-svn-commits
mailing list