Skip to content

Commit efbe96b

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-39717 Transactions Page (#74)
1 parent 6ce34dc commit efbe96b

File tree

3 files changed

+162
-0
lines changed

3 files changed

+162
-0
lines changed

‎source/includes/write/transactions/transactions.java

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
MongoClient mongoClient = MongoClients.create(settings);
2+
3+
MongoDatabase restaurantsDatabase = mongoClient.getDatabase("sample_restaurants");
4+
MongoCollection<Document> restaurants = restaurantsDatabase.getCollection("restaurants");
5+
MongoDatabase moviesDatabase = mongoClient.getDatabase("sample_mflix");
6+
MongoCollection<Document> movies = moviesDatabase.getCollection("movies");
7+
8+
Mono.from(mongoClient.startSession())
9+
.flatMap(session -> {
10+
// Begins the transaction
11+
session.startTransaction();
12+
13+
// Inserts documents in the given order
14+
return Mono.from(restaurants.insertOne(session, new Document("name", "Reactive Streams Pizza").append("cuisine", "Pizza")))
15+
.then(Mono.from(movies.insertOne(session, new Document("title", "Java: Into the Streams").append("type", "Movie"))))
16+
// Commits the transaction
17+
.flatMap(result -> Mono.from(session.commitTransaction())
18+
.thenReturn(result))
19+
.onErrorResume(error -> Mono.from(session.abortTransaction()).then(Mono.error(error)))
20+
.doFinally(signalType -> session.close());
21+
})
22+
// Closes the client after the transaction completes
23+
.doFinally(signalType -> mongoClient.close())
24+
// Prints the results of the transaction
25+
.subscribe(
26+
result -> System.out.println("Transaction succeeded"),
27+
error -> System.err.println("Transaction failed: " + error)
28+
);

‎source/write-data-to-mongo.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Write Data to MongoDB
2727
/write/replace-documents
2828
/write/write-delete-documents
2929
/write/bulk-writes
30+
/write/transactions
3031
/write/store-large-docs
3132
/write/write-concern
3233
/write/run-command

‎source/write/transactions.txt

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
.. _java-rs-transactions:
2+
3+
============
4+
Transactions
5+
============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: ACID, write, consistency, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to perform
24+
**transactions**. Transactions allow you to run a series of operations that do
25+
not apply until all data changes are successful. If any operation in the
26+
transaction fails, the driver cancels the transaction and discards all data
27+
changes without ever becoming visible.
28+
29+
In MongoDB, transactions run within logical **sessions**. A
30+
session is a grouping of related
31+
read or write operations that you intend to run sequentially. With sessions, you can
32+
enable :manual:`causal consistency
33+
</core/read-isolation-consistency-recency/#causal-consistency>` for a
34+
group of operations, and run :website:`ACID transactions
35+
</basics/acid-transactions>`. MongoDB guarantees that the data involved in your
36+
transaction operations remains consistent, even if the operations encounter
37+
unexpected errors.
38+
39+
When using the {+driver-short+}, you can create a new session from a ``MongoClient``
40+
instance as a ``ClientSession`` type. We recommend that you reuse your client for
41+
multiple sessions and transactions instead of instantiating a new client each
42+
time.
43+
44+
.. warning::
45+
46+
Use a ``ClientSession`` only with the ``MongoClient`` (or associated
47+
``MongoDatabase`` or ``MongoCollection``) that created it. Using a ``ClientSession`` with
48+
a different ``MongoClient`` results in operation errors.
49+
50+
Sample Data
51+
~~~~~~~~~~~
52+
53+
The examples in this guide use the ``sample_restaurants.restaurants`` and ``sample_mflix.movies`` collections
54+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
55+
free MongoDB Atlas cluster and load the sample datasets, see the
56+
:ref:`<java-rs-getting-started>`.
57+
58+
.. include:: includes/reactor-note.rst
59+
60+
Transaction Methods
61+
-------------------
62+
63+
Create a ``ClientSession`` by using the ``startSession()`` method on your ``MongoClient``
64+
instance. You can then modify the session state by using the methods provided by
65+
the ``ClientSession``. The following table details the methods you can use to
66+
manage your transaction:
67+
68+
.. list-table::
69+
:widths: 40 60
70+
:header-rows: 1
71+
72+
* - Method
73+
- Description
74+
75+
* - ``startTransaction()``
76+
- | Starts a new transaction, configured with the given options, on
77+
this session. Throws an exception if there is already
78+
a transaction in progress for the session. To learn more about
79+
this method, see the :manual:`startTransaction() page
80+
</reference/method/Session.startTransaction/>` in the {+mdb-server+} manual.
81+
82+
* - ``abortTransaction()``
83+
- | Ends the active transaction for this session. Throws an exception
84+
if there is no active transaction for the session or if the
85+
transaction is already committed or ended. To learn more about
86+
this method, see the :manual:`abortTransaction() page
87+
</reference/method/Session.abortTransaction/>` in the {+mdb-server+} manual.
88+
89+
* - ``commitTransaction()``
90+
- | Commits the active transaction for this session. Throws an exception
91+
if there is no active transaction for the session or if the
92+
transaction was ended. To learn more about
93+
this method, see the :manual:`commitTransaction() page
94+
</reference/method/Session.commitTransaction/>` in the {+mdb-server+} manual.
95+
96+
Transaction Example
97+
-------------------
98+
99+
The following example demonstrates how to create a session, create a
100+
transaction, and insert documents into multiple collections in one transaction.
101+
The code executes the following steps:
102+
103+
1. Creates a session from the client by using the ``startSession()`` method
104+
#. Starts a transaction by using the ``startTransaction()`` method
105+
#. Inserts documents into the ``restaurants`` and ``movies`` collections
106+
#. Commits the transaction by using the ``commitTransaction()`` method
107+
108+
.. literalinclude:: /includes/write/transactions/transactions.java
109+
:language: java
110+
:copyable:
111+
:emphasize-lines: 26, 29, 33-36, 38
112+
113+
Additional Information
114+
----------------------
115+
116+
To learn more about the concepts mentioned in this guide, see the
117+
following pages in the Server manual:
118+
119+
- :manual:`Transactions </core/transactions/>`
120+
- :manual:`Server Sessions </reference/server-sessions/>`
121+
- :manual:`Causal Consistency </core/read-isolation-consistency-recency/#causal-consistency>`
122+
123+
API Documentation
124+
~~~~~~~~~~~~~~~~~
125+
126+
To learn more about any of the types or methods discussed in this
127+
guide, see the following API Documentation:
128+
129+
- `MongoClient <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClient.html>`__
130+
- `startSession() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClient.html#startSession()>`__
131+
- `startTransaction() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/ClientSession.html#startTransaction()>`__
132+
- `abortTransaction() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/ClientSession.html#abortTransaction()>`__
133+
- `commitTransaction() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/ClientSession.html#commitTransaction()>`__

0 commit comments

Comments
 (0)