Copyright (c) 2005 - 2024 Franz, Incorporated

Last updated 5 December 2024 at 16:42

• Documentation Index
  • Release Notes
  • Quick Start
  • SSL/TLS Quick Start
  • Introduction
  • Setup and Configuration
    • Download
    • Server Installation
    • Server Configuration and Control
    • WebView
    • Database Upgrading
    • Managing Users
  • Server Management
    • Performance Tuning
    • Deleting Duplicate Triples
    • Purging Deleted Triples
    • Auditing
    • Managing Users
    • Replication
    • Point-in-Time Recovery
    • Transaction Log Archiving
    • Security Overview
    • Security Implementation
  • Tools
    • agtool
    • Data Loading
    • Data Export
    • Backup and Restore
    • Querying
    • RDFS++
    • Materializer
    • Event Scheduler
    • SHACL
  • Details
    • Triple Indices
    • Freetext Indices
    • Encoded IDs
    • Connection Pooling
    • N-dimensional Geospatial Overview
    • 2-D Geospatial
    • Temporal
    • Social Network
    • JavaScript
    • Datatypes
    • Data Conversion (Rapper)
    • Stored Procedures
    • Triple Attributes
    • Lineparse Format
  • Querying
    • SPARQL documentation summary
    • SPARQL Reference
    • SPIN
    • SPARQL Magic Properties
    • Prolog
  • 3rd-party tools
    • Solr text Indices
    • MongoDB integration
    • TopBraid Composer Plugin
    • Cloudera
  • Client APIs
    • Gruff
    • REST/HTTP interface
    • HTTP reference
    • Javadocs (Sesame and Jena)
    • Python API
    • Lisp Reference
    • JavaScript
  • Tutorials
    • N-dimensional Geospatial
    • SPARQL Tutorial
    • Java Sesame
    • Java Jena
    • Python Sesame
    • Lisp
    • Prolog
    • More...
  • Other
    • Conferences and Seminars
    • Source Code on Github
    • Amazon EC2
    • Copyrights
    • Change History
  • Franz, Inc.

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.1 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:

mvn compile 

2. Run the example:

mvn exec:java -Dexec.mainClass="com.franz.tutorials.tpc.TwoPhaseCommitExample" 

Notes about the test program:

• The test program starts the Apache Derby database product.

• The test program creates an AllegroGraph repository and a Derby database.

• The AllegroGraph repository is placed in the java-catalog catalog and is named test-2pc. The java-catalog must exist in AllegroGraph and so must be defined in the agraph.cfg file prior to running the example (see Server Configuration and Control for information on specifying catalogs). If the test-2pc repo exists, it will be overwritten.

• The Derby database is also named test-2pc.

• Then com.atomikos.icatch.config.Configuration.addResource() is called twice to notify the transaction manager that these resources will be involved in two phase transactions.

• An instance of the transaction manager is created by calling UserTransactionManager(). It is initialized by invoking its init() method. Then doSampleTransaction() is called. doSampleTransaction gets a connection to each resource. Then we ask the transaction manager to begin a new distributed transaction.
  

• The participants in the distributed transaction are registered by calling enlistResource() on the transaction object with the result of calling getXAResource() on each of the connections. Then we do normal operations against each of the repository connections (adding one triple to the AllegroGraph repo and a record into the Derby database).

• Then we invoke the tm.commit() method of the transaction manager object. The transaction manager performs the two phase commit operation as a result.

• We could have also called tm.rollback() to cancel the transaction. This would roll back the work on all participants.