doc(universe_domain): add ud samples for remaining libraries (#15660)

Author: scotthart

google/cloud/bigtable/doc/bigtable-main.dox

@@ -38,6 +38,7 @@ library.
 - @ref bigtable-endpoint-example
 - @ref bigtable-auth-example
 - @ref bigtable-override-retry
+- @ref bigtable-universe-domain-example
 - @ref bigtable-mocking "Mocking the Cloud Bigtable C++ client"
 - The [Setting up your development environment] guide describes how to set up
   a C++ development environment in various platforms, including the Google Cloud
@@ -110,6 +111,22 @@ guide for more details.
 
 */
 
+/**
+@page bigtable-universe-domain-example Override the default Universe Domain
+
+In some cases, you may need to override the default universe domain used by the client
+library. Use the [AddUniverseDomainOption](@ref google::cloud::AddUniverseDomainOption)
+when initializing the client library to change this default.
+
+@snippet client_samples.cc table-set-universe-domain
+
+Changing the default universe domain for other `*Client` classes is very similar, as
+shown in these examples:
+
+- [`BigtableTableAdminClient`](@ref BigtableTableAdminClient-set-universe-domain-snippet)
+- [`InstanceTableAdminClient`](@ref BigtableInstanceAdminClient-set-universe-domain-snippet)
+*/
+
 /*! @page Table-set-endpoint-snippet Override Table Default Endpoint
 
 @snippet google/cloud/bigtable/examples/client_samples.cc table-set-endpoint
@@ -120,6 +137,11 @@ guide for more details.
 @snippet google/cloud/bigtable/examples/client_samples.cc table-with-service-account
 */
 
+/*! @page Table-set-universe-domain-snippet Override Table Default Universe Domain
+
+@snippet google/cloud/bigtable/examples/client_samples.cc table-set-universe-domain
+*/
+
 /*! @page BigtableTableAdminClient-set-endpoint-snippet Override BigtableTableAdminClient Default Endpoint
 
 @snippet google/cloud/bigtable/admin/samples/bigtable_table_admin_client_samples.cc set-client-endpoint
@@ -130,6 +152,11 @@ guide for more details.
 @snippet google/cloud/bigtable/admin/samples/bigtable_table_admin_client_samples.cc with-service-account
 */
 
+/*! @page BigtableTableAdminClient-set-universe-domain-snippet Override BigtableTableAdminClient Default Universe Domain
+
+@snippet google/cloud/bigtable/admin/samples/bigtable_table_admin_client_samples.cc set-client-universe-domain
+*/
+
 /*! @page BigtableInstanceAdminClient-set-endpoint-snippet Override BigtableInstanceAdminClient Default Endpoint
 
 @snippet google/cloud/bigtable/admin/samples/bigtable_instance_admin_client_samples.cc set-client-endpoint
@@ -139,3 +166,8 @@ guide for more details.
 
 @snippet google/cloud/bigtable/admin/samples/bigtable_instance_admin_client_samples.cc with-service-account
 */
+
+/*! @page BigtableInstanceAdminClient-set-universe-domain-snippet Override BigtableInstanceAdminClient Default Universe Domain
+
+@snippet google/cloud/bigtable/admin/samples/bigtable_instance_admin_client_samples.cc set-client-universe-domain
+*/

google/cloud/bigtable/examples/BUILD.bazel

@@ -75,6 +75,7 @@ cc_test(
         "//:bigtable",
         "//:common",
         "//:grpc_utils",
+        "//:universe_domain",
         "//google/cloud/testing_util:google_cloud_cpp_testing_grpc_private",
         "//google/cloud/testing_util:google_cloud_cpp_testing_private",
     ],

google/cloud/bigtable/examples/CMakeLists.txt

@@ -70,6 +70,7 @@ if (BUILD_TESTING)
                     google-cloud-cpp::bigtable_protos
                     google-cloud-cpp::common
                     google-cloud-cpp::grpc_utils
+                    google-cloud-cpp::universe_domain
                     absl::time
                     GTest::gmock_main
                     GTest::gmock
@@ -91,6 +92,7 @@ if (BUILD_TESTING)
                     google-cloud-cpp::bigtable_protos
                     google-cloud-cpp::common
                     google-cloud-cpp::grpc_utils
+                    google-cloud-cpp::universe_domain
                     absl::time
                     gRPC::grpc++
                     gRPC::grpc

google/cloud/bigtable/examples/client_samples.cc

@@ -20,6 +20,7 @@
 #include "google/cloud/internal/getenv.h"
 #include "google/cloud/internal/random.h"
 #include "google/cloud/testing_util/example_driver.h"
+#include "google/cloud/universe_domain.h"
 #include <fstream>
 #include <string>
 #include <vector>
@@ -116,6 +117,32 @@ void TableWithServiceAccount(std::vector<std::string> const& argv) {
   (argv.at(0), argv.at(1), argv.at(2), argv.at(3));
 }
 
+void TableSetUniverseDomain(std::vector<std::string> const& argv) {
+  if (argv.size() != 3) {
+    throw google::cloud::testing_util::Usage{
+        "table-set-endpoint <project-id> <instance-id> <table-id>"};
+  }
+  //! [table-set-universe-domain]
+  namespace bigtable = ::google::cloud::bigtable;
+  [](std::string const& project_id, std::string const& instance_id,
+     std::string const& table_id) {
+    google::cloud::Options options;
+
+    // AddUniverseDomainOption interrogates the UnifiedCredentialsOption, if
+    // set, in the provided Options for the Universe Domain associated with the
+    // credentials and adds it to the set of Options.
+    // If no UnifiedCredentialsOption is set, GoogleDefaultCredentials are used.
+    auto ud_options =
+        google::cloud::AddUniverseDomainOption(std::move(options));
+
+    if (!ud_options.ok()) throw std::move(ud_options).status();
+    auto resource = bigtable::TableResource(project_id, instance_id, table_id);
+    return bigtable::Table(bigtable::MakeDataConnection(*ud_options), resource);
+  }
+  //! [table-set-universe-domain]
+  (argv.at(0), argv.at(1), argv.at(2));
+}
+
 void AutoRun(std::vector<std::string> const& argv) {
   using ::google::cloud::internal::GetEnv;
   namespace examples = ::google::cloud::testing_util;
@@ -144,6 +171,9 @@ void AutoRun(std::vector<std::string> const& argv) {
   std::cout << "\nRunning SetRetryPolicy() sample" << std::endl;
   SetRetryPolicy({project_id, instance_id, table_id});
 
+  std::cout << "\nRunning TableSetUniverseDomain() sample" << std::endl;
+  TableSetUniverseDomain({project_id, instance_id, table_id});
+
   std::cout << "\nAutoRun done" << std::endl;
 }
 
@@ -154,6 +184,7 @@ int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
       {"table-set-endpoint", TableSetEndpoint},
       {"set-retry-policy", SetRetryPolicy},
       {"table-with-service-account", TableWithServiceAccount},
+      {"table-set-universe-domain", TableSetUniverseDomain},
       {"auto", AutoRun},
   });
   return example.Run(argc, argv);

