Narayana Transaction Processing Engine

This repository contains the Software Transactional Memory (STM) implementation built using core Narayana features. It provides transactional memory capabilities that can be used for managing shared state in a concurrent environment.

For detailed technical documentation, visit the official Narayana documentation site. Note that this STM implementation also serves as the foundation for the Vert.x transaction work found in the TransactionalVert.x project.

Narayana provides RESTful interfaces to its Transaction Manager to support atomic transactions over HTTP. This implementation follows the RESTAT protocol (based on the RESTAT specification draft).

These interfaces allow developers to achieve ACID properties (Atomicity, Consistency, Isolation, Durability) in web applications, particularly when managing multiple or remote resources. This is useful for ensuring that multiple reads or writes remain consistent even in the presence of network or server failures. Even for read-only operations, using these interfaces ensures that a user views a consistent snapshot of the server state.

The XML Transaction Service (XTS) is a component of Narayana designed to coordinate private and public Web Services within a business transaction. It provides a reliable way for business partners to manage complex, multi-service interactions, ensuring data integrity across multiple enterprises.

Key capabilities include:

• Spanning transactions across multiple Web Services.
• Managing long-running business processes.
• Ensuring that if one part of a multi-service process fails, the entire transaction can be reversed to a consistent state (atomicity).

To use XTS, your environment must be capable of hosting JaxWS endpoints (such as an application server like {appServer}), as XTS uses JaxWS to provide the active components required for the underlying protocols.

The Vert.x STM Module exposes the Narayana STM (Software Transactional Memory) implementation for Vert.x applications. It allows you to manage transactional state within a single address space using annotations and a Container.

Important Note: This is NOT for distributed transactions. Transaction contexts do not flow between address spaces. It is designed for local concurrency control within a Vert.x instance.

Software Transactional Memory (STM) in Narayana provides a way to manage object state in highly concurrent environments with ACID-like properties (Atomicity, Consistency, Isolation), though Durability is typically relaxed (volatile).

Key Benefits:

• Concurrency Control: Safely manages conflicts between threads using either Pessimistic (default, blocking) or Optimistic (MVCC, abort-on-conflict) isolation models.
• Performance: By avoiding persistent storage (unless configured), updates to volatile state are extremely fast.
• Composability: STM objects can be easily composed into larger transactional units, supporting nested transactions where sub-transactions can be rolled back by a parent.
• Low Overhead: Allows 'plain old language objects' to become STM-aware with minimal code changes via annotations.

Transaction Bridging is the process of linking the JavaEE (JTA) and Web Services (WS-AT) transaction domains. Narayana's txbridge component provides bi-directional linkage, allowing a single transaction to span business logic designed for either transaction type.

This enables scenarios such as:

• Exposing existing JavaEE transactional business logic (e.g., EJBs) as transactional Web Services.
• Allowing JavaEE transactional components to utilize transactional Web Services.

Existing business logic does not need to be modified to operate within the scope of a foreign transaction type, as the bridge masks the differences in method signatures, exception types, and protocols.

Narayana provides atomic transactions that ensure data integrity across multiple datasources using the ACID model:

• Atomicity: The transaction either completes successfully (commits) or all its effects are undone (aborts/rolls back).
• Consistency: Transactions preserve application-specific invariants and produce consistent results.
• Isolation: Intermediate states of a transaction are not visible to others, and transactions appear to execute serially.
• Durability: Once a transaction is committed, its effects are permanent and survive system failures.

A transaction can be terminated in two ways: committed (changes are made durable on stable storage) or aborted (all changes are undone).

Heuristic decisions occur when a participant unilaterally commits or aborts a transaction without waiting for the coordinator. If a participant makes a heuristic decision, the following exceptions may be raised during commit/abort:

• HeuristicRollback: The resource already unilaterally rolled back.
• HeuristicCommit: The resource already unilaterally committed.
• HeuristicMixed: Some updates committed while others rolled back.
• HeuristicHazard: The outcome of some updates is unknown (either all committed or all rolled back).