docs: update all public documents to use auto-generated admin clients. (

#2928) * fix: prevent illegal negative timeout values into thread sleep() method while retrying exceptions in unit tests. * For details on issue see - #2206 * Fixing lint issues. * docs: update all public documents to use auto-generated admin clients. * chore: fix lint issue. * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
googleapis · Mar 4, 2024 · ccb110a · ccb110a
1 parent 9a8cce8
commit ccb110a
Show file tree

Hide file tree

Showing 130 changed files with 4,674 additions and 4,514 deletions.
diff --git a/README.md b/README.md
diff --git a/samples/README.md b/samples/README.md
@@ -34,7 +34,7 @@ You can run a given `ClassName` via:
 ## Tutorial
 
 ### Running the tutorial
-    mvn exec:java -Dexec.mainClass=com.example.spanner.SpannerSample -Dexec.args="<command> my-instance my-database"
+    mvn exec:java -Dexec.mainClass=com.example.spanner.admin.archived.SpannerSample -Dexec.args="<command> my-instance my-database"
 
 ## Tracing sample
 `TracingSample.java` demonstrates how to export traces generated by client library to StackDriver and to /tracez page.

diff --git a/samples/snippets/pom.xml b/samples/snippets/pom.xml
@@ -165,7 +165,7 @@
           <archive>
             <index>false</index>
             <manifest>
-              <mainClass>com.example.spanner.SpannerSample</mainClass>
+              <mainClass>com.example.spanner.admin.archived.SpannerSample</mainClass>
               <addClasspath>true</addClasspath>
               <classpathPrefix>lib/</classpathPrefix>
             </manifest>

diff --git a/samples/snippets/src/main/java/com/example/spanner/AddAndDropDatabaseRole.java b/samples/snippets/src/main/java/com/example/spanner/AddAndDropDatabaseRole.java
@@ -17,12 +17,12 @@
 package com.example.spanner;
 
 // [START spanner_add_and_drop_database_role]
-import com.google.api.gax.longrunning.OperationFuture;
-import com.google.cloud.spanner.DatabaseAdminClient;
+
 import com.google.cloud.spanner.Spanner;
 import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
 import com.google.common.collect.ImmutableList;
-import com.google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata;
+import com.google.spanner.admin.database.v1.DatabaseName;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
@@ -34,54 +34,46 @@ static void addAndDropDatabaseRole() {
     String projectId = "my-project";
     String instanceId = "my-instance";
     String databaseId = "my-database";
-    String parentRole = "my-new-parent-role";
-    String childRole = "my-new-child-role";
+    String parentRole = "parent_role";
+    String childRole = "child_role";
     addAndDropDatabaseRole(projectId, instanceId, databaseId, parentRole, childRole);
   }
 
   static void addAndDropDatabaseRole(
-      String projectId, String instanceId, String databaseId, String parentRole, String childRole) {
+      String projectId, String instanceId, String databaseId,
+      String parentRole, String childRole) {
     try (Spanner spanner =
-                 SpannerOptions.newBuilder()
-                         .setProjectId(projectId)
-                         .build()
-                         .getService())  {
-      final DatabaseAdminClient adminClient = spanner.getDatabaseAdminClient();
-      OperationFuture<Void, UpdateDatabaseDdlMetadata> operation =
-          adminClient.updateDatabaseDdl(
-              instanceId,
-              databaseId,
+        SpannerOptions.newBuilder()
+            .setProjectId(projectId)
+            .build()
+            .getService();
+        DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
+      System.out.println("Waiting for role create operation to complete...");
+      databaseAdminClient.updateDatabaseDdlAsync(
+              DatabaseName.of(projectId, instanceId, databaseId),
               ImmutableList.of(
-                  "CREATE ROLE " + parentRole,
-                  "GRANT SELECT ON TABLE Albums TO ROLE " + parentRole,
-                  "CREATE ROLE " + childRole,
-                  "GRANT ROLE " + parentRole + " TO ROLE " + childRole),
-              null);
-      try {
-        System.out.println("Waiting for role create operation to complete...");
-        operation.get(5, TimeUnit.MINUTES);
-        System.out.printf(
-            "Created roles %s and %s and granted privileges%n", parentRole, childRole);
-        // Delete role and membership.
-        operation =
-            adminClient.updateDatabaseDdl(
-                instanceId,
-                databaseId,
-                ImmutableList.of(
-                    "REVOKE ROLE " + parentRole + " FROM ROLE " + childRole,
-                    "DROP ROLE " + childRole),
-                null);
-        System.out.println("Waiting for role revoke & drop operation to complete...");
-        operation.get(5, TimeUnit.MINUTES);
-        System.out.printf("Revoked privileges and dropped role %s%n", childRole);
-      } catch (ExecutionException | TimeoutException e) {
-        System.out.printf(
-            "Error: AddAndDropDatabaseRole failed with error message %s\n", e.getMessage());
-        e.printStackTrace();
-      } catch (InterruptedException e) {
-        System.out.println(
-            "Error: Waiting for AddAndDropDatabaseRole operation to finish was interrupted");
-      }
+                  String.format("CREATE ROLE %s", parentRole),
+                  String.format("GRANT SELECT ON TABLE Albums TO ROLE %s", parentRole),
+                  String.format("CREATE ROLE %s", childRole),
+                  String.format("GRANT ROLE %s TO ROLE %s", parentRole, childRole)))
+          .get(5, TimeUnit.MINUTES);
+      System.out.printf(
+          "Created roles %s and %s and granted privileges%n", parentRole, childRole);
+      // Delete role and membership.
+      System.out.println("Waiting for role revoke & drop operation to complete...");
+      databaseAdminClient.updateDatabaseDdlAsync(
+          DatabaseName.of(projectId, instanceId, databaseId),
+          ImmutableList.of(
+              String.format("REVOKE ROLE %s FROM ROLE %s", parentRole, childRole),
+              String.format("DROP ROLE %s", childRole))).get(5, TimeUnit.MINUTES);
+      System.out.printf("Revoked privileges and dropped role %s%n", childRole);
+    } catch (ExecutionException | TimeoutException e) {
+      System.out.printf(
+          "Error: AddAndDropDatabaseRole failed with error message %s\n", e.getMessage());
+      e.printStackTrace();
+    } catch (InterruptedException e) {
+      System.out.println(
+          "Error: Waiting for AddAndDropDatabaseRole operation to finish was interrupted");
     }
   }
 }