google/cloud/pubsub/doc/pubsub-main.dox

@@ -27,6 +27,7 @@ library.
 - @ref pubsub-endpoint-example
 - @ref pubsub-auth-example
 - @ref pubsub-override-retry
+- @ref pubsub-universe-domain-example
 - @ref publisher-mock shows how to write tests mocking [Publisher]
 - @ref subscriber-mock shows how to write tests mocking [Subscriber]
 - The [Setting up your development environment] guide describes how to set up
@@ -108,6 +109,25 @@ Follow these links to find examples for other `*Client` classes:
 [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
 */
 
+/**
+@page pubsub-universe-domain-example Override the default universe domain
+
+In some cases, you may need to override the default universe domain used by the client
+library. Use the [AddUniverseDomainOption](@ref google::cloud::AddUniverseDomainOption)
+when initializing the client library to change this default.
+
+@snippet client_samples.cc publisher-set-universe-domain
+
+Follow these links to find examples for other `*Client` classes:
+
+- [`Subscriber`](@ref Subscriber-universe-domain-snippet)
+- [`BlockingPublisher`](@ref BlockingPublisher-universe-domain-snippet)
+- [`TopicAdminClient`](@ref TopicAdminClient-universe-domain-snippet)
+- [`SubscriptionAdminClient`](@ref SubscriptionAdminClient-universe-domain-snippet)
+- [`SchemaServiceClient`](@ref SchemaServiceClient-universe-domain-snippet)
+- [`Publisher`](@ref Publisher-universe-domain-snippet)
+*/
+
 /*! @page Publisher-endpoint-snippet Override @c Publisher Default Endpoint
 
 @snippet google/cloud/pubsub/samples/client_samples.cc publisher-set-endpoint
@@ -179,3 +199,38 @@ Follow these links to find examples for other `*Client` classes:
 @snippet google/cloud/pubsub/samples/schema_client_samples.cc with-service-account
 
 */
+
+/*! @page Publisher-universe-domain-snippet Override @c Publisher Default Endpoint
+
+@snippet google/cloud/pubsub/samples/client_samples.cc publisher-set-universe-domain
+
+*/
+
+/*! @page Subscriber-universe-domain-snippet Override @c Subscriber Default Endpoint
+
+@snippet google/cloud/pubsub/samples/client_samples.cc subscriber-set-universe-domain
+
+*/
+
+/*! @page BlockingPublisher-universe-domain-snippet Override @c BlockingPublisher Default Endpoint
+
+@snippet google/cloud/pubsub/samples/client_samples.cc blocking-publisher-set-universe-domain
+
+*/
+
+/*! @page TopicAdminClient-universe-domain-snippet Override @c TopicAdminClient Default Endpoint
+
+@snippet google/cloud/pubsub/admin/samples/topic_admin_client_samples.cc set-client-universe-domain
+*/
+
+/*! @page SubscriptionAdminClient-universe-domain-snippet Override @c SubscriptionAdminClient Default Endpoint
+
+@snippet google/cloud/pubsub/admin/samples/subscription_admin_client_samples.cc set-client-universe-domain
+
+*/
+
+/*! @page SchemaServiceClient-universe-domain-snippet Override @c SchemaServiceClient Default Endpoint
+
+@snippet google/cloud/pubsub/samples/schema_client_samples.cc set-client-universe-domain
+
+*/

google/cloud/pubsub/samples/client_samples.cc

@@ -20,6 +20,7 @@
 #include "google/cloud/internal/getenv.h"
 #include "google/cloud/internal/random.h"
 #include "google/cloud/testing_util/example_driver.h"
+#include "google/cloud/universe_domain.h"
 #include <fstream>
 #include <string>
 #include <vector>
@@ -79,6 +80,32 @@ void PublisherServiceAccountKey(std::vector<std::string> const& argv) {
   (argv.at(0), argv.at(1), argv.at(2));
 }
 
+void PublisherSetUniverseDomain(std::vector<std::string> const& argv) {
+  namespace examples = ::google::cloud::testing_util;
+  if (argv.size() != 2) {
+    throw examples::Usage{
+        "publisher-set-universe-domain <project-id> <topic-id>"};
+  }
+  //! [publisher-set-universe-domain]
+  namespace pubsub = ::google::cloud::pubsub;
+  [](std::string const& project_id, std::string const& topic_id) {
+    google::cloud::Options options;
+
+    // AddUniverseDomainOption interrogates the UnifiedCredentialsOption, if
+    // set, in the provided Options for the Universe Domain associated with the
+    // credentials and adds it to the set of Options.
+    // If no UnifiedCredentialsOption is set, GoogleDefaultCredentials are used.
+    auto ud_options =
+        google::cloud::AddUniverseDomainOption(std::move(options));
+
+    if (!ud_options.ok()) throw std::move(ud_options).status();
+    auto pub = pubsub::Publisher(pubsub::MakePublisherConnection(
+        "europe-central2", pubsub::Topic(project_id, topic_id), *ud_options));
+  }
+  //! [publisher-set-universe-domain]
+  (argv.at(0), argv.at(1));
+}
+
 void SubscriberSetEndpoint(std::vector<std::string> const& argv) {
   namespace examples = ::google::cloud::testing_util;
   if (argv.size() != 2) {
@@ -131,6 +158,33 @@ void SubscriberServiceAccountKey(std::vector<std::string> const& argv) {
   (argv.at(0), argv.at(1), argv.at(2));
 }
 
+void SubscriberSetUniverseDomain(std::vector<std::string> const& argv) {
+  namespace examples = ::google::cloud::testing_util;
+  if (argv.size() != 2) {
+    throw examples::Usage{
+        "subscriber-set-universe-domain <project-id> <subscription-id>"};
+  }
+  //! [subscriber-set-universe-domain]
+  namespace pubsub = ::google::cloud::pubsub;
+  [](std::string const& project_id, std::string const& subscription_id) {
+    google::cloud::Options options;
+
+    // AddUniverseDomainOption interrogates the UnifiedCredentialsOption, if
+    // set, in the provided Options for the Universe Domain associated with the
+    // credentials and adds it to the set of Options.
+    // If no UnifiedCredentialsOption is set, GoogleDefaultCredentials are used.
+    auto ud_options =
+        google::cloud::AddUniverseDomainOption(std::move(options));
+
+    if (!ud_options.ok()) throw std::move(ud_options).status();
+    auto sub = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
+        "europe-central2", pubsub::Subscription(project_id, subscription_id),
+        *ud_options));
+  }
+  //! [subscriber-set-universe-domain]
+  (argv.at(0), argv.at(1));
+}
+
 void BlockingPublisherSetEndpoint(std::vector<std::string> const& argv) {
   namespace examples = ::google::cloud::testing_util;
   if (!argv.empty()) {
@@ -177,6 +231,32 @@ void BlockingPublisherServiceAccountKey(std::vector<std::string> const& argv) {
   (argv.at(0));
 }
 
+void BlockingPublisherSetUniverseDomain(std::vector<std::string> const& argv) {
+  namespace examples = ::google::cloud::testing_util;
+  if (!argv.empty()) {
+    throw examples::Usage{"blocking-publisher-set-universe-domain"};
+  }
+  //! [blocking-publisher-set-universe-domain]
+  namespace pubsub = ::google::cloud::pubsub;
+  []() {
+    google::cloud::Options options;
+
+    // AddUniverseDomainOption interrogates the UnifiedCredentialsOption, if
+    // set, in the provided Options for the Universe Domain associated with the
+    // credentials and adds it to the set of Options.
+    // If no UnifiedCredentialsOption is set, GoogleDefaultCredentials are used.
+    auto ud_options =
+        google::cloud::AddUniverseDomainOption(std::move(options));
+
+    if (!ud_options.ok()) throw std::move(ud_options).status();
+    auto pub =
+        pubsub::BlockingPublisher(pubsub::MakeBlockingPublisherConnection(
+            "europe-central2", *ud_options));
+  }
+  //! [blocking-publisher-set-universe-domain]
+  ();
+}
+
 void AutoRun(std::vector<std::string> const& argv) {
   namespace examples = ::google::cloud::testing_util;
 
@@ -199,19 +279,29 @@ void AutoRun(std::vector<std::string> const& argv) {
   std::cout << "\nRunning PublisherServiceAccountKey() sample" << std::endl;
   PublisherServiceAccountKey({project_id, topic_id, keyfile});
 
+  std::cout << "\nRunning PublisherSetUniverseDomain() sample" << std::endl;
+  PublisherSetUniverseDomain({project_id, topic_id});
+
   std::cout << "\nRunning SubscriberSetEndpoint() sample" << std::endl;
   SubscriberSetEndpoint({project_id, subscription_id});
 
   std::cout << "\nRunning SubscriberServiceAccountKey() sample" << std::endl;
   SubscriberServiceAccountKey({project_id, subscription_id, keyfile});
 
+  std::cout << "\nRunning SubscriberSetUniverseDomain() sample" << std::endl;
+  SubscriberSetUniverseDomain({project_id, subscription_id});
+
   std::cout << "\nRunning BlockingPublisherSetEndpoint() sample" << std::endl;
   BlockingPublisherSetEndpoint({});
 
   std::cout << "\nRunning BlockingPublisherServiceAccountKey() sample"
             << std::endl;
   BlockingPublisherServiceAccountKey({keyfile});
 
+  std::cout << "\nRunning BlockingPublisherSetUniverseDomain() sample"
+            << std::endl;
+  BlockingPublisherSetUniverseDomain({});
+
   std::cout << "\nAutoRun done" << std::endl;
 }
 
@@ -221,11 +311,15 @@ int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
   google::cloud::testing_util::Example example({
       {"publisher-set-endpoint", PublisherSetEndpoint},
       {"publisher-service-account-key", PublisherServiceAccountKey},
+      {"publisher-set-universe-domain", PublisherSetUniverseDomain},
       {"subscriber-set-endpoint", SubscriberSetEndpoint},
       {"subscriber-service-account-key", SubscriberServiceAccountKey},
+      {"subscriber-set-universe-domain", SubscriberSetUniverseDomain},
       {"blocking-publisher-set-endpoint", BlockingPublisherSetEndpoint},
       {"blocking-publisher-service-account-key",
        BlockingPublisherServiceAccountKey},
+      {"blocking-publisher-set-universe-domain",
+       BlockingPublisherSetUniverseDomain},
       {"auto", AutoRun},
   });
   return example.Run(argc, argv);