CXX-3082 Add comprehensive examples (mongocxx, Part 2)

.mci.yml

@@ -10,9 +10,10 @@ exec_timeout_secs: 3600
 variables:
 
     # If updating mongoc_version_minimum, also update:
-    # - the default value of --c-driver-build-ref in etc/make_release.py
     # - LIBBSON_REQUIRED_VERSION and LIBMONGOC_REQUIRED_VERSION in CMakeLists.txt
     # - the version of pkg:github/mongodb/mongo-c-driver in etc/purls.txt
+    # - the default value of --c-driver-build-ref in etc/make_release.py
+    # Only LIBMONGOC_DOWNLOAD_VERSION needs to be updated when pinning to an unreleased commit.
     mongoc_version_minimum: &mongoc_version_minimum "1.28.0"
 
     integration_matrix:
@@ -1292,7 +1293,7 @@ task_groups:
           binary: bash
           args: [-c, rm -rf *]
 
-  - name: test_atlas_task_group_search_indexes
+  - name: test_atlas_task_group_search_indexes_7.0
     setup_group:
       - func: "setup"
       - func: "clone_drivers-evergreen-tools"
@@ -1320,6 +1321,34 @@ task_groups:
     tasks:
       - test_search_index_helpers
 
+  - name: test_atlas_task_group_search_indexes_8.0
+    setup_group:
+      - func: "setup"
+      - func: "clone_drivers-evergreen-tools"
+      - command: subprocess.exec
+        params:
+          working_dir: mongo-cxx-driver
+          binary: bash
+          add_expansions_to_env: true
+          env:
+            MONGODB_VERSION: '8.0'
+          args: [-c, "${DRIVERS_TOOLS}/.evergreen/atlas/setup-atlas-cluster.sh"]
+      - command: expansions.update
+        # Expected to set MONGODB_URI expansion.
+        params:
+          file: mongo-cxx-driver/atlas-expansion.yml
+    teardown_group:
+      - command: subprocess.exec
+        params:
+          working_dir: mongo-cxx-driver
+          binary: bash
+          add_expansions_to_env: true
+          args: [-c, "${DRIVERS_TOOLS}/.evergreen/atlas/teardown-atlas-cluster.sh"]
+    setup_group_can_fail_task: true
+    setup_group_timeout_secs: 1800
+    tasks:
+      - test_search_index_helpers
+
 
 #######################################
 #           Buildvariants             #
@@ -1360,6 +1389,14 @@ buildvariants:
           <<: *integration_matrix_expansions_linux
       <<: *integration_matrix_tasks_single
 
+    - name: integration-ubuntu2004-8.0-single
+      display_name: "Ubuntu 20.04 Debug (MongoDB 8.0)"
+      run_on: ubuntu2004-large
+      expansions:
+          mongodb_version: "8.0"
+          <<: *integration_matrix_expansions_linux
+      <<: *integration_matrix_tasks_single
+
     - name: integration-ubuntu2004-7.0-single
       display_name: "Ubuntu 20.04 Debug (MongoDB 7.0)"
       run_on: ubuntu2004-large
@@ -1416,6 +1453,14 @@ buildvariants:
           <<: *integration_matrix_expansions_windows_vs2019
       <<: *integration_matrix_tasks_single
 
+    - name: integration-vs2019-8.0-single
+      display_name: "Windows (VS 2019) Debug (MongoDB 8.0)"
+      run_on: windows-vsCurrent-large
+      expansions:
+          mongodb_version: "8.0"
+          <<: *integration_matrix_expansions_windows_vs2019
+      <<: *integration_matrix_tasks_single
+
     - name: integration-vs2019-7.0-single
       display_name: "Windows (VS 2019) Debug (MongoDB 7.0)"
       run_on: windows-vsCurrent-large
@@ -1472,6 +1517,14 @@ buildvariants:
           <<: *integration_matrix_expansions_linux
       <<: *integration_matrix_tasks_replica
 
+    - name: integration-ubuntu2004-8.0-replica
+      display_name: "Ubuntu 20.04 Debug replica set (MongoDB 8.0)"
+      run_on: ubuntu2004-large
+      expansions:
+          mongodb_version: "8.0"
+          <<: *integration_matrix_expansions_linux
+      <<: *integration_matrix_tasks_replica
+
     - name: integration-ubuntu2004-7.0-replica
       display_name: "Ubuntu 20.04 Debug replica set (MongoDB 7.0)"
       run_on: ubuntu2004-large
@@ -1528,6 +1581,14 @@ buildvariants:
           <<: *integration_matrix_expansions_linux
       <<: *integration_matrix_tasks_sharded
 
