[jboss-svn-commits] JBL Code SVN: r35264 - in labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide: ArjunaCore_Administration_Guide and 2 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Sep 23 20:45:25 EDT 2010
Author: misty at redhat.com
Date: 2010-09-23 20:45:24 -0400 (Thu, 23 Sep 2010)
New Revision: 35264
Added:
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.ent
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Author_Group.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Book_Info.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Chapter.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Errors_And_Exceptions.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Failure_Recovery_Administration.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Introduction.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ObjectStore_Management.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Preface.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Revision_History.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/expiry_scanner_properties.xml
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/images/
labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/publican.cfg
Log:
Docbook version of ArjunaCore Administration Guide
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.ent (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.ent 2010-09-24 00:45:24 UTC (rev 35264)
@@ -0,0 +1,4 @@
+<!ENTITY PRODUCT "ArjunaCore">
+<!ENTITY BOOKID "ArjunaCore_Administration_Guide">
+<!ENTITY YEAR "2010">
+<!ENTITY HOLDER "JBoss.org">
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Administration_Guide.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -0,0 +1,19 @@
+<?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_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" />
+<!-- <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" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index />
+</book>
+
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ArjunaCore_Runtime_Information.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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 "ArjunaCore_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>ArjunaCore 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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Author_Group.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Author_Group.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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 "ArjunaCore_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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Book_Info.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Book_Info.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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 "ArjunaCore_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<bookinfo id="book-ArjunaCore_Administration_Guide-ArjunaCore_Administration_Guide">
+ <title>ArjunaCore Administration Guide</title>
+ <subtitle>Administration of the ArjunaCore Transaction Service</subtitle>
+ <productname>ArjunaCore</productname>
+ <productnumber>4.12.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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Chapter.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Chapter.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Chapter.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Errors_And_Exceptions.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Errors_And_Exceptions.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Errors_And_Exceptions.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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 "ArjunaCore_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>
+ <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>ArjunaCore</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.LicenceError</literal></para></entry><!-- Can this one
+ still happen? -->
+ <entry>
+ <para>
+ An attempt has been made to use the transaction service in a manner inconsistent with the current
+ licence. The transaction service will not allow further forward progress for existing or new transactions.
+ </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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Failure_Recovery_Administration.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Failure_Recovery_Administration.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Failure_Recovery_Administration.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -0,0 +1,215 @@
+<?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>Failure Recovery Administration</title>
+
+ <para>
+ The failure recovery subsystem of ArjunaCore 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 ArjunaCore 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 ArjunaCore
+ applications). The <filename>RecoveryManager</filename> file is located in the arjunacore 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 initialised, 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>arjuna.properties</filename> file and then also
+ reads the property file <filename>RecoveryManager.properties</filename>, from the same directory as it found the
+ <filename>arjuna.properties</filename> file. An entry for a property in the RecoveryManager properties file will
+ override an entry for the same property in the main TransactionService properties file. Most of the entries are
+ specific to the Recovery Manager.
+ </para>
+ <para>
+ A default version of <filename>RecoveryManager.properties</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" />. The rest of this section discusses the issues relevant in setting the
+ properties to other values, in the order of their appearance in the default version of the file.
+ </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 tracing mechanism provided by
+ the <application>Arjuna Common Logging Framework (CLF)</application>, which provides a high level interface that
+ hides differences that exist between existing logging APIs such Jakarta log4j or JDK 1.4 <!-- Should this be
+ updated to 1.5? 1.6?-->logging API. CLF indirects all logging via the <application>Apache Commons Logging
+ framework</application> and configuration is assumed to occur through that framework.
+ </para>
+ <para>
+ With the CLF, applications make logging calls on <interfacename>logger</interfacename> objects. Loggers use
+ logging Levels to decide if they are interested in a particular log message. 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>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 debugging level 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>ArjunaCore</application>, there was no contact mechanism, and the backoff
+ 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>ArjunaCore</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>ArjunaCore</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>ArjunaCore</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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Introduction.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Introduction.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Introduction.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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 "ArjunaCore_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 ArjunaCore 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 ArjunaCore system provides no security or protection for data. The objects
+ stored in the ArjunaCore 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 ArjunaCore 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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ObjectStore_Management.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ObjectStore_Management.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/ObjectStore_Management.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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 "ArjunaCore_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 realise this and do not simply
+ delete the contents of the object store assuming it is an exclusive resource.
+ </para>
+</chapter>
+
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Preface.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Preface.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Preface.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -0,0 +1,13 @@
+<?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 "ArjunaCore_Administration_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<preface id="pref-ArjunaCore_Administration_Guide-Preface">
+ <title>Preface</title>
+ <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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Revision_History.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Revision_History.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/Starting_And_Stopping_Transaction_Manager.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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 "ArjunaCore_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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/default_recovery_extension_settings.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -0,0 +1,4 @@
+e<entry key="RecoveryEnvironmentBean.recoveryExtensions">
+ com.arjuna.ats.internal.arjuna.recovery.AtomicActionRecoveryModule
+ com.arjuna.ats.internal.txoj.recovery.TORecoveryModule
+</entry>
Added: labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/expiry_scanner_properties.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/expiry_scanner_properties.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/en-US/extras/expiry_scanner_properties.xml 2010-09-24 00:45:24 UTC (rev 35264)
@@ -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/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/publican.cfg
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/publican.cfg (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/user_guide/Administration_Guide/ArjunaCore_Administration_Guide/publican.cfg 2010-09-24 00:45:24 UTC (rev 35264)
@@ -0,0 +1,7 @@
+# Config::Simple 4.59
+# Wed Sep 1 15:11:59 2010
+
+xml_lang: en-US
+type: Book
+brand: jboss-community
+
More information about the jboss-svn-commits
mailing list