diff --git a/samples/snippets/src/main/java/com/example/spanner/AddJsonColumnSample.java b/samples/snippets/src/main/java/com/example/spanner/AddJsonColumnSample.java
@@ -17,12 +17,12 @@
 package com.example.spanner;
 
 // [START spanner_add_json_column]
-import com.google.api.gax.longrunning.OperationFuture;
-import com.google.cloud.spanner.DatabaseAdminClient;
+
 import com.google.cloud.spanner.Spanner;
 import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
 import com.google.common.collect.ImmutableList;
-import com.google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata;
+import com.google.spanner.admin.database.v1.DatabaseName;
 import java.util.concurrent.ExecutionException;
 
 class AddJsonColumnSample {
@@ -33,25 +33,24 @@ static void addJsonColumn() throws InterruptedException, ExecutionException {
     String instanceId = "my-instance";
     String databaseId = "my-database";
 
-    try (Spanner spanner =
-        SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
-      DatabaseAdminClient adminClient = spanner.getDatabaseAdminClient();
-      addJsonColumn(adminClient, instanceId, databaseId);
-    }
+    addJsonColumn(projectId, instanceId, databaseId);
   }
 
-  static void addJsonColumn(DatabaseAdminClient adminClient, String instanceId, String databaseId)
+  static void addJsonColumn(String projectId, String instanceId, String databaseId)
       throws InterruptedException, ExecutionException {
-    OperationFuture<Void, UpdateDatabaseDdlMetadata> operation =
-        adminClient.updateDatabaseDdl(
-            instanceId,
-            databaseId,
-            ImmutableList.of("ALTER TABLE Venues ADD COLUMN VenueDetails JSON"),
-            null);
-    // Wait for the operation to finish.
-    // This will throw an ExecutionException if the operation fails.
-    operation.get();
-    System.out.printf("Successfully added column `VenueDetails`%n");
+    try (Spanner spanner =
+        SpannerOptions.newBuilder()
+            .setProjectId(projectId)
+            .build()
+            .getService();
+        DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
+      // Wait for the operation to finish.
+      // This will throw an ExecutionException if the operation fails.
+      databaseAdminClient.updateDatabaseDdlAsync(
+          DatabaseName.of(projectId, instanceId, databaseId),
+          ImmutableList.of("ALTER TABLE Venues ADD COLUMN VenueDetails JSON")).get();
+      System.out.printf("Successfully added column `VenueDetails`%n");
+    }
   }
 }
 // [END spanner_add_json_column]
