From e38b83def456a8c5c5e6ebcc388854213b1db203 Mon Sep 17 00:00:00 2001 From: Michael Musgrove Date: Fri, 16 Dec 2016 12:13:23 +0000 Subject: [PATCH] JBTM-2819 Clarify the semantics of clearing a heuristic --- product/en-US/development_guide/tools.xml | 62 +++++++++++------------ 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/product/en-US/development_guide/tools.xml b/product/en-US/development_guide/tools.xml index 91a109fa..7bd356b9 100644 --- a/product/en-US/development_guide/tools.xml +++ b/product/en-US/development_guide/tools.xml @@ -107,7 +107,7 @@ read-resource CLI command on this element to see the participants of the transaction. Participants are - identified by their JNDI names. + identified by their JNDI names (or some other unique identifier if the JNDI name is not available). /subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9/participants=java\:\/JmsXA:read-resource @@ -121,7 +121,7 @@ "eis-product-name" => "HornetQ", "eis-product-version" => "2.0", "jndi-name" => "java:/JmsXA", - "status" => "HEURISTIC", + "status" => "HEURISTIC_HAZARD", "type" => "/StateManager/AbstractRecord/XAResourceRecord" } } @@ -130,9 +130,9 @@ The outcome status shown here is in a - HEURISTIC + HEURISTIC_HAZARD state and is eligible for recovery. Refer to - + for more details. @@ -170,36 +170,32 @@ Each transaction log participant supports a :delete operation which -Normally you would leave participant log management to the transaction log that owns it or to the recovery system. However, this delete operation is provided for those cases where you know it is safe to do so and, in the case of heuristically completed XA resources, you wish to trigger a forget call so that the XA resource vendors' logs are cleaned correctly. By default, if this forget call fails then the delete operation will fail. The system administrator may override this behaviour by setting a system property: -ObjectStoreEnvironmentBean.ignoreMBeanHeuristics to the value true. +Normally you would leave participant log management to the transaction log that owns it or to the recovery system. However, this delete operation for participant logs is provided for those cases where you know it is safe to do so and, in the case of heuristically completed XA resources, you wish to trigger a forget call so that the XA resource vendors' logs are cleaned correctly. By default, if this forget call fails then the delete operation will still succeed. The system administrator may override this behaviour by setting a system property: + ObjectStoreEnvironmentBean.ignoreMBeanHeuristics to the value false. - - Recover a transaction. + + Recover a transaction participant. - Each transaction log supports recovery via the + Each transaction participant log may support recovery via the :recover - CLI command. + CLI command if it is in a heuristic state. Recovery of Heuristic Transactions and Participants - If the transaction's status is - HEURISTIC - , the recovery operation changes the state to + If the transaction participant's status is + HEURISTIC or + HEURISTIC_HAZARD or + HEURISTIC_MIXED + then the recover operation changes the state to PREPARE and - triggers a recovery attempt. - - - - - If one of the transaction participants is in a heuristic state, the recovery - operation tries to replay the + triggers a recovery attempt by replaying the commit operation. If successful, the participant is removed from the transaction log. You @@ -356,22 +352,22 @@ Normally you would leave participant log management to the transaction log that "eis-product-name" => "HornetQ", "eis-product-version" => "2.0", "jndi-name" => "java:/JmsXA", - "status" => "HEURISTIC", + "status" => "HEURISTIC_HAZARD", "type" => "/StateManager/AbstractRecord/XAResourceRecord" The status attribute shown in this example is in a - HEURISTIC + HEURISTIC_HAZARD state and is eligible for recovery. Refer to - + for more details. - Delete a transaction. + Delete a transaction or transaction participant. MBeans for transaction logs and participants contain a remove operation. Invoke @@ -387,27 +383,29 @@ Normally you would leave participant log management to the transaction log that is not an exclusive resource, -Normally you would leave participant log management to the transaction log that owns it or to the recovery system. However, this remove operation for participant logs is provided for those cases where you know it is safe to do so and, in the case of heuristically completed XA resources, you wish to trigger a forget call so that the XA resource vendors' logs are cleaned correctly. By default, if this forget call fails then the delete operation will fail. The system administrator may override this behaviour by setting a system property: - ObjectStoreEnvironmentBean.ignoreMBeanHeuristics to the value true. +Normally you would leave participant log management to the transaction log that owns it or to the recovery system. However, this remove operation for participant logs is provided for those cases where you know it is safe to do so and, in the case of heuristically completed XA resources, you wish to trigger a forget call so that the XA resource vendors' logs are cleaned correctly. By default, if this forget call fails then the delete operation will still succeed. The system administrator may override this behaviour by setting a system property: + ObjectStoreEnvironmentBean.ignoreMBeanHeuristics to the value false. - + Recover a transaction. - Transaction participants supports recovery via the + Transaction participants support recovery via the clearHeuristic operation. - Recovery of Heuristic Transactions and Participants + Recovery of Heuristic Participants - If the transaction's status is - HEURISTIC - , the clearHeuristic operation changes the state to + If the transaction participant's status is + HEURISTIC or + HEURISTIC_HAZARD or + HEURISTIC_MIXED + then the clearHeuristic operation changes the state to PREPARED.