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

* doxygen: apply consistent @see list syntax
* db_lock: use write concern majority when dropping locked databases
* db_lock: avoid server error due to lengthy API example component name
* runner: add support for disabling forking even when available
* runner: use bsoncxx::from_json instead of the basic builder
* examples: avoid mongocryptd conflicting with sharded clusters
* examples: add client sessions
* examples: add index views
* examples: add change streams
* examples: database error handling
* examples: add collection error handling
* Refactor API examples runner CLI argument parsing
* Add API examples runner support for filtering by component name

Author: eramongodb

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()));
+    }
+}

examples/api/mongocxx/examples/change_streams/from_client.cpp

@@ -0,0 +1,66 @@
+// 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 <bsoncxx/json.hpp>
+
+#include <mongocxx/change_stream.hpp>
+#include <mongocxx/client.hpp>
+#include <mongocxx/options/change_stream.hpp>
+#include <mongocxx/uri.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(mongocxx::client client) {
+    // Basic usage.
+    {
+        mongocxx::change_stream stream = client.watch();
+
+        EXPECT(stream.get_resume_token());
+    }
+
+    // With options.
+    {
+        mongocxx::options::change_stream opts;
+
+        opts.batch_size(1);
+        // ... other change stream options.
+
+        mongocxx::change_stream stream = client.watch(opts);
+
+        EXPECT(stream.get_resume_token());
+    }
+
+    // With a pipeline.
+    {
+        mongocxx::pipeline pipeline;
+
+        pipeline.match(bsoncxx::from_json(R"({"operationType": "insert"})"));
+        // ... other pipeline options.
+
+        mongocxx::change_stream stream = client.watch(pipeline);
+
+        EXPECT(stream.get_resume_token());
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT_FOR_REPLICA() {
+    example(mongocxx::client{mongocxx::uri{}});
+}

examples/api/mongocxx/examples/change_streams/from_collection.cpp

@@ -0,0 +1,73 @@
+// 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 <bsoncxx/json.hpp>
+
+#include <mongocxx/change_stream.hpp>
+#include <mongocxx/client.hpp>
+#include <mongocxx/options/change_stream.hpp>
+#include <mongocxx/uri.hpp>
+
+#include <examples/api/db_lock.hh>
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(mongocxx::collection coll) {
+    // Basic usage.
+    {
+        mongocxx::change_stream stream = coll.watch();
+
+        EXPECT(stream.get_resume_token());
+    }
+
+    // With options.
+    {
+        mongocxx::options::change_stream opts;
+
+        opts.batch_size(1);
+        // ... other change stream options.
+
+        mongocxx::change_stream stream = coll.watch(opts);
+
+        EXPECT(stream.get_resume_token());
+    }
+
+    // With a pipeline.
+    {
+        mongocxx::pipeline pipeline;
+
+        pipeline.match(bsoncxx::from_json(R"({"operationType": "insert"})"));
+        // ... other pipeline options.
+
+        mongocxx::change_stream stream = coll.watch(pipeline);
+
+        EXPECT(stream.get_resume_token());
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT_FOR_REPLICA() {
+    mongocxx::client client{mongocxx::uri{}};
+
+    {
+        db_lock guard{client, EXAMPLES_COMPONENT_NAME_STR};
+
+        example(guard.get()["coll"]);
+    }
+}