diff --git a/samples/snippets/src/main/java/com/example/spanner/AddJsonbColumnSample.java b/samples/snippets/src/main/java/com/example/spanner/AddJsonbColumnSample.java
@@ -17,12 +17,12 @@
 package com.example.spanner;
 
 // [START spanner_postgresql_jsonb_add_column]
-import com.google.api.gax.longrunning.OperationFuture;
-import com.google.cloud.spanner.DatabaseAdminClient;
+
 import com.google.cloud.spanner.Spanner;
 import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
 import com.google.common.collect.ImmutableList;
-import com.google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata;
+import com.google.spanner.admin.database.v1.DatabaseName;
 import java.util.concurrent.ExecutionException;
 
 class AddJsonbColumnSample {
@@ -33,25 +33,25 @@ static void addJsonbColumn() throws InterruptedException, ExecutionException {
     String instanceId = "my-instance";
     String databaseId = "my-database";
 
-    try (Spanner spanner =
-        SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
-      DatabaseAdminClient adminClient = spanner.getDatabaseAdminClient();
-      addJsonbColumn(adminClient, instanceId, databaseId);
-    }
+    addJsonbColumn(projectId, instanceId, databaseId);
   }
 
-  static void addJsonbColumn(DatabaseAdminClient adminClient, String instanceId, String databaseId)
+  static void addJsonbColumn(String projectId, String instanceId, String databaseId)
       throws InterruptedException, ExecutionException {
-    OperationFuture<Void, UpdateDatabaseDdlMetadata> operation =
-        adminClient.updateDatabaseDdl(
-            instanceId,
-            databaseId,
-            ImmutableList.of("ALTER TABLE Venues ADD COLUMN VenueDetails JSONB"),
-            null);
-    // Wait for the operation to finish.
-    // This will throw an ExecutionException if the operation fails.
-    operation.get();
-    System.out.printf("Successfully added column `VenueDetails`%n");
+    try (Spanner spanner =
+        SpannerOptions.newBuilder()
+            .setProjectId(projectId)
+            .build()
+            .getService();
+        DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
+      // JSONB datatype is only supported with PostgreSQL-dialect databases.
+      // Wait for the operation to finish.
+      // This will throw an ExecutionException if the operation fails.
+      databaseAdminClient.updateDatabaseDdlAsync(
+          DatabaseName.of(projectId, instanceId, databaseId),
+          ImmutableList.of("ALTER TABLE Venues ADD COLUMN VenueDetails JSONB")).get();
+      System.out.printf("Successfully added column `VenueDetails`%n");
+    }
   }
 }
 // [END spanner_postgresql_jsonb_add_column]
diff --git a/samples/snippets/src/main/java/com/example/spanner/AddNumericColumnSample.java b/samples/snippets/src/main/java/com/example/spanner/AddNumericColumnSample.java
@@ -17,12 +17,12 @@
 package com.example.spanner;
 
 // [START spanner_add_numeric_column]
-import com.google.api.gax.longrunning.OperationFuture;
-import com.google.cloud.spanner.DatabaseAdminClient;
+
 import com.google.cloud.spanner.Spanner;
 import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
 import com.google.common.collect.ImmutableList;