+    - name: integration-ubuntu2004-8.0-sharded
+      display_name: "Ubuntu 20.04 Debug sharded cluster (MongoDB 8.0)"
+      run_on: ubuntu2004-large
+      expansions:
+          mongodb_version: "8.0"
+          <<: *integration_matrix_expansions_linux
+      <<: *integration_matrix_tasks_sharded
+
     - name: integration-ubuntu2004-7.0-sharded
       display_name: "Ubuntu 20.04 Debug sharded cluster (MongoDB 7.0)"
       run_on: ubuntu2004-large
@@ -1941,7 +2002,24 @@ buildvariants:
       tasks:
         - name: compile_without_tests
         - name: compile_macro_guard_tests
-        - name: test_atlas_task_group_search_indexes
+
+    - name: atlas-search-indexes-7.0
+      display_name: "Atlas Search Indexes (7.0)"
+      expansions:
+        build_type: "Debug"
+      run_on:
+        - ubuntu2004-build
+      tasks:
+        - name: test_atlas_task_group_search_indexes_7.0
+
+    - name: atlas-search-indexes-8.0
+      display_name: "Atlas Search Indexes (8.0)"
+      expansions:
+        build_type: "Debug"
+      run_on:
+        - ubuntu2004-build
+      tasks:
+        - name: test_atlas_task_group_search_indexes_8.0
 
     - name: ubuntu2004-debug-gcc
       display_name: "Ubuntu 20.04 Debug (GCC)"

CMakeLists.txt

@@ -54,7 +54,7 @@ set(LIBBSON_REQUIRED_ABI_VERSION 1.0)
 
 # Also update etc/purls.txt.
 set(LIBMONGOC_REQUIRED_VERSION 1.28.0)
-set(LIBMONGOC_DOWNLOAD_VERSION 1.28.0)
+set(LIBMONGOC_DOWNLOAD_VERSION d934cd5de55af65220816e4fd01ce3f9c0ef1cd4) # TODO: update to 1.29.0 once it is released.
 set(LIBMONGOC_REQUIRED_ABI_VERSION 1.0)
 
 set(NEED_DOWNLOAD_C_DRIVER false)

docs/api/mongocxx/examples/change_streams.md

@@ -0,0 +1,23 @@
+# Obtain a Change Stream
+
+## From a Client
+
+@snippet api/mongocxx/examples/change_streams/from_client.cpp Example
+
+## From a Database
+
+@snippet api/mongocxx/examples/change_streams/from_database.cpp Example
+
+## From a Collection
+
+@snippet api/mongocxx/examples/change_streams/from_collection.cpp Example
+
+# Use a Change Stream
+
+## Basic Usage
+
+@snippet api/mongocxx/examples/change_streams/basic.cpp Example
+
+## With Pipeline
+
+@snippet api/mongocxx/examples/change_streams/with_pipeline.cpp Example

docs/api/mongocxx/examples/client_sessions.md

