Understanding Heuristic Completion
This section provides a brief overview of the concept of heuristically completing XA transactions. For instructions specific to MarkLogic Server, see Heuristically Completing a MarkLogic Server Transaction.
The unit of work managed by a Resource Manager in an XA transaction is a branch. Manually intervening to force completion of a prepared XA transaction branch is making a heuristic decision, or heuristically completing the branch. The branch may be heuristically completed by either committing or rolling back the local transaction.
XA uses Two Phase Commit to commit or rollback global transactions. Normal transaction completion follows this flow:
The Transaction Manager instructs all participants to prepare to commit.
Each participant reports responds with whether or not it is ready to commit.
If all participants report prepared to commit, the Transaction Manager instructs all participants to commit.
If one or more participants is not prepared to commit, the Transaction Manager instructs all participants to roll back.
If the Transaction Manager goes down due to a failure such as loss of network connectivity or a system crash, the Transaction Manager does not remember the global transaction when it comes back up. In this case, the local transaction times out normally, or may be canceled with a normal rollback, using xdmp:transaction-rollback().
If the Transaction Manager goes down after the transaction is prepared, the Transaction Manager normally recovers and resumes the flow described above. However, it may not always be possible to wait for normal recovery.
For example, if connectivity to the Transaction Manager is lost for a long time, locks may be held unacceptably long on documents in MarkLogic Server. Under such circumstances, the administrator may heuristically complete a branch of the global transaction to release resources.
Note
Heuristic completion bypasses the Transaction Manager and the Two Phase Commit process, so it can lead to data integrity problems. Use heuristic completion only as a last resort.
The XA protocol requires a Resource Manager to remember the outcome of a heuristic decision, allowing the Transaction Manager to determine the status of the branch when it resynchronizes the global transaction.This remembered state is automatically cleaned up if the global transaction eventually completes with the same outcome as the heuristic decision.
Manual intervention may be required after a heuristic decision. If the Transaction Manager recovers and makes a different commit/rollback decision for the global transaction than the local heuristic decision for the branch, then data integrity is lost and must be restored manually.
For example, if the administrator heuristically completes a branch by committing it, but the global transaction later rolls back, then the heuristically completed branch requires manual intervention to roll back the previously committed local transaction and make the resource consistent with the other global transaction participants.
Heuristic completion is not needed in cases where a global transaction stalls prior to being prepared. In this case, the global transaction is lost and the local branches time out or otherwise fall back on normal failure mechanisms.