-import com.google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata;
+import com.google.spanner.admin.database.v1.DatabaseName;
 import java.util.concurrent.ExecutionException;
 
 class AddNumericColumnSample {
@@ -33,26 +33,24 @@ static void addNumericColumn() throws InterruptedException, ExecutionException {
     String instanceId = "my-instance";
     String databaseId = "my-database";
 
-    try (Spanner spanner =
-        SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
-      DatabaseAdminClient adminClient = spanner.getDatabaseAdminClient();
-      addNumericColumn(adminClient, instanceId, databaseId);
-    }
+    addNumericColumn(projectId, instanceId, databaseId);
   }
 
-  static void addNumericColumn(
-      DatabaseAdminClient adminClient, String instanceId, String databaseId)
+  static void addNumericColumn(String projectId, String instanceId, String databaseId)
       throws InterruptedException, ExecutionException {
-    OperationFuture<Void, UpdateDatabaseDdlMetadata> operation =
-        adminClient.updateDatabaseDdl(
-            instanceId,
-            databaseId,
-            ImmutableList.of("ALTER TABLE Venues ADD COLUMN Revenue NUMERIC"),
-            null);
-    // Wait for the operation to finish.
-    // This will throw an ExecutionException if the operation fails.
-    operation.get();
-    System.out.printf("Successfully added column `Revenue`%n");
+    try (Spanner spanner =
+        SpannerOptions.newBuilder()
+            .setProjectId(projectId)
+            .build()
+            .getService();
+        DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
+      // Wait for the operation to finish.
+      // This will throw an ExecutionException if the operation fails.
+      databaseAdminClient.updateDatabaseDdlAsync(
+          DatabaseName.of(projectId, instanceId, databaseId),
+          ImmutableList.of("ALTER TABLE Venues ADD COLUMN Revenue NUMERIC")).get();
+      System.out.printf("Successfully added column `Revenue`%n");
+    }
   }
 }
 // [END spanner_add_numeric_column]
diff --git a/samples/snippets/src/main/java/com/example/spanner/AlterSequenceSample.java b/samples/snippets/src/main/java/com/example/spanner/AlterSequenceSample.java
@@ -17,21 +17,24 @@
 package com.example.spanner;
 
 // [START spanner_alter_sequence]
-import com.google.cloud.spanner.DatabaseAdminClient;
+
 import com.google.cloud.spanner.DatabaseClient;
 import com.google.cloud.spanner.DatabaseId;
 import com.google.cloud.spanner.ResultSet;
 import com.google.cloud.spanner.Spanner;
 import com.google.cloud.spanner.SpannerExceptionFactory;
 import com.google.cloud.spanner.SpannerOptions;
 import com.google.cloud.spanner.Statement;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
 import com.google.common.collect.ImmutableList;
+import com.google.spanner.admin.database.v1.DatabaseName;
 import java.util.Objects;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
 public class AlterSequenceSample {
+
   static void alterSequence() {
     // TODO(developer): Replace these variables before running the sample.
     final String projectId = "my-project";
@@ -42,17 +45,14 @@ static void alterSequence() {
 
   static void alterSequence(String projectId, String instanceId, String databaseId) {
     try (Spanner spanner =
-        SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
-      final DatabaseAdminClient dbAdminClient = spanner.getDatabaseAdminClient();
+        SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
+        DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
 
-      dbAdminClient
-          .updateDatabaseDdl(
-              instanceId,
-              databaseId,
+      databaseAdminClient
+          .updateDatabaseDdlAsync(DatabaseName.of(projectId, instanceId, databaseId),
               ImmutableList.of(
                   "ALTER SEQUENCE Seq SET OPTIONS "
-                      + "(skip_range_min = 1000, skip_range_max = 5000000)"),
-              null)
+                      + "(skip_range_min = 1000, skip_range_max = 5000000)"))
           .get(5, TimeUnit.MINUTES);
 
       System.out.println(