#80 add some docs

Author: aburmeis

ChangeLog.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+- added support for transactions offering a platform transaction manager based on stream transactions (#80)
 
 ## [3.7.1] - 2022-08-19
 

src/main/java/com/arangodb/springframework/transaction/ArangoTransactionManager.java

@@ -15,8 +15,6 @@
  * Transaction manager using ArangoDB stream transactions on the
  * {@linkplain ArangoOperations#getDatabaseName()} current database} of the template.
  * Isolation level {@linkplain TransactionDefinition#ISOLATION_SERIALIZABLE serializable} is not supported.
- *
- * @see ArangoDatabase#beginStreamTransaction(StreamTransactionOptions)
  */
 public class ArangoTransactionManager extends AbstractPlatformTransactionManager {
 
@@ -26,11 +24,7 @@ public class ArangoTransactionManager extends AbstractPlatformTransactionManager
     public ArangoTransactionManager(ArangoOperations operations, QueryTransactionBridge bridge) {
         this.operations = operations;
         this.bridge = bridge;
-        setNestedTransactionAllowed(false);
-        setTransactionSynchronization(SYNCHRONIZATION_ALWAYS);
         setValidateExistingTransaction(true);
-        setGlobalRollbackOnParticipationFailure(true);
-        setRollbackOnCommitFailure(true);
     }
 
     /**
@@ -53,6 +47,7 @@ protected Object doGetTransaction() {
     /**
      * Configures the new transaction object. The resulting resource will be synchronized and the bridge will be initialized.
      *
+     * @see ArangoDatabase#beginStreamTransaction(StreamTransactionOptions)
      * @see QueryTransactionBridge
      */
     @Override
@@ -71,6 +66,8 @@ protected void doBegin(Object transaction, TransactionDefinition definition) thr
 
     /**
      * Commit the current stream transaction iff any. The bridge is cleared afterwards.
+     *
+     * @see ArangoDatabase#commitStreamTransaction(String)
      */
     @Override
     protected void doCommit(DefaultTransactionStatus status) throws TransactionException {
@@ -88,6 +85,8 @@ protected void doCommit(DefaultTransactionStatus status) throws TransactionExcep
 
     /**
      * Roll back the current stream transaction iff any. The bridge is cleared afterwards.
+     *
+     * @see ArangoDatabase#abortStreamTransaction(String)
      */
     @Override
     protected void doRollback(DefaultTransactionStatus status) throws TransactionException {
@@ -103,9 +102,14 @@ protected void doRollback(DefaultTransactionStatus status) throws TransactionExc
         }
     }
 
+    /**
+     * Check if the transaction objects has an underlying stream transaction.
+     *
+     * @see ArangoDatabase#getStreamTransaction(String)
+     */
     @Override
     protected boolean isExistingTransaction(Object transaction) throws TransactionException {
-        return transaction instanceof ArangoTransactionObject && ((ArangoTransactionObject) transaction).exists();
+        return ((ArangoTransactionObject) transaction).exists();
     }
 
     @Override

src/main/java/com/arangodb/springframework/transaction/ArangoTransactionObject.java

@@ -41,7 +41,7 @@ ArangoTransactionResource getResource() {
     }
 
     boolean exists() {
-        return resource.getStreamTransactionId() != null;
+        return getStreamTransaction() != null;
     }
 
     void configure(TransactionDefinition definition) {
@@ -116,9 +116,14 @@ private void addCollections(Collection<String> collections) {
     }
 
     private boolean isStatus(StreamTransactionStatus status) {
+        getStreamTransaction();
+        return transaction != null && transaction.getStatus() == status;
+    }
+
+    private StreamTransactionEntity getStreamTransaction() {
         if (transaction == null && resource.getStreamTransactionId() != null) {
             transaction = database.getStreamTransaction(resource.getStreamTransactionId());
         }
-        return transaction != null && transaction.getStatus() == status;
+        return transaction;
     }
 }

src/main/java/com/arangodb/springframework/transaction/TransactionAttributeTemplate.java

@@ -1,21 +1,45 @@
 package com.arangodb.springframework.transaction;
 
 import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.TransactionDefinition;
 import org.springframework.transaction.interceptor.TransactionAttribute;
 import org.springframework.transaction.support.TransactionTemplate;
 
 import java.util.Collection;
 import java.util.Collections;
+import java.util.function.Predicate;
 
+/**
+ * Template class that simplifies programmatic transaction demarcation and
+ * transaction exception handling in combination with a transaction manager using labels.
+ *
+ * @see ArangoTransactionManager
+ */
 public class TransactionAttributeTemplate extends TransactionTemplate implements TransactionAttribute {
 
+    private static final Predicate<Throwable> DEFAULT_ROLLBACK_ON = ex -> (ex instanceof RuntimeException || ex instanceof Error);
+
     private String qualifier;
     private Collection<String> labels = Collections.emptyList();
+    private Predicate<Throwable> rollbackOn = DEFAULT_ROLLBACK_ON;
+
+    public TransactionAttributeTemplate() {
+    }
 
     public TransactionAttributeTemplate(PlatformTransactionManager transactionManager) {
         super(transactionManager);
     }
 
+    public TransactionAttributeTemplate(PlatformTransactionManager transactionManager, TransactionDefinition transactionDefinition) {
+        super(transactionManager, transactionDefinition);
+        if (transactionDefinition instanceof TransactionAttribute) {
+            TransactionAttribute transactionAttribute = (TransactionAttribute) transactionDefinition;
+            setQualifier(transactionAttribute.getQualifier());
+            setLabels(transactionAttribute.getLabels());
+            setRollbackOn(transactionAttribute::rollbackOn);
+        }
+    }
+
     @Override
     public String getQualifier() {
         return qualifier;
@@ -36,6 +60,10 @@ public void setLabels(Collection<String> labels) {
 
     @Override
     public boolean rollbackOn(Throwable ex) {
-        return (ex instanceof RuntimeException || ex instanceof Error);
+        return rollbackOn.test(ex);
+    }
+
+    public void setRollbackOn(Predicate<Throwable> rollbackOn) {
+        this.rollbackOn = rollbackOn;
     }
 }