Skip to content

Commit 1654ab9

Browse files
rustagirrustagir
authored
Merge pull request #7 from rustagir/DOCSP-37773-tutorials-connect
DOCSP-37773: tutorials > connect
2 parents 8a21b64 + 9bb97cb commit 1654ab9

File tree

4 files changed

+272
-0
lines changed

4 files changed

+272
-0
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,6 @@ driver-short = "Java RS driver"
1212
driver-long = "MongoDB Java Reactive Streams Driver"
1313
version = "5.0"
1414
full-version = "{+version+}.0"
15+
api = "https://mongodb.github.io/mongo-java-driver/5.0/apidocs/mongodb-driver-reactivestreams/com/mongodb/reactivestreams"
1516
rs-docs = "https://www.reactive-streams.org/reactive-streams-1.0.4-javadoc/org/reactivestreams"
1617
driver-source-gh = "https://github.com/mongodb/mongo-java-driver"

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Java RS Driver
88

99
/installation
1010
/get-started
11+
/tutorials
1112
View the Source <https://github.com/mongodb/mongo-java-driver>
1213

1314
Have a lovely day!

‎source/tutorials.txt

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. _javars-tutorials:
2+
3+
=========
4+
Tutorials
5+
=========
6+
7+
.. toctree::
8+
9+
/tutorials/connect/
10+

‎source/tutorials/connect.txt

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
.. _javars-connect:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. TODO .. toctree:: /tutorials/...
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
This guide describes how to use the {+driver-short+} to connect to
16+
MongoDB.
17+
18+
Use the ``MongoClients.create()`` method to make a connection to a
19+
running MongoDB deployment.
20+
21+
.. important::
22+
23+
The following examples do not provide an exhaustive list of
24+
ways to instantiate a ``MongoClient``. For a complete list of the
25+
``MongoClient`` factory methods, see the `MongoClients API
26+
documentation <{+api+}/client/MongoClients.html>`__.
27+
28+
.. note::
29+
30+
We *strongly recommended* that system keep-alive settings should
31+
be configured with shorter timeouts.
32+
33+
See the :manual:`Does TCP keepalive time affect MongoDB Deployments?
34+
</faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments->`
35+
question and answer in the Server manual FAQ for more information.
36+
37+
Prerequisites
38+
-------------
39+
40+
You must set up the following components to run the code examples in
41+
this guide:
42+
43+
- A running MongoDB deployment to connect to. For example, to
44+
connect to a standalone deployment, you must have access to a running
45+
standalone deployment.
46+
47+
- Driver dependency installed in your project. To learn how to install
48+
the driver, see the :ref:`installation guide <javars-install>`.
49+
50+
- The following import statements:
51+
52+
.. code-block:: java
53+
54+
import com.mongodb.reactivestreams.client.MongoClients;
55+
import com.mongodb.reactivestreams.client.MongoClient;
56+
import com.mongodb.MongoClientSettings;
57+
import com.mongodb.ConnectionString;
58+
import com.mongodb.ServerAddress;
59+
import com.mongodb.MongoCredential;
60+
61+
import java.util.Arrays;
62+
63+
MongoClient
64+
-----------
65+
66+
A ``MongoClient`` instance represents a pool of connections to the
67+
database. You need only one instance of ``MongoClient`` even
68+
when running multiple concurrent operations.
69+
70+
.. important::
71+
72+
Typically, you create only one ``MongoClient`` instance for a given
73+
MongoDB deployment, such as a standalone deployment, replica set, or a sharded
74+
cluster, and use the client across your application. However, if you do create
75+
multiple instances, keep the following in mind:
76+
77+
- All resource-usage limits (for example, max connections) apply to
78+
each ``MongoClient`` instance.
79+
- To dispose of an instance, call the ``MongoClient.close()`` method
80+
to clean up resources.
81+
82+
Connect to a Standalone MongoDB Deployment
83+
------------------------------------------
84+
85+
The following example shows several ways to connect to a single
86+
MongoDB deployment.
87+
88+
You can connect to a single MongoDB deployment in the following ways:
89+
90+
- Instantiate a ``MongoClient`` object without any parameters to
91+
connect to a MongoDB server running on localhost on port ``27017``:
92+
93+
.. code-block:: java
94+
95+
MongoClient mongoClient = MongoClients.create();
96+
97+
- Explicitly specify the ``hostname`` to connect to a MongoDB
98+
instance running on the specified host on port ``27017``:
99+
100+
.. code-block:: java
101+
102+
MongoClient mongoClient = MongoClients.create(
103+
MongoClientSettings.builder()
104+
.applyToClusterSettings(builder ->
105+
builder.hosts(Arrays.asList(new ServerAddress("hostOne"))))
106+
.build());
107+
108+
- Explicitly specify the ``hostname`` and the ``port``:
109+
110+
.. code-block:: java
111+
112+
MongoClient mongoClient = MongoClients.create(
113+
MongoClientSettings.builder()
114+
.applyToClusterSettings(builder ->
115+
builder.hosts(Arrays.asList(new ServerAddress("hostOne", 27018))))
116+
.build());
117+
118+
- Specify the ``ConnectionString``:
119+
120+
.. code-block:: java
121+
122+
MongoClient mongoClient = MongoClients.create("mongodb://hostOne:27017");
123+
124+
Connect to a Replica Set
125+
------------------------
126+
127+
To connect to a replica set, you must specify one or more
128+
members to the ``MongoClients.create()`` method. To learn more about
129+
replica sets, see :manual:`Replication </replication/>` in the Server
130+
manual.
131+
132+
.. note::
133+
134+
MongoDB auto-discovers the primary and secondary nodes in a replica
135+
set.
136+
137+
You can connect to a MongoDB replica set by specifying the members in
138+
a ``ConnectionString``.
139+
140+
The following example shows how to specify three members of the
141+
replica set:
142+
143+
.. code-block:: java
144+
145+
MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017,host3:27017");
146+
147+
The following example shows how to specify members of the
148+
replica set and the ``replicaSet`` option with the replica set
149+
name:
150+
151+
.. code-block:: java
152+
153+
MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myReplicaSet");
154+
155+
The following example shows how to specify a list of
156+
``ServerAddress`` instances corresponding to all of the replica
157+
set members:
158+
159+
.. code-block:: java
160+
161+
MongoClient mongoClient = MongoClients.create(
162+
MongoClientSettings.builder()
163+
.applyToClusterSettings(builder ->
164+
builder.hosts(Arrays.asList(
165+
new ServerAddress("host1", 27017),
166+
new ServerAddress("host2", 27017),
167+
new ServerAddress("host3", 27017))))
168+
.build());
169+
170+
Connect to a Sharded Cluster
171+
----------------------------
172+
173+
To connect to a sharded cluster, specify the ``mongos`` instance or
174+
instances to the ``MongoClients.create()`` method. To learn more about
175+
sharded clusters, see :manual:`Sharding </sharding/>` in the Server
176+
manual.
177+
178+
You can connect to a single ``mongos`` instance in the following ways:
179+
180+
- Specify the hostname and the port in a ``ConnectionString``:
181+
182+
.. code-block:: java
183+
184+
MongoClient mongoClient = MongoClients.create( "mongodb://localhost:27017" );
185+
186+
- Exclude connection string if the ``mongos`` is running on
187+
``localhost:27017``:
188+
189+
.. code-block:: java
190+
191+
MongoClient mongoClient = MongoClients.create();
192+
193+
You can connect to multiple ``mongos`` instances in the following ways:
194+
195+
- Specify the ``ConnectionString`` to contain their hostnames and ports:
196+
197+
.. code-block:: java
198+
199+
MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017");
200+
201+
- Specify a list of the ``ServerAddress`` objects corresponding to
202+
each instance:
203+
204+
.. code-block:: java
205+
206+
MongoClient mongoClient = MongoClients.create(
207+
MongoClientSettings.builder()
208+
.applyToClusterSettings(builder ->
209+
builder.hosts(Arrays.asList(
210+
new ServerAddress("host1", 27017),
211+
new ServerAddress("host2", 27017))))
212+
.build());
213+
214+
Connection Options
215+
------------------
216+
217+
You can specify connection settings by using either the
218+
``ConnectionString`` or ``MongoClientSettings`` types, or both.
219+
220+
For example, you can specify TLS/SSL and authentication settings in the
221+
connection string:
222+
223+
.. code-block:: java
224+
225+
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&ssl=true");
226+
227+
You can also use a ``MongoClientSettings`` instance to specify TLS/SSL
228+
and the ``MongoCredential`` type to store the authentication information:
229+
230+
.. code-block:: java
231+
232+
String user; // the username
233+
String database; // the name of the database in which the user is defined
234+
char[] password; // the password as a character array
235+
// ...
236+
237+
MongoCredential credential = MongoCredential.createCredential(user, database, password);
238+
239+
MongoClientSettings settings = MongoClientSettings.builder()
240+
.credential(credential)
241+
.applyToSslSettings(builder -> builder.enabled(true))
242+
.applyToClusterSettings(builder ->
243+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
244+
.build();
245+
246+
MongoClient mongoClient = MongoClients.create(settings);
247+
248+
In some cases, you might need to combine a connection string
249+
with programmatic configuration:
250+
251+
.. code-block:: java
252+
253+
ConnectionString connectionString = new ConnectionString("mongodb://host1:27107,host2:27017/?ssl=true");
254+
CommandListener myCommandListener = ...;
255+
MongoClientSettings settings = MongoClientSettings.builder()
256+
.addCommandListener(myCommandListener)
257+
.applyConnectionString(connectionString)
258+
.build();
259+
260+
MongoClient mongoClient = MongoClients.create(settings);

0 commit comments

Comments
 (0)