Introduction

AllegroGraph now supports two-phase commits when managed by an external transaction coordinator such as the Atomikos Transaction Essentials Transaction Manager (see https://www.atomikos.com/Main/TransactionsEssentials).

Two-phase commit concepts

Wikipedia defines the two-phase commit protocol as 

In transaction processing, databases, and computer networking, the  
two-phase commit protocol (2PC) is a type of atomic commitment  
protocol (ACP). It is a distributed algorithm that coordinates all  
the processes that participate in a distributed atomic transaction  
on whether to commit or abort (roll back) the transaction (it is a  
specialized type of consensus protocol).

When used with an external transaction coordinator, AllegroGraph can ensure that commits in specified repositories in AllegroGraph (in one or more running servers) and in external non-AllegroGraph databases will all happen or will all fail (be rolled back).

Transaction managers are supplied by companies other than Franz Inc. (the supplier of AllegroGraph). One such supplier is Atomikos, who supply the Atomikos Transaction Essentials transaction manager. This is the transaction manager with which AllegroGraph's Two-phase Commit utility is certified.

Two-phase committing has a number of well-known disadvantages, perhaps the most important of which is that it is a blocking protocol: once the commit procedure is started, none of the participants can do any further commits until all have either indicated their readiness to commit and the commit order has gone out from the transaction coordinator or the transaction coordinator calls for a roll back and the roll back is finished. If any participant (or, after sending the "ready to commit?" message, the transaction coordinator) fails or becomes unavailable, further commits on the affected AllegroGraph repositories are blocked until the prepared commit is completed or rolled back. (Non-AllegroGraph participant databases are presumably similarly restricted. See their documentation for more information.)

Because of this blocking potential, users need special permission to initiate a 2PC. See the Managing Users document, particularly the section on User Permissions and Access Controls for more information on user permissions and how they are set. Users with superuser privileges can always initiate a 2PC.

Two-phase Commit Example

There is a complete example using two-phase commit and the Atomikos Transaction Essentials transaction manager among the tutorials included with the AllegroGraph Java client download.

The AllegroGraph Java client is not part of the regular AllegroGraph download. Go to the AllegroGraph Java client GitHub page and follow the instructions there.

Once downloaded, you will find the two-phase commit example in the tutorials/2pc/ directory.

To run the tutorial start an AllegroGraph 8.3.0 server and open a shell in tutorials/2pc/.

The example reads the host, port, user, and password from the environment variables AGRAPH_HOST, AGRAPH_PORT, AGRAPH_USER, and AGRAPH_PASS. If any variable is unset, defaults (in order "localhost", "10035", "test" and "xyzzy") are used. Set the appropriate environment variables as necessary. The user must either be a superuser or have 2pc privileges (see the General permissions section of the Managing Users document for details on user permissions and privleges).

Now perform the following steps:

  1. Compile the example: 
    2. mvn compile
  2. Run the example: 
    3. mvn exec:java -Dexec.mainClass="com.franz.tutorials.tpc.TwoPhaseCommitExample"

Notes about the test program: