Skip to content

Commit d86690a

Browse files
mcmorisimcmorisi
authored
Merge branch 'main' into DOCSP-39705-cursors
2 parents 4dc4138 + cba57be commit d86690a

26 files changed

+1865
-317
lines changed

‎.github/workflows/check-autobuilder.yml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Check Autobuilder for Errors
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "source/**"
7+
8+
jobs:
9+
check:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v3
13+
- uses: cbush/snooty-autobuilder-check@main

‎.github/workflows/copy-compat-to-docs-shared.yml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Copy Files to docs-shared
2+
3+
on:
4+
workflow_dispatch: {} # use to manually trigger workflow
5+
push:
6+
branches:
7+
- "main"
8+
paths:
9+
- "source/includes/mongodb-compatibility-table-java-rs.rst"
10+
- "source/includes/language-compatibility-table-java-rs.rst"
11+
12+
jobs:
13+
copy-file:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v3
18+
19+
- name: Copy mongodb-compat table
20+
uses: dmnemec/copy_file_to_another_repo_action@main
21+
env:
22+
API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
23+
with:
24+
source_file: "source/includes/mongodb-compatibility-table-java-rs.rst"
25+
destination_repo: "10gen/docs-shared"
26+
destination_folder: "dbx"
27+
user_email: "[email protected]"
28+
user_name: "docs-builder-bot"
29+
commit_message: "Auto-import from docs-java-rs"
30+
31+
- name: Copy language-compat table
32+
uses: dmnemec/copy_file_to_another_repo_action@main
33+
env:
34+
API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
35+
with:
36+
source_file: "source/includes/language-compatibility-table-java-rs.rst"
37+
destination_repo: "10gen/docs-shared"
38+
destination_folder: "dbx"
39+
user_email: "[email protected]"
40+
user_name: "docs-builder-bot"
41+
commit_message: "Auto-import from docs-java-rs"

‎build.sh

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# ensures that we always use the latest version of the script
2+
if [ -f build-site.sh ]; then
3+
rm build-site.sh
4+
fi
5+
6+
7+
curl https://raw.githubusercontent.com/mongodb/docs-worker-pool/netlify-poc/scripts/build-site.sh -o build-site.sh
8+
sh build-site.sh

‎netlify.toml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[[integrations]]
2+
name = "snooty-cache-plugin"
3+
4+
# Production context: all deploys from the Production branch
5+
# set in your site’s Branches settings in the UI will inherit
6+
# these settings.
7+
[build]
8+
publish = "snooty/public"
9+
command = ". ./build.sh"

‎snooty.toml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ toc_landing_pages = [
1212
"/read-data-from-mongo/",
1313
"/write-data-to-mongo/",
1414
"/getting-started/",
15-
"/secure-your-data/"
15+
"/secure-your-data/",
16+
"/upgrade/"
1617
]
1718

1819
[constants]
@@ -27,4 +28,5 @@ java-rs = "Java Reactive Streams"
2728
string-data-type = "``String``"
2829
bool = "``boolean``"
2930
pr = "Project Reactor"
30-
mdb-server = "MongoDB Server"
31+
mdb-server = "MongoDB Server"
32+
stable-api = "Stable API"

‎source/connect-to-mongo/choose-connection-target.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,13 @@ Then, pass your connection string to the ``create()`` method constructing a ``Mo
4040
Follow the :atlas:`Atlas driver connection guide </driver-connection>`
4141
to retrieve your connection string.
4242

