[ignite-3] branch main updated: IGNITE-17678 Added description for transaction changes. Fixes #1079

[sk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sk0x50 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git


The following commit(s) were added to refs/heads/main by this push:
     new 8d286cc799 IGNITE-17678 Added description for transaction changes. Fixes #1079
8d286cc799 is described below

commit 8d286cc79924f5fc56bc47f60a77c28dbea636dc
Author: IgGusev <de...@mail.ru>
AuthorDate: Tue Sep 20 13:53:06 2022 +0300

    IGNITE-17678 Added description for transaction changes. Fixes #1079
    
    Signed-off-by: Slava Koptilin <sl...@gmail.com>
---
 .../transactions/performing-transactions.adoc      | 70 +++++++++++++++++++++-
 1 file changed, 68 insertions(+), 2 deletions(-)

diff --git a/docs/_docs/transactions/performing-transactions.adoc b/docs/_docs/transactions/performing-transactions.adoc
index d3898239c9..a69986e2a5 100644
--- a/docs/_docs/transactions/performing-transactions.adoc
+++ b/docs/_docs/transactions/performing-transactions.adoc
@@ -16,9 +16,9 @@
 
 This Alpha release introduces the key-value API that provides an interface for starting and completing transactions.
 
-== Executing Transactions
+=== Synchronous Transactions
 
-Use the `igniteTransactions` class to create a transaction object and the `commit` method to send it.
+Use the `igniteTransactions` class to create a transaction object, and the `commit` method to send it.
 
 [tabs]
 --
@@ -30,6 +30,42 @@ tx.commit()
 ----
 --
 
+You can also perform a rollback with the `rollback` command:
+
+[tabs]
+--
+tab:Java[]
+[source,java]
+----
+Transaction tx = igniteTransactions.begin();
+tx.rollback()
+----
+--
+
+
+Here is the example of a transaction that transfers money from one account to another, and handles a possible overdraft:
+
+--
+[source,java]
+----
+Transaction tx = igniteTransactions.begin();
+
+try {
+    Tuple row1 = accounts.get(tx, Tuple.create().set("accountId", 1));
+    if (row1.doubleValue("balance") - amount < 0) {
+        tx.rollback();
+        return false;
+    }
+    Tuple row2 = accounts.get(tx, Tuple.create().set("accountId", 2);
+    accounts.upsert(tx, Tuple.create().set("accountId", 1).set("balance", row1.doubleValue("balance") - amount));
+    accounts.upsert(tx, Tuple.create().set("accountId", 2).set("balance", row2.doubleValue("balance") + amount));
+    tx.commit();
+} catch (Throwable t) {
+    tx.rollback();
+}
+----
+--
+
 == Asynchronous Transactions
 
 You can also perform transactions asynchronously.
@@ -57,4 +93,34 @@ igniteTransactions.beginAsync()
         )
     ).thenCompose(Transaction::commitAsync).join();
 ----
+--
+
+
+== Implicit Transaction Management
+
+Apache Ignite 3 also provides implicit transaction managemet for dealing with simpler transactions by using the `runInTransaction` class. When using it, the following will be done automatically:
+
+- The transaction is started and substituted to the closure.
+- The transaction is committed if no exceptions were thrown during the closure.
+- The transaction will be retried in case of recoverable error. Closure must be purely functional - not causing side effects.
+
+Here is the example of a transaction that transfers money from one account to another, and handles a possible overdraft:
+
+[tabs]
+--
+tab:Java[]
+[source,java]
+----
+igniteTransactions.runInTransaction(tx -> {
+    CompletableFuture<Tuple> fut1 = view.getAsync(tx, Tuple.create().set("accountId", 1));
+    CompletableFuture<Tuple> fut2 = view.getAsync(tx, Tuple.create().set("accountId", 2)); // Read second balance concurrently
+    if (fut1.join().doubleValue("balance") - amount < 0) {
+        tx.rollback();
+        return;
+    }
+
+    view.upsertAsync(tx, Tuple.create().set("accountId", 1).set("balance", fut1.join().doubleValue("balance") - amount));
+    view.upsertAsync(tx, Tuple.create().set("accountId", 2).set("balance", fut2.join().doubleValue("balance") + amount);
+});
+----
 --
\ No newline at end of file