Attachment 833116 Details for Bug 1038585 – Administration & configuration guide

Administration & configuration guide

tx_admin.txt (text/plain), 14.66 KB, created by Radim Vansa on 2013-12-05 12:23:54 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Radim Vansa

Created: 2013-12-05 12:23:54 UTC

Size: 14.66 KB

patch

obsolete

>23.1. About Transactions
>A transaction consists of a collection of interdependent or related operations or tasks. All operations within a single transaction must succeed for the overall success of the transaction. If any operations within a transaction fail, the transaction as a whole fails and rolls back any changes. Transactions are particularly useful when dealing with a series of changes as part of a larger operation.
>
>In Red Hat JBoss Data Grid, transactions are only available in Library mode.
>
>23.1.1. Transaction Manager
>In Red Hat JBoss Data Grid, the Transaction Manager coordinates transactions across a single or multiple resources. The responsibilities of a Transaction Manager include:
>
>    initiating and concluding transactions
>    managing information about each transaction
>    coordinating transactions as they operate over multiple resources
>    recovering from a failed transaction by rolling back changes 
>
>23.1.2. XA Resources and Synchronizations
>
>XA Resources are fully fledged transaction participants. In the prepare phase, XA Resource votes either OK or ABORT. If the Transaction Manager receives OK votes from all XA Resources, the transaction is committed, otherwise it is rolled back.
>
>Synchronizations are a type of listener that receives notifications about events leading to the transaction life cycle. Synchronizations receive an event before and after the operation completes.
>
>It may not be necessary to register as a full XA resource unless there is a need to use recovery as well. Synchronizations have the advantage that they allow Transaction Manager to optimize 2PC with a 1PC where only one other resource is enlisted with that transaction (last resource commit optimization). This makes registering a synchronization more efficient.
>However, if the operation fails in prepare phase within Red Hat JBoss Data Grid, the transaction is not rolled back and if there are more participants in the transaction, these may ignore this failure and commit. Also, errors encountered in the commit phase are not propageted to the application code committing the transaction.
>
>By default Red Hat JBoss Data Grid registers to the transaction as a synchronization.
>
>23.1.3. Optimistic and Pessimistic transactions
>
>Pessimistic transactions acquire the locks as soon as the first write operation on the key is executed. After the key is locked, no other transaction can modify the key until this transaction is committed or rolled back. It is up to the application code to acquire the locks in correct order, to prevent deadlocks.
>
>With optimistic transactions locks are acquired at transaction prepare time and are held up only to the point the transaction commits (or rollbacks). Also, Red Hat JBoss Data Grid sorts keys for all entries modified within a transaction automatically, preventing deadlock due to incorrect order of keys being locked. This results in less messages being sent during the transaction execution, locks held for shorted period and possibly better throughput.
>
>Note:
>Read operations never acquire any locks. Acquiring the lock for a read operation on demand is possible only with pessimistic transactions, using the FORCE_WRITE_LOCK flag with the operation.
>
>23.1.4. Write skew check
>In common use case an entry is read and subsequently written in a transaction. However, another transaction might modify the entry between these two operations. In order to detect such situation and rollback a transaction Red Hat JBoss Data Grid offers entry versioning and write skew checks. If the modified version has not the same version as when it was read the last time in this transaction, the write skew checks throws an exception and the transaction is rolled back.
>Enabling write skew check requires the REPEATABLE_READ isolation level. Also, in clustered mode (distributed/replicated) you have to set up entry versioning. For local mode, entry versioning is not required.
>With optimistic transactions, write skew checks are required for (atomic) conditional operations.
>
>23.1.5. Transactions Spanning Multiple Cache Instances
>Each cache operates as a separate, standalone Java Transaction API (JTA) resource. However, components can be internally shared by Red Hat JBoss Data Grid for optimization, but this sharing does not affect how caches interact with a Java Transaction API (JTA) Manager.
>
>23.2. Configure Transactions
>23.2.1. Configure Transactions (Library Mode)
>In Red Hat JBoss Data Grid, transactions in Library mode can be configured with synchronization and transaction recovery. Transactions in their entirety (which includes synchronization and transaction recovery) are not available in Remote Client-Server mode.
>In Library mode, transactions are configured as follows:
>
>Procedure 23.2. Configure Transactions in Library Mode (XML Configuration)
>
>1.  Set the Transaction Mode
>    The transactionMode element configures whether or not the cache is transactional. Default value is NON_TRANSACTIONAL.
>
>    <namedCache ...>
>        <transaction transactionMode="{TRANSACTIONAL,NON_TRANSACTIONAL}">
>                ...
>    </namedCache>      
>
>2.  Configure the Transaction Manager
>    See the table below this procedure for a list of available lookup classes.
>
>
>    <transaction transactionMode="TRANSACTIONAL"
>                 transactionManagerLookupClass="{TransactionManagerLookupClass}">
>
>3.  Configure Locking Mode
>    The lockingMode parameter determines if the optimistic or pessimistic locking method is used. If the cache is non-transactional, the locking mode is ignored. Default value is OPTIMISTIC.
>
>    <transaction transactionMode="TRANSACTIONAL"    	           
>    	           transactionManagerLookupClass="{TransactionManagerLookupClass}"
>                 lockingMode="{OPTIMISTIC,PESSIMISTIC}">
>
>4.  Specify Synchronization
>    The useSynchronization element configures the cache to register a synchronization with the transaction manager, or register itself as an XA resource. Default is true (use synchronization).
>
>    <transaction transactionMode="TRANSACTIONAL"
>    	           transactionManagerLookupClass="{TransactionManagerLookupClass}"
>    	           lockingMode="{OPTIMISTIC,PESSIMISTIC}"
>    	           useSynchronization="{true,false}">
>
>5.  Configure Recovery
>    The recovery enabled enables recovery for the cache when set to "true".
>    The recoveryInfoCacheName is used to set the name of the cache where recovery information is held. The default name of the cache is "__recoveryInfoCacheName__".
>
>    <transaction transactionMode="{TRANSACTIONAL,NON_TRANSACTIONAL}"
>    	           transactionManagerLookupClass="{TransactionManagerLookupClass}"
>    	           lockingMode="{OPTIMISTIC,PESSIMISTIC}"
>    	           useSynchronization="true">
>    		<recovery enabled="true" recoveryInfoCacheName="{CacheName}" />
>    </transaction>
>
>6.  Configure write skew check
>    The writeSkew check determines if modification of entry from different transaction should rollback this transaction. Write skew set to "true" requires isolation_level set to REPEATABLE_READ. Default values are writeSkew="false" and isolation_level="READ_COMMITTED".
> 
>    <namedCache ...>   
>        <transaction ...>
>        <locking isolation_level="{READ_COMMITTED,REPEATABLE_READ}" writeSkew="{true,false}" />
>        ...
>    </namedCache>
>
>7.  Configure entry versioning
>    For clustered cache, enabled write skew check requires entry versioning enabled and set to SIMPLE.
>    
>    <namedCache ...>
>        <transaction ...>
>        <locking ...>
>        <versioning enabled="{true,false}" versioningScheme="{NONE|SIMPLE}"/>
>        ...
>    </namedCache>
>
>Procedure 23.3. Configure Transactions in Library Mode (Programmatic Configuration)
>
>1.  Set the Transaction Mode
>    Configuration config = new ConfigurationBuilder()/* ... */.transaction()
>        .transactionMode(TransactionMode.TRANSACTIONAL);
>
>2.  Configure the Transaction Manager
>    See the table below this procedure for a list of available lookup classes.
>
>    Configuration config = new ConfigurationBuilder()/* ... */.transaction()
>        .transactionMode(TransactionMode.TRANSACTIONAL)
>        .transactionManagerLookup(new GenericTransactionManagerLookup());
>    
>3.  Configure Locking Mode
>    The lockingMode determines if the optimistic or pessimistic locking method is used. If the cache is non-transactional, the locking mode is ignored. Default value is OPTIMISTIC.
>
>    Configuration config = new ConfigurationBuilder()/* ... */.transaction()
>        .transactionMode(TransactionMode.TRANSACTIONAL)
>        .transactionManagerLookup(new GenericTransactionManagerLookup());
>        .lockingMode(LockingMode.OPTIMISTIC);
>
>4.  Specify Synchronization
>    The useSynchronization configures the cache to register a synchronization with the transaction manager, or register itself as an XA resource. Default is true (use synchronization).
>
>    Configuration config = new ConfigurationBuilder()/* ... */.transaction()
>        .transactionMode(TransactionMode.TRANSACTIONAL)
>        .transactionManagerLookup(new GenericTransactionManagerLookup());
>        .lockingMode(LockingMode.OPTIMISTIC)
>        .useSynchronization(true);        
>
>5.  Configure Recovery
>    The recovery enabled enables recovery for the cache when set to "true".
>    The recoveryInfoCacheName is used to set the name of the cache where recovery information is held. The default name of the cache is specified by RecoveryConfiguration.DEFAULT_RECOVERY_INFO_CACHE.
>
>    Configuration config = new ConfigurationBuilder()/* ... */.transaction()
>        .transactionMode(TransactionMode.TRANSACTIONAL)
>        .transactionManagerLookup(new GenericTransactionManagerLookup());
>        .lockingMode(LockingMode.OPTIMISTIC)
>        .useSynchronization(true)
>        .recovery()
>            .recoveryInfoCacheName("anotherRecoveryCacheName");
>
>6.  Configure write skew check
>    The writeSkew check determines if modification of entry from different transaction should rollback this transaction. Write skew set to "true" requires isolation_level set to REPEATABLE_READ. Default values are writeSkew="false" and isolation_level="READ_COMMITTED".
> 
>    Configuration config = new ConfigurationBuilder()/* ... */.locking()
>        .isolationLevel(IsolationLevel.REPEATABLE_READ).writeSkewCheck(true);
>
>7.  Configure entry versioning
>    For clustered cache, enabled write skew check requires entry versioning enabled and set to SIMPLE.
>    
>    Configuration config = new ConfigurationBuilder()/* ... */.versioning()
>        .enable()
>        .scheme(VersioningScheme.SIMPLE);
>    
>### insert Table 14.1. Transaction Manager Lookup Classes from the Dev guide
>
>23.2.2. Configure Transactions (Remote Client-Server Mode)
>Red Hat JBoss Data Grid does not offer transactions in remote client-server mode. The default and only supported configuration is non-transactional, set as below:
>
><cache>
>	...
> 	<transaction mode="NONE" />
>	...
></cache>
>
>23.3. Transaction Recovery
>
>The Transaction Manager coordinates the recovery process and works with Red Hat JBoss Data Grid to determine which transactions require manual intervention to complete operations. This process is known as transaction recovery.
>
>Red Hat JBoss Data Grid uses JMX for operations that explicitly force transactions to commit or rollback. These methods receive byte arrays that describe the XID instead of the number associated with the relevant transactions.
>The System Administrator can use such JMX operations to facilitate automatic job completion for transactions that require manual intervention. This process uses the Transaction Manager's transaction recovery process and has access to the Transaction Manager's XID objects.
>
>23.3.1. Transaction Recovery Process
>The following process outlines the transaction recovery process in Red Hat JBoss Data Grid.
>
>Procedure 23.3. The Transaction Recovery Process
>
>1.  The Transaction Manager creates a list of transactions that require intervention.
>2.  The system administrator, connected to JBoss Data Grid using JMX, is presented with the list of transactions (including transaction IDs) using email or logs. The status of each transaction is either COMMITTED or PREPARED. If some transactions are in both COMMITTED and PREPARED states, it indicates that the transaction was committed on some nodes while in the preparation state on others.
>3.  The System Administrator visually maps the XID received from the Transaction Manager to a JBoss Data Grid internal ID. This step is necessary because the XID (a byte array) cannot be conveniently passed to the JMX tool and then reassembled by JBoss Data Grid without this mapping.
>4.  The system administrator forces the commit or rollback process for a transaction based on the mapped internal ID. 
>
>23.3.2. Transaction Recovery Example
>The following example describes how transactions are used in a situation where money is transferred from an account stored in a database to an account stored in Red Hat JBoss Data Grid.
>
>Example 23.1. Money Transfer from an Account Stored in a Database to an Account in JBoss Data Grid
>
>    The TransactionManager.commit() method is invoked to to run the two phase commit protocol between the source (the database) and the destination (JBoss Data Grid) resources.
>    The TransactionManager tells the database and JBoss Data Grid to initiate the prepare phase (the first phase of a Two Phase Commit). 
>
>During the commit phase, the database applies the changes but JBoss Data Grid fails before receiving the Transaction Manager's commit request. As a result, the system is in an inconsistent state due to an incomplete transaction. Specifically, the amount to be transferred has been subtracted from the database but is not yet visible in JBoss Data Grid because the prepared changes could not be applied.
>Transaction recovery is used here to reconcile the inconsistency between the database and JBoss Data Grid entries.
>
>Note:
>To use JMX to manage transaction recoveries, JMX support must be explicitly enabled.
>
>23.4. Deadlock Detection
>A deadlock occurs when multiple processes or tasks wait for the other to release a mutually required resource. Deadlocks can significantly reduce the throughput of a system, particularly when multiple transactions operate against one key set.
>Red Hat JBoss Data Grid provides deadlock detection to identify such deadlocks. Deadlock detection is set to disabled by default.
>
>23.4.1. Enable Deadlock Detection
>Deadlock detection in Red Hat JBoss Data Grid is set to disabled by default but can be enabled and configured for each cache using the namedCache configuration element by adding the following:
>
><deadlockDetection enabled="true" spinDuration="100"/>
>
>The spinDuration attribute defines how often is lock acquisition attempted within maximum time allowed to acquire a particular lock, in milliseconds.
>
>Deadlock detection can only be applied to individual caches. Deadlocks that are applied on more than one cache cannot be detected by JBoss Data Grid.
>

Actions: View

Attachments on bug 1038585: 833116 | 833117