43-
When you connect to Atlas, we recommend using the Stable API client option to avoid
43+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
4444
breaking changes when Atlas upgrades to a new version of MongoDB Server.
45-
To learn more about the Stable API feature, see :manual:`Stable API
45+
To learn more about the {+stable-api+} feature, see :manual:`Stable API
4646
</reference/stable-api>` in the MongoDB Server manual.
4747

4848
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
49-
code uses the ``serverApi`` option to specify a Stable API version.
49+
code uses the ``serverApi`` option to specify a {+stable-api+} version.
5050

5151
.. include:: /includes/connect/connect-reactor.rst
5252

‎source/connect-to-mongo/stable-api.txt

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
.. _java-rs-stable-api:
2+
3+
==========
4+
{+stable-api+}
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: compatible, backwards, upgrade
19+
20+
.. note::
21+
22+
The {+stable-api+} feature requires {+mdb-server+} 5.0 or later.
23+
24+
Overview
25+
--------
26+
27+
In this guide, you can learn how to specify **{+stable-api+}** compatibility when
28+
connecting to a MongoDB deployment.
29+
30+
The {+stable-api+} feature forces the server to run operations with behaviors compatible
31+
with the API version you specify. Using the {+stable-api+} ensures consistent responses
32+
from the server and provides long-term API stability for your application.
33+
34+
The following sections describe how you can enable and customize {+stable-api+} for
35+
your MongoDB client. For more information about the {+stable-api+}, including a list of
36+
the commands it supports, see :manual:`Stable API </reference/stable-api/>` in the
37+
{+mdb-server+} manual.
38+
39+
Enable the {+stable-api+}
40+
-------------------------
41+
42+
To enable the {+stable-api+}, perform the following steps:
43+
44+
1. Construct a ``ServerApi`` object and specify a {+stable-api+} version. You must use
45+
a {+stable-api+} version defined in the ``ServerApiVersion`` enum.
46+
#. Construct a ``MongoClientSettings`` object using the ``MongoClientSettings.Builder`` class.
47+
#. Instantiate a ``MongoClient`` using the ``MongoClients.create()`` method and
48+
pass your ``MongoClientSettings`` instance as a parameter.
49+
50+
The following code example shows how to specify {+stable-api+} version 1:
51+
52+
.. literalinclude:: /includes/connect/stable-api.java
53+
:start-after: start-enable-stable-api
54+
:end-before: end-enable-stable-api
55+
:language: java
56+
:copyable:
57+
:dedent:
58+
59+
Once you create a ``MongoClient`` instance with the {+stable-api+}, all commands you
60+
run with the client use the specified {+stable-api+} configuration. If you must run
61+
commands using alternative configurations, create a new ``MongoClient``.
62+
63+
.. _java-rs-stable-api-options:
64+
65+
Configure the {+stable-api+}
66+
----------------------------
67+
68+
The following table describes chainable methods of the ``ServerApi.Builder`` class that
69+
you can use to customize the behavior of the {+stable-api+}.
70+
71+
.. list-table::
72+
:header-rows: 1
73+
:stub-columns: 1
74+
:widths: 25,75
75+
76+
* - Option Name
77+
- Description
78+
79+
* - ``strict()``
80+
- | **Optional**. When ``true``, if you call a command that isn't part of
81+
the declared API version, the driver raises an exception.
82+
|
83+
| Default: **false**
84+
85+
* - ``deprecationErrors()``
86+
- | **Optional**. When ``true``, if you call a command that is deprecated in the
87+
declared API version, the driver raises an exception.
88+
|
89+
| Default: **false**
90+
91+
The following code example shows how you can configure an instance of ``ServerApi``
92+
by chaining methods on the ``ServerApi.Builder``:
93+
94+
.. literalinclude:: /includes/connect/stable-api.java
95+
:start-after: start-stable-api-options
96+
:end-before: end-stable-api-options
97+
:language: java
98+
:copyable:
99+
:dedent:
100+
101+
Troubleshooting
102+
---------------
103+
104+
Unrecognized field 'apiVersion' on server
105+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106+
107+
The {+driver-short+} raises this exception if you specify an API version and connect to a
108+
MongoDB server that doesn't support the {+stable-api+}. Ensure you're connecting to a
109+
deployment running {+mdb-server+} v5.0 or later.
110+
111+
Provided apiStrict:true, but the command <operation> is not in API Version
112+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113+
114+
The {+driver-short+} raises this exception if your ``MongoClient`` runs an operation that
115+
isn't in the {+stable-api+} version you specified. To avoid this error, use an alternative
116+
operation supported by the specified {+stable-api+} version, or set the ``strict``
117+
option to ``False`` when constructing your ``ServerApi`` object.
118+
119+
API Documentation
120+
-----------------
121+
122+
For more information about using the {+stable-api+} with the {+driver-short+}, see the
123+
following API documentation:
124+
125+
- `ServerApi <{+api+}/mongodb-driver-core/com/mongodb/ServerApi.html>`__
126+
- `ServerApi.Builder <{+api+}/mongodb-driver-core/com/mongodb/ServerApi.Builder.html>`__
127+
- `ServerApiVersion <{+api+}/mongodb-driver-core/com/mongodb/ServerApiVersion.html>`__
128+
- `ServerAddress <{+api+}/mongodb-driver-core/com/mongodb/ServerAddress.html>`__
129+
- `MongoClientSettings <{+api+}/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__
130+
- `MongoClientSettings.Builder <{+api+}/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__
131+
- `MongoClients <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClients.html>`__

‎source/connect.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Connect to MongoDB
2727
/connect-to-mongo/connection-options/
2828
/connect-to-mongo/tls/
2929
/connect-to-mongo/compression/
30+
/connect-to-mongo/stable-api/
3031

3132
Overview
3233
--------

‎source/includes/connect/stable-api.java

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
package org.example;
2+
3+
import com.mongodb.ConnectionString;
4+
import com.mongodb.MongoClientSettings;
5+
import com.mongodb.ServerApi;
6+
import com.mongodb.ServerApiVersion;
7+
8+
import com.mongodb.reactivestreams.client.*;
9+
10+
public class Main {
11+
public static void main(String[] args) {
12+
// start-enable-stable-api
13+
ServerApi serverApi = ServerApi.builder()
14+
.version(ServerApiVersion.V1)
15+
.build();
16+
17+
// Replace the placeholder with your Atlas connection string
18+
String uri = "<connection string URI>";
19+
20+
MongoClientSettings settings = MongoClientSettings.builder()
21+
.applyConnectionString(new ConnectionString(uri))
22+
.serverApi(serverApi)
23+
.build();
24+
25+
try (MongoClient mongoClient = MongoClients.create(settings)) {
26+
// Perform client operations here
27+
}
28+
// end-enable-stable-api
29+
30+
// start-stable-api-options
31+
ServerApi serverApi = ServerApi.builder()
32+
.version(ServerApiVersion.V1)
33+
.strict(true)
34+
.deprecationErrors(true)
35+
.build();
36+
// end-stable-api-options
37+
}
38+
}

‎source/includes/read-ops/distinct.java

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
import com.mongodb.ConnectionString;
2+
import com.mongodb.MongoClientSettings;
3+
import com.mongodb.client.model.Filters;
4+
import com.mongodb.reactivestreams.client.*;
5+
import org.bson.Document;
6+
import org.bson.conversions.Bson;
7+
import reactor.core.publisher.Flux;
8+
9+
public class Distinct {
10+
public static void main(String[] args) {
11+
String uri = "<connection string URI>";
12+
13+
MongoClientSettings settings = MongoClientSettings.builder()
14+
.applyConnectionString(new ConnectionString(uri))
15+
.build();
16+
17+
try (MongoClient mongoClient = MongoClients.create(settings))
18+
{
19+
MongoDatabase database = mongoClient.getDatabase("sample_restaurants");
20+
MongoCollection<Document> collection = database.getCollection("restaurants");
21+
22+
// start-distinct
23+
DistinctPublisher<String> distinctPublisher = collection
24+
.distinct("borough", String.class);
25+
26+
Flux.from(distinctPublisher)
27+
.doOnNext(System.out::println)
28+
.blockLast();
29+
// end-distinct
30+
31+
// start-distinct-query
32+
Bson filter = Filters.eq("cuisine", "Italian");
33+
34+
DistinctPublisher<String> distinctPublisher = collection
35+
.distinct("borough", String.class)
36+
.filter(filter);
37+
38+
Flux.from(distinctPublisher)
39+
.doOnNext(System.out::println)
40+
.blockLast();
41+
// end-distinct-query
42+
43+
// start-distinct-comment
44+
Bson filter = Filters.and(
45+
Filters.eq("borough", "Bronx"),
46+
Filters.eq("cuisine", "Pizza")
47+
);
48+
49+
DistinctPublisher<String> distinctPublisher = collection
50+
.distinct("name", String.class)
51+
.filter(filter)
52+
.comment("Bronx pizza restaurants");
53+
54+
Flux.from(distinctPublisher)
55+
.doOnNext(System.out::println)
56+
.blockLast();
57+
// end-distinct-comment
58+
}
59+
}
60+
}

‎source/includes/read/change-streams.java

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// start-open-change-stream
2+
// Opens a change stream and prints the changes as they're received
3+
ChangeStreamPublisher<Document> changeStreamPublisher = restaurants.watch();
4+
Flux.from(changeStreamPublisher)
5+
.doOnNext(change -> System.out.println("Received change: " + change))
6+
.blockLast();
7+
// end-open-change-stream
8+
9+
// start-change-stream-pipeline
10+
// Creates a change stream pipeline
11+
List<Bson> pipeline = Arrays.asList(
12+
Aggregates.match(Filters.eq("operationType", "update"))
13+
);
14+
15+
// Opens a change stream and prints the changes as they're received
16+
ChangeStreamPublisher<Document> changeStreamPublisher = restaurants.watch(pipeline);
17+
Flux.from(changeStreamPublisher)
18+
.doOnNext(change -> System.out.println("Received change: " + change))
19+
.blockLast();
20+
// end-change-stream-pipeline
21+
22+
// start-change-stream-post-image
23+
// Creates a change stream pipeline
24+
List<Bson> pipeline = Arrays.asList(
25+
Aggregates.match(Filters.eq("operationType", "update"))
26+
);
27+
28+
// Opens a change stream and prints the changes as they're received including the full
29+
// document after the update
30+
ChangeStreamPublisher<Document> changeStreamPublisher = restaurants.watch(pipeline)
31+
.fullDocument(FullDocument.UPDATE_LOOKUP);
32+
33+
Flux.from(changeStreamPublisher)
34+
.doOnNext(change -> System.out.println("Received change: " + change))
35+
.blockLast();
36+
// end-change-stream-post-image

0 commit comments

Comments
 (0)