add transaction page and code snippet

Author: stephmarie17

source/fundamentals.txt

@@ -20,6 +20,7 @@ Fundamentals
    /fundamentals/aggregation
    /fundamentals/aggregation-expression-operations
    /fundamentals/indexes
+   /fundamentals/transactions
    /fundamentals/collations
    /fundamentals/logging
    /fundamentals/monitoring

source/fundamentals/transactions.txt

@@ -0,0 +1,133 @@
+============
+Transactions
+============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} to perform 
+**transactions**. :manual:`Transactions </core/transactions/>` allow
+you to run a series of operations that do not change any data until the
+transaction is committed. If any operation in the transaction returns an
+error, the driver cancels the transaction and discards all data changes
+before they ever become visible.
+
+In MongoDB, transactions run within logical **sessions**. A
+:manual:`session </reference/server-sessions/>` is a grouping of related
+read or write operations that you intend to run sequentially. Sessions
+enable :manual:`causal consistency
+</core/read-isolation-consistency-recency/#causal-consistency>` for a
+group of operations or allow you to execute operations in an
+:website:`ACID transaction </basics/acid-transactions>`. MongoDB
+guarantees that the data involved in your transaction operations remains
+consistent, even if the operations encounter unexpected errors.
+
+When using the {+driver-short+}, you can create a new session from a 
+``Client`` instance as a ``ClientSession``. We recommend that you reuse
+your client for multiple sessions and transactions instead of
+instantiating a new client each time.
+
+.. warning::
+
+   Use a ``Session`` only with the ``Client`` (or associated
+   ``Database`` or ``Collection``) that created it. Using a
+   ``Session`` with a different ``Client`` results in operation
+   errors.
+
+Methods
+-------
+
+After you start a session by using the ``startSession()`` method, you can modify
+the session state by using the method set provided by the ``Session`` interface.
+The following table describes these methods:
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Method
+     - Description
+
+   * - ``startTransaction()``
+     - | Starts a new transaction for this session with the
+         default transaction options. Use the ``TransactionOptions`` 
+         parameter to start a transaction with given options. You 
+         cannot start a transaction if there's already an active transaction
+         on the session.
+       |
+       | **Parameter**: ``transactionOptions``
+
+   * - ``abortTransaction()``
+     - | Ends the active transaction for this session. Returns an error 
+         if there is no active transaction for the
+         session or the transaction was previously ended.
+
+   * - ``commitTransaction()``
+     - | Commits the active transaction for this session. Returns an
+         error if there is no active transaction for the session or if the
+         transaction was ended.
+
+   * - ``withTransaction()``
+     - | Starts a new transaction for this session and runs the given function.
+       |
+       | **Parameter**: ``transactionBody``
+
+A ``Session`` also has methods to retrieve session properties and modify mutable 
+session properties. View the `API documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html>`__ 
+to learn more about these methods.
+
+Example
+-------
+
+The following example demonstrates how you can create a session, create a transaction, 
+and commit a multi-document insert operation through the following steps:
+
+1. Create a session from the client using the ``startSession()`` method.
+#. Set transaction options to configure transactional behavior.
+#. Use the ``withTransaction()`` method to start a transaction.
+#. Insert multiple documents. The ``withTransaction()`` method executes, commits, and aborts 
+   the transaction. If any operation results in errors, ``withTransaction()`` handles canceling
+   the transaction.
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Transactions.java
+   :language: java
+
+If you require more control over your transactions, you can use the ``startTransaction()``
+method. This method allows you to explicitly commit or abort the transaction and manually
+manage the transaction lifecycle.
+
+Additional Information
+----------------------
+
+To learn more about the concepts mentioned in this guide, see the following pages in 
+the Server manual:
+
+- :manual:`Transactions </core/transactions/>`
+- :manual:`Server Sessions </reference/server-sessions>`
+- :manual:`Read Isolation, Consistency, and Recency </core/read-isolation-consistency-recency/#causal-consistency>`
+
+To learn more about ACID compliance, see the :website:`What are ACID
+Properties in Database Management Systems? </basics/acid-transactions>`
+article on the MongoDB website.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the types or methods discussed in this
+guide, see the following API Documentation:
+
+- `ClientSession <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html>`_
+- `startTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#startTransaction()>`_
+- `commitTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#commitTransaction()>`_
+- `abortTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#abortTransaction()>`_
+- `withTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#withTransaction(com.mongodb.client.TransactionBody)>`_
+- `TransactionOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/TransactionOptions.html>`_
+- 

source/includes/fundamentals/code-snippets/Transaction.java

@@ -0,0 +1,37 @@
+import com.mongodb.*;
+import com.mongodb.client.*;
+import com.mongodb.client.model.WriteConcern;
+import org.bson.Document;
+
+import java.util.Arrays;
+
+public class Transaction {
+    public static void main(String[] args) {
+        // Connect to MongoDB
+        String connectionString = "mongodb://localhost:27017"; // Update with your MongoDB URI
+        try (MongoClient mongoClient = MongoClients.create(connectionString)) {
+            MongoDatabase database = mongoClient.getDatabase("yourDatabaseName");
+            MongoCollection<Document> collection = database.getCollection("yourCollectionName");
+
+            // Set transaction options
+            TransactionOptions txnOptions = TransactionOptions.builder()
+                    .writeConcern(WriteConcern.MAJORITY)
+                    .build();
+
+            try (ClientSession session = mongoClient.startSession()) {
+
+                // Use withTransaction and lambda for transactional operations
+                session.withTransaction(() -> {
+                    collection.insertMany(session, Arrays.asList(
+                            new Document("title", "The Bluest Eye").append("author", "Toni Morrison"),
+                            new Document("title", "Sula").append("author", "Toni Morrison"),
+                            new Document("title", "Song of Solomon").append("author", "Toni Morrison")
+                    ));
+                    return null; // Return value as expected by the lambda
+                }, txnOptions);
+            }
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+    }
+}