[jboss-cvs] JBossAS SVN: r100391 - projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Feb 4 02:01:16 EST 2010
Author: laubai
Date: 2010-02-04 02:01:16 -0500 (Thu, 04 Feb 2010)
New Revision: 100391
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml
Log:
Partially corrected Transactions.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml 2010-02-04 06:17:28 UTC (rev 100390)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Transactions.xml 2010-02-04 07:01:16 UTC (rev 100391)
@@ -3,54 +3,54 @@
<chapter id="transaction">
<title>Transaction Management</title>
<section>
- <title>Overview</title>
- <para>Transaction support in JBoss Enterprise Web Platform is provided by JBossTS, a mature, modular,
- standards based, highly configurable transaction manager. By default the
- server runs with the local-only JTA module of JBossTS installed. This module
- provides an implementation of the standard JTA API for use by other internal
- components, such as the EJB container, as well as direct use by application
- code. It is suitable for coordinating ACID transactions that involve one or
- more XA Resource managers, such as databases or message queues.</para>
- <para>Two additional, optional, JBossTS transaction modules are also shipped with
- JBoss Enterprise Web Platform and may be deployed to provide additional functionality if
- required. These are:</para>
- <itemizedlist>
- <listitem>
- <para>JBossTS JTS, a transaction manager capable of distributing
- transaction context on remote IIOP method calls, thus
- creating a single distributed transaction spanning multiple
- JVMs. This is useful for e.g. large scale applications that
- span multiple servers, or for standards based
- interoperability with transactional business logic running
- in CORBA based systems. The functionality of this module can
- be accessed through the standard JTA API, making it a
- drop-in replacement that does not require changes to
- transactional business logic. It is necessary only to change
- the server configuration. Details of this process are given
- below.</para>
- </listitem>
- <listitem>
- <para>JBossTS XTS, an XML based transaction service implementing the
- WS-AtomicTransaction (WS-AT) and WS-BusinessActivity (WS-BA)
- version 1.2 specifications. This additional module utilizes
- core transaction support provided by the JTA or JTS, as well
- as web services functionality provided by JBossWS Native. It
- is deployed into the server as an application, a process
- detailed below. Applications may use WS-AT to provide
- standards based, distributed ACID transactions in a manner
- broadly similar to JTS but using a web services transport
- rather than a CORBA one. The WS-BA implementation
- compliments this by providing an alternative, compensation
- based transaction model, well suited to coordinating long
- running, loosely coupled business processes. XTS also
- implements a WS-Coordination service which, usually, is only
- accessed internally by the local WS-AT and WS-BA
- implementations. However, this WS-C service can also be used
- to provide remote coordination for WS-AT and WS-BA
- transactions created in other JBoss server instances or
- non-JBoss containers.</para>
- </listitem>
- </itemizedlist>
+ <title>Overview</title>
+ <para>Transaction support in JBoss Enterprise Web Platform is provided by JBoss Transaction Service,
+ (JBoss TS) a mature, modular, standards-based, highly configurable transaction manager. By default the
+ server runs with the local-only JTA module of JBossTS installed. This module
+ provides an implementation of the standard JTA API for use by other internal
+ components, such as the EJB container, as well as direct use by application
+ code. It is suitable for coordinating ACID transactions that involve one or
+ more XA Resource managers, such as databases or message queues.</para>
+ <para>Two additional, optional, JBoss Transaction Service modules are also shipped with
+JBoss Enterprise Web Platform and may be deployed to provide additional functionality if
+ required. These are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>JBoss TS JTS, a transaction manager capable of distributing
+ transaction context on remote IIOP method calls, thus
+ creating a single distributed transaction spanning multiple
+ JVMs. This is useful for large scale applications that
+ span multiple servers, or for standards based
+ interoperability with transactional business logic running
+ in CORBA based systems. The functionality of this module can
+ be accessed through the standard JTA API, making it a
+ drop-in replacement that does not require changes to
+ transactional business logic. It is necessary only to change
+ the server configuration. Details of this process are given
+ below.</para>
+ </listitem>
+ <listitem>
+ <para>JBossTS XTS, an XML based transaction service implementing the
+ WS-AtomicTransaction (WS-AT) and WS-BusinessActivity (WS-BA)
+ version 1.2 specifications. This additional module utilizes
+ core transaction support provided by the JTA or JTS, as well
+ as web services functionality provided by JBossWS Native. It
+ is deployed into the server as an application, a process
+ detailed below. Applications may use WS-AT to provide
+ standards based, distributed ACID transactions in a manner
+ broadly similar to JTS but using a web services transport
+ rather than a CORBA one. The WS-BA implementation
+ compliments this by providing an alternative, compensation
+ based transaction model, well suited to coordinating long
+ running, loosely coupled business processes. XTS also
+ implements a WS-Coordination service which, usually, is only
+ accessed internally by the local WS-AT and WS-BA
+ implementations. However, this WS-C service can also be used
+ to provide remote coordination for WS-AT and WS-BA
+ transactions created in other JBoss server instances or
+ non-JBoss containers.</para>
+ </listitem>
+ </itemizedlist>
</section>
<section>
<title>Configuration Essentials</title>
@@ -72,143 +72,139 @@
changes made thereafter, either to the properties file, beans file, or
programatically, will not have an effect until server (JVM) restart.</para>
<para>The most critical bean properties are:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>transactionTimeout – the default time, in seconds,
- after which a transaction will be considered to be
- stuck and may be rolled back by the transaction
- manager.</para>
- <para>The transaction timeout functionality is useful to
- prevent poorly written code, such as large SQL
- queries, from blocking the system indefinitely. The
- default value is 300 seconds. This should be
- adjusted to suit your environment and
- workload.</para>
- <para>Note that transaction timeouts are processed
- asynchronously, a design decision which can take
- some applications by surprise. See the transaction
- timeout handling section below for more
- details.</para>
- </listitem>
- <listitem>
- <para>objectStoreDir - the directory to which transaction
- data will be logged. This bean property overrides
- the jbossts-properties.xml config file value for
- com.arjuna.ats,arjuna,objectstore.objectStoreDir</para>
- <para>This transaction log is required to complete
- transactions in the case of system failures. The
- performance and reliability of the storage device
- used for it are critical. In general, local RAID
- disk should be preferred. Remote storage may be used
- provided it correctly implements file locking.
- However, requiring network I/O for this storage can
- be a significant bottleneck on performance. The
- ObjectStore will normally contain one file per
- in-flight transaction, each a few kbytes in size.
- These are distributed over a directory tree for
- optimal performance. The small file size and rapid
- creation/deleting of files lends itself well to SSD
- based storage devices, although traditional hard
- drives may of course still be used. If a RAID
- controller is used, it should be configured for
- write through cache, in much the same manner as
- database storage devices. Writing of the transaction
- log is automatically skipped in the case of
- transactions that are rolling back or contain only a
- single resource.</para>
- </listitem>
- </itemizedlist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>transactionTimeout</varname></term>
+ <listitem>
+ <para>
+ The default time in seconds before a transaction will be considered stuck
+ and may be rolled back by the transaction manager. This helps to prevent
+ poor code from blocking the system indefinitely.
+ </para>
+ <para>
+ The default value is <literal>300</literal> seconds. This should be adjusted
+ to suit your environment and workload.
+ </para>
+ <para>
+ Transaction timeouts are processed asynchronously, which may not be
+ appropriate for your application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>objectStoreDir</varname></term>
+ <listitem>
+ <para>
+ Defines the directory in which to log transaction data. This bean property
+ overrides the <filename>jbossts-properties.xml</filename> configuration file
+ value for <classname>com.arjuna.ats,arjuna,objectstore.objectStoreDir</classname>.
+ </para>
+ <para>
+ This transaction log is required to complete transactions in case of system
+ failure. The storage device used must therefore be highly performant and
+ reliable. In general, local RAID disk is preferred. Remote storage can be used
+ if file locking is correctly implemented. However, requiring network I/O can be
+ a significant performance bottleneck.
+ </para>
+ <para>
+ The <classname>ObjectStore</classname> usually contains one file of several
+ kilobytes per in-flight transaction. These are distributed over a directory tree
+ for optimal performance. The small file size and rapid creation/deletion of files
+ lends itself well to SSD-based storage devices. If used, RAID controllers should
+ be configured for write through cache, similarly to database storage devices.
+ Writing the transaction log is automatically skipped for transactions that are
+ rolling back or contain only a single resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <para>The following additional configuration properties present in the
- jbossts-properties.xml may also be of interest:</para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para>com.arjuna.common.util.logging.DebugLevel</para>
- <para>This setting determines the internal log threshold for
- the transaction manager codebase. It is independent
- of the server's wider log4j logging configuration
- and represents an additional hurdle that log
- messages must pass before being printed. The default
- value is “0x00000000” i.e. no debug logging. INFO
- and WARN messages will still be printed by default.
- This provides optimal performance. The value
- “0xffffffff” should be used when full debug logging
- is required. This is very verbose and will result in
- large log files. Log messages that pass the internal
- DebugLevel check will be passed to the server's
- logging system for further processing. Thus it may
- also be necessary to set appropriate configuration
- for “com.arjuna” code in the
- server/[name]/conf/jboss-log4j.xml file. Note that
- whilst a value of “0xffffffff” may be left in place
- permanently and the log4j settings used to turn
- logging on or off, this is less performant than
- using the internal DebugLevel checking.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.coordinator.commitOnePhase</para>
- <para>This setting determines if the transaction manager
- will automatically apply the one-phase commit
- optimization to the transaction completion protocol
- in cases where only a single resource is registered
- with the transaction. It is enabled (“YES”) by
- default to provide optimal performance, since no
- transaction log write is necessary in such cases.
- Some resource managers may not be compatible with
- this optimization and it is occasionally necessary
- to disable it. This can be done by changing the
- value to “NO”.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.objectstore.transactionSync</para>
- <para>This setting controls the flushing of transaction logs
- to disk during the transaction termination. It is
- enabled (“ON”) by default, which results in a
- FileDescriptor.sync call for each committing
- transaction. This is required to provide recovery
- guarantees and hence ACID properties. If the
- applications running in the server can tolerate data
- inconsistency or loss, greater performance may be
- achieved by disabling this behavior by setting the
- property value to “OFF”. This is not recommended –
- it is usually preferable to recraft such
- applications to avoid using the transaction manager
- entirely.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.xa.nodeIdentifier and
- com.arjuna.ats.jta.xaRecoveryNode</para>
- <para>These properties determine the behavior of the
- transaction recovery system. Correct configuration
- is essential to ensure transactions are resolved
- correctly in the event of a server crash and
- restart. See the crash recovery section below for
- details.</para>
- <para>Additional properties that may be added to the
- jbossts-properties.xml include the following. Care
- should be taken to place these in the appropriate
- section of the file, or they may not be correctly
- processed.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.coordinator.enableStatistics</para>
- <para>This property enables the gathering of transaction
- statistics, which may be viewed via methods on the
- TransactionManagerService bean or, more commonly,
- its corresponding JMX MBean. This option is disabled
- by default, as the additional locking needed to
- record statistics accurately may cause a slight
- performance impact. Thus the statistics getter
- methods will thus normally return zero values. To
- enable the option, set its value to “YES” in the
- properties file.</para>
- </listitem>
- </itemizedlist>
- </para>
+ <para>The following configuration properties can also be specified in
+ <filename>jbossts-properties.xml</filename> may also be of interest:</para>
+ <!--hajime-->
+ <itemizedlist>
+ <listitem>
+ <para>com.arjuna.common.util.logging.DebugLevel</para>
+ <para>This setting determines the internal log threshold for
+ the transaction manager codebase. It is independent
+ of the server's wider log4j logging configuration
+ and represents an additional hurdle that log
+ messages must pass before being printed. The default
+ value is “0x00000000” i.e. no debug logging. INFO
+ and WARN messages will still be printed by default.
+ This provides optimal performance. The value
+ “0xffffffff” should be used when full debug logging
+ is required. This is very verbose and will result in
+ large log files. Log messages that pass the internal
+ DebugLevel check will be passed to the server's
+ logging system for further processing. Thus it may
+ also be necessary to set appropriate configuration
+ for “com.arjuna” code in the
+ server/[name]/conf/jboss-log4j.xml file. Note that
+ whilst a value of “0xffffffff” may be left in place
+ permanently and the log4j settings used to turn
+ logging on or off, this is less performant than
+ using the internal DebugLevel checking.</para>
+ </listitem>
+ <listitem>
+ <para>com.arjuna.ats.arjuna.coordinator.commitOnePhase</para>
+ <para>This setting determines if the transaction manager
+ will automatically apply the one-phase commit
+ optimization to the transaction completion protocol
+ in cases where only a single resource is registered
+ with the transaction. It is enabled (“YES”) by
+ default to provide optimal performance, since no
+ transaction log write is necessary in such cases.
+ Some resource managers may not be compatible with
+ this optimization and it is occasionally necessary
+ to disable it. This can be done by changing the
+ value to “NO”.</para>
+ </listitem>
+ <listitem>
+ <para>com.arjuna.ats.arjuna.objectstore.transactionSync</para>
+ <para>This setting controls the flushing of transaction logs
+ to disk during the transaction termination. It is
+ enabled (“ON”) by default, which results in a
+ FileDescriptor.sync call for each committing
+ transaction. This is required to provide recovery
+ guarantees and hence ACID properties. If the
+ applications running in the server can tolerate data
+ inconsistency or loss, greater performance may be
+ achieved by disabling this behavior by setting the
+ property value to “OFF”. This is not recommended –
+ it is usually preferable to recraft such
+ applications to avoid using the transaction manager
+ entirely.</para>
+ </listitem>
+ <listitem>
+ <para>com.arjuna.ats.arjuna.xa.nodeIdentifier and
+ com.arjuna.ats.jta.xaRecoveryNode</para>
+ <para>These properties determine the behavior of the
+ transaction recovery system. Correct configuration
+ is essential to ensure transactions are resolved
+ correctly in the event of a server crash and
+ restart. See the crash recovery section below for
+ details.</para>
+ <para>Additional properties that may be added to the
+ jbossts-properties.xml include the following. Care
+ should be taken to place these in the appropriate
+ section of the file, or they may not be correctly
+ processed.</para>
+ </listitem>
+ <listitem>
+ <para>com.arjuna.ats.arjuna.coordinator.enableStatistics</para>
+ <para>This property enables the gathering of transaction
+ statistics, which may be viewed via methods on the
+ TransactionManagerService bean or, more commonly,
+ its corresponding JMX MBean. This option is disabled
+ by default, as the additional locking needed to
+ record statistics accurately may cause a slight
+ performance impact. Thus the statistics getter
+ methods will thus normally return zero values. To
+ enable the option, set its value to “YES” in the
+ properties file.</para>
+ </listitem>
+ </itemizedlist>
</section>
<section>
<title>Transactional Resources</title>
More information about the jboss-cvs-commits
mailing list