diff --git a/source/includes/write/transactions/transactions.java b/source/includes/write/transactions/transactions.java new file mode 100644 index 00000000..39da369d --- /dev/null +++ b/source/includes/write/transactions/transactions.java @@ -0,0 +1,28 @@ +MongoClient mongoClient = MongoClients.create(settings); + +MongoDatabase restaurantsDatabase = mongoClient.getDatabase("sample_restaurants"); +MongoCollection restaurants = restaurantsDatabase.getCollection("restaurants"); +MongoDatabase moviesDatabase = mongoClient.getDatabase("sample_mflix"); +MongoCollection movies = moviesDatabase.getCollection("movies"); + +Mono.from(mongoClient.startSession()) + .flatMap(session -> { + // Begins the transaction + session.startTransaction(); + + // Inserts documents in the given order + return Mono.from(restaurants.insertOne(session, new Document("name", "Reactive Streams Pizza").append("cuisine", "Pizza"))) + .then(Mono.from(movies.insertOne(session, new Document("title", "Java: Into the Streams").append("type", "Movie")))) + // Commits the transaction + .flatMap(result -> Mono.from(session.commitTransaction()) + .thenReturn(result)) + .onErrorResume(error -> Mono.from(session.abortTransaction()).then(Mono.error(error))) + .doFinally(signalType -> session.close()); + }) + // Closes the client after the transaction completes + .doFinally(signalType -> mongoClient.close()) + // Prints the results of the transaction + .subscribe( + result -> System.out.println("Transaction succeeded"), + error -> System.err.println("Transaction failed: " + error) + ); \ No newline at end of file diff --git a/source/write-data-to-mongo.txt b/source/write-data-to-mongo.txt index 5729eb2b..2fdbc348 100644 --- a/source/write-data-to-mongo.txt +++ b/source/write-data-to-mongo.txt @@ -27,6 +27,7 @@ Write Data to MongoDB /write/replace-documents /write/write-delete-documents /write/bulk-writes + /write/transactions /write/store-large-docs /write/write-concern /write/command diff --git a/source/write/transactions.txt b/source/write/transactions.txt new file mode 100644 index 00000000..3aa637b8 --- /dev/null +++ b/source/write/transactions.txt @@ -0,0 +1,133 @@ +.. _java-rs-transactions: + +============ +Transactions +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: ACID, write, consistency, code example + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to perform +**transactions**. Transactions allow you to run a series of operations that do +not apply until all data changes are successful. If any operation in the +transaction fails, the driver cancels the transaction and discards all data +changes without ever becoming visible. + +In MongoDB, transactions run within logical **sessions**. A +session is a grouping of related +read or write operations that you intend to run sequentially. With sessions, you can +enable :manual:`causal consistency +` for a +group of operations, and run :website:`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 ``MongoClient`` +instance as a ``ClientSession`` type. We recommend that you reuse your client for +multiple sessions and transactions instead of instantiating a new client each +time. + +.. warning:: + + Use a ``ClientSession`` only with the ``MongoClient`` (or associated + ``MongoDatabase`` or ``MongoCollection``) that created it. Using a ``ClientSession`` with + a different ``MongoClient`` results in operation errors. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``sample_restaurants.restaurants`` and ``sample_mflix.movies`` collections +from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:ref:``. + +.. include:: includes/reactor-note.rst + +Transaction Methods +------------------- + +Create a ``ClientSession`` by using the ``startSession()`` method on your ``MongoClient`` +instance. You can then modify the session state by using the methods provided by +the ``ClientSession``. The following table details the methods you can use to +manage your transaction: + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``startTransaction()`` + - | Starts a new transaction, configured with the given options, on + this session. Throws an exception if there is already + a transaction in progress for the session. To learn more about + this method, see the :manual:`startTransaction() page + ` in the {+mdb-server+} manual. + + * - ``abortTransaction()`` + - | Ends the active transaction for this session. Throws an exception + if there is no active transaction for the session or if the + transaction is already committed or ended. To learn more about + this method, see the :manual:`abortTransaction() page + ` in the {+mdb-server+} manual. + + * - ``commitTransaction()`` + - | Commits the active transaction for this session. Throws an exception + if there is no active transaction for the session or if the + transaction was ended. To learn more about + this method, see the :manual:`commitTransaction() page + ` in the {+mdb-server+} manual. + +Transaction Example +------------------- + +The following example demonstrates how to create a session, create a +transaction, and insert documents into multiple collections in one transaction. +The code executes the following steps: + +1. Creates a session from the client by using the ``startSession()`` method +#. Starts a transaction by using the ``startTransaction()`` method +#. Inserts documents into the ``restaurants`` and ``movies`` collections +#. Commits the transaction by using the ``commitTransaction()`` method + +.. literalinclude:: /includes/write/transactions/transactions.java + :language: java + :copyable: + :emphasize-lines: 26, 29, 33-36, 38 + +Additional Information +---------------------- + +To learn more about the concepts mentioned in this guide, see the +following pages in the Server manual: + +- :manual:`Transactions ` +- :manual:`Server Sessions ` +- :manual:`Causal Consistency ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the types or methods discussed in this +guide, see the following API Documentation: + +- `MongoClient <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClient.html>`__ +- `startSession() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClient.html#startSession()>`__ +- `startTransaction() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/ClientSession.html#startTransaction()>`__ +- `abortTransaction() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/ClientSession.html#abortTransaction()>`__ +- `commitTransaction() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/ClientSession.html#commitTransaction()>`__