@@ -0,0 +1,22 @@
+# Create a Client Session
+
+## Basic Usage
+
+@snippet api/mongocxx/examples/client_sessions/create/basic.cpp Example
+
+## With Options
+
+@snippet api/mongocxx/examples/client_sessions/create/with_options.cpp Example
+
+# Use a Client Session
+
+@see
+- [Causal Consistency and Read and Write Concerns (MongoDB Manual)](https://www.mongodb.com/docs/manual/core/causal-consistency-read-write-concerns/)
+
+## Basic Usage
+
+@snippet api/mongocxx/examples/client_sessions/use/basic.cpp Example
+
+## With Transactions
+
+@snippet api/mongocxx/examples/client_sessions/use/transactions.cpp Example

docs/api/mongocxx/examples/collections.md

@@ -26,18 +26,50 @@
 
 # Index Operations
 
-## List Indexes
+## On a Collection
+
+### List Indexes
 
 @snippet examples/api/mongocxx/examples/collections/list_indexes.cpp Example
 
-## Create an Index
+### Create an Index
 
 @snippet examples/api/mongocxx/examples/collections/create_index.cpp Example
 
-## Create an Index With Options
+### Create an Index With Options
 
 @snippet examples/api/mongocxx/examples/collections/create_index_with_options.cpp Example
 
+## With an Index View
+
+### Obtain an Index View
+
+@snippet examples/api/mongocxx/examples/collections/index_views/indexes.cpp Example
+
+### List Indexes
+
+@snippet examples/api/mongocxx/examples/collections/index_views/list.cpp Example
+
+### Create an Index
+
+@snippet examples/api/mongocxx/examples/collections/index_views/create.cpp Example
+
+### Create an Index With Options
+
+@snippet examples/api/mongocxx/examples/collections/index_views/create_with_options.cpp Example
+
+### Create Multiple Indexes
+
+@snippet examples/api/mongocxx/examples/collections/index_views/create_many.cpp Example
+
+### Drop an Index
+
+@snippet examples/api/mongocxx/examples/collections/index_views/drop.cpp Example
+
+### Drop All Indexes
+
+@snippet examples/api/mongocxx/examples/collections/index_views/drop_all.cpp Example
+
 # Document Operations
 
 ## Query the Number of Documents
@@ -111,3 +143,17 @@
 ## Execute an Aggregation Operation
 
 @snippet examples/api/mongocxx/examples/collections/aggregate.cpp Example
+
+# Error Handling
+
+## Invalid Collection
+
+@snippet examples/api/mongocxx/examples/collections/incompatible_options.cpp Example
+
+## Invalid Parameter
+
+@snippet examples/api/mongocxx/examples/collections/invalid_parameter.cpp Example
+
+## Incompatible Options
+
+@snippet examples/api/mongocxx/examples/collections/incompatible_options.cpp Example

docs/api/mongocxx/examples/databases.md

@@ -41,3 +41,9 @@
 ## List Collection Names in the Database
 
 @snippet examples/api/mongocxx/examples/databases/list_collection_names.cpp Example
+
+# Error Handling
+
+## Invalid Database
+
+@snippet examples/api/mongocxx/examples/databases/invalid.cpp Example

examples/api/db_lock.cpp

@@ -21,6 +21,7 @@
 #include <mongocxx/collection.hpp>
 #include <mongocxx/database.hpp>
 
+#include <examples/api/concern.hh>
 #include <examples/api/db_lock.hh>
 #include <examples/macros.hh>
 
@@ -32,14 +33,23 @@ std::mutex db_locks_mut;
 }  // namespace
 
 db_lock::~db_lock() {
-    this->get().drop();
+    this->get().drop(wc_majority());
 }
 
 db_lock::db_lock(mongocxx::client& client, std::string name) : _client_ptr(&client), _name(name) {
+    // https://www.mongodb.com/docs/manual/reference/limits/#mongodb-limit-Length-of-Database-Names
+    static constexpr std::size_t db_name_size_max = 63u;
+
+    if (_name.size() > db_name_size_max) {
+        // Strip prefix, which is more likely to be common across components.
+        // e.g. `api_mongocxx_examples_very_long_component_name` -> `g_component_name` (length: 16).
+        _name = std::move(_name).substr(_name.size() - db_name_size_max, db_name_size_max);
+    }
+
     ((void)std::lock_guard<std::mutex>{db_locks_mut},
      _lock = std::unique_lock<std::mutex>(db_locks[name]));
 
-    this->get().drop();
+    this->get().drop(wc_majority());
 }
 
 mongocxx::database db_lock::get() const& {

examples/api/mongocxx/examples/change_streams/basic.cpp

@@ -0,0 +1,79 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <chrono>
+
+#include <bsoncxx/json.hpp>
+
+#include <mongocxx/client.hpp>
+#include <mongocxx/collection.hpp>
+#include <mongocxx/database.hpp>
+#include <mongocxx/uri.hpp>
+
+#include <examples/api/concern.hh>
+#include <examples/api/db_lock.hh>
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(mongocxx::database db) {
+    mongocxx::collection coll = db.create_collection("coll");
+
+    mongocxx::change_stream stream = coll.watch();
+
+    auto result_opt = coll.insert_one(bsoncxx::from_json(R"({"x": 1})"));
+    EXPECT(result_opt);
+    auto id = result_opt->inserted_id();
+
+    int count = 0;
+    auto now = [] { return std::chrono::steady_clock::now(); };
+    auto start = now();
+
+    // periodicNoopIntervalSecs: 10 (default)
+    while (count < 1 && now() - start < std::chrono::seconds(10)) {
+        for (bsoncxx::document::view change : stream) {
+            ++count;
+
+            EXPECT(change["operationType"]);
+            EXPECT(change["operationType"].get_string().value.compare("insert") == 0);
+
+            EXPECT(change["ns"]);
+            EXPECT(change["ns"]["db"].get_string().value == db.name());
+            EXPECT(change["ns"]["coll"].get_string().value == coll.name());
+
+            EXPECT(change["fullDocument"]);
+            EXPECT(change["fullDocument"]["x"]);
+
+            EXPECT(change["documentKey"]);
+            EXPECT(change["documentKey"]["_id"].get_oid().value == id);
+        }
+    }
+
+    EXPECT(count == 1);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT_FOR_REPLICA() {
+    mongocxx::client client{mongocxx::uri{}};
+
+    {
+        db_lock guard{client, EXAMPLES_COMPONENT_NAME_STR};
+
+        example(set_rw_concern_majority(guard.get()));
+    }
+}