cleaned up tasks + added sample code

Author: ldetmer

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerOptions.java

@@ -128,7 +128,7 @@ public class SpannerOptions extends ServiceOptions<Spanner, SpannerOptions> {
   private static final String GOOGLE_DEFAULT_UNIVERSE = "googleapis.com";
   private static final String EXPERIMENTAL_HOST_PROJECT_ID = "default";
 
-  private static final ImmutableSet<String> SCOPES =
+  public static final ImmutableSet<String> SCOPES =
       ImmutableSet.of(
           "https://www.googleapis.com/auth/spanner.admin",
           "https://www.googleapis.com/auth/spanner.data");

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/MutableCredentials.java

@@ -46,7 +46,7 @@ public class MutableCredentials extends Credentials {
   private final Set<String> scopes;
 
   public MutableCredentials(ServiceAccountCredentials credentials) {
-    this(credentials, SpannerOptions.getDefaultInstance().getScopes());
+    this(credentials, SpannerOptions.SCOPES);
   }
 
   public MutableCredentials(ServiceAccountCredentials credentials, @Nonnull Set<String> scopes) {

google-cloud-spanner/src/test/java/com/google/cloud/spanner/connection/MutableCredentialsTest.java

@@ -79,7 +79,7 @@ public void testCreateMutableCredentials() throws IOException {
 
   @Test
   public void testCreateMutableCredentialsWithDefaultScopes() throws IOException {
-    Set<String> defaultScopes = SpannerOptions.getDefaultInstance().getScopes();
+    Set<String> defaultScopes = SpannerOptions.SCOPES;
     when(initialCredentials.createScoped(defaultScopes)).thenReturn(initialScopedCredentials);
     when(initialScopedCredentials.getAuthenticationType()).thenReturn(initialAuthType);
     when(initialScopedCredentials.getRequestMetadata(any(URI.class))).thenReturn(initialMetadata);

google-cloud-spanner/src/test/java/com/google/cloud/spanner/connection/it/ITMutableCredentialsTest.java

@@ -43,7 +43,7 @@ public class ITMutableCredentialsTest {
 
   @Test
   public void testMutableCredentialsUpdateAuthorizationForRunningClient() throws IOException {
-    GoogleCredentials validCredentials;
+    GoogleCredentials validCredentials = null;
 
     // accept cert path overridden by environment variable for local testing
     if (System.getenv("GOOGLE_ACCOUNT_CREDENTIALS") != null) {
@@ -52,7 +52,10 @@ public void testMutableCredentialsUpdateAuthorizationForRunningClient() throws I
         validCredentials = GoogleCredentials.fromStream(stream);
       }
     } else {
-      validCredentials = GoogleCredentials.getApplicationDefault();
+      try {
+        validCredentials = GoogleCredentials.getApplicationDefault();
+      } catch (IOException e) {
+      }
     }
 
     // credentials must be ServiceAccountCredentials
@@ -68,23 +71,24 @@ public void testMutableCredentialsUpdateAuthorizationForRunningClient() throws I
     MutableCredentials mutableCredentials =
         new MutableCredentials((ServiceAccountCredentials) validCredentials);
 
-    System.out.println("validCredentials " + validCredentials);
-
     SpannerOptions options =
         SpannerOptions.newBuilder()
             .setEmulatorHost(
                 null) // this setting is required otherwise SpannerOptions overrides credentials to
             // NoCredentials
             .setCredentials(mutableCredentials)
             .build();
-    System.out.println("initial credentials " + options.getCredentials());
+
     ProjectName projectName = ProjectName.of(options.getProjectId());
     try (Spanner spanner = options.getService();
         InstanceAdminClient instanceAdminClient = spanner.createInstanceAdminClient()) {
       instanceAdminClient.listInstances(projectName);
+
       // update mutableCredentials now to use an invalid credentials
       mutableCredentials.updateCredentials(invalidCredentials);
+
       try {
+        // this call should now fail with new invalid credentials
         instanceAdminClient.listInstances(projectName);
         fail("Expected UNAUTHENTICATED after switching to invalid credentials");
       } catch (Exception e) {

samples/snippets/src/main/java/com/example/spanner/MutableCredentialsExample.java

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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.
+ */
+
+package com.example.spanner;
+
+//[START mutable_credentials]
+
+import com.google.auth.oauth2.ServiceAccountCredentials;
+import com.google.cloud.spanner.Spanner;
+import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
+import com.google.cloud.spanner.connection.MutableCredentials;
+import com.google.spanner.admin.database.v1.DatabaseName;
+import com.google.spanner.admin.database.v1.GetDatabaseDdlResponse;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.nio.file.attribute.FileTime;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+public class MutableCredentialsExample {
+
+
+  static void createClientWithMutableCredentials() throws IOException {
+    final String credentialsPath = "location_of_service_account_credential_json";
+    Path path = Paths.get(credentialsPath);
+    // Use an array to hold the mutable lastModifiedTime so it can be accessed in the lambda
+    FileTime[] lastModifiedTime = new FileTime[]{ Files.getLastModifiedTime(path) };
+
+    // 1 - create service account credentials
+    ServiceAccountCredentials serviceAccountCredentials;
+    try (FileInputStream is = new FileInputStream(credentialsPath)) {
+      serviceAccountCredentials = ServiceAccountCredentials.fromStream(is);
+    }
+
+    // 2 - wrap credentials from step 1 in a MutableCredentials instance
+    MutableCredentials mutableCredentials = new MutableCredentials(serviceAccountCredentials);
+
+    // 3 - set credentials on your SpannerOptions builder to your mutableCredentials
+    SpannerOptions options = SpannerOptions.newBuilder()
+            .setCredentials(mutableCredentials)
+            .build();
+
+    // 4 - include logic for when to how your mutableCredentials
+    // In this example we'll use a SchedulerExecutorService to periodically check for updates
+    ScheduledExecutorService executorService = Executors.newSingleThreadScheduledExecutor();
+    executorService.scheduleAtFixedRate(() -> {
+      try {
+        FileTime currentModifiedTime = Files.getLastModifiedTime(path);
+        if (currentModifiedTime.compareTo(lastModifiedTime[0]) > 0) {
+          lastModifiedTime[0] = currentModifiedTime;
+          try (FileInputStream is = new FileInputStream(credentialsPath)) {
+            ServiceAccountCredentials credentials = ServiceAccountCredentials.fromStream(is);
+            mutableCredentials.updateCredentials(credentials);
+            System.out.println("Credentials rotated.");
+          }
+        }
+      } catch (IOException e) {
+        System.err.println("Failed to check or update credentials: " + e.getMessage());
+      }
+    }, 15, 15, TimeUnit.MINUTES);
+
+    // 5. Use the client
+    try (Spanner spanner = options.getService();
+         DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
+      // Perform operations...
+      // long running client operations will always use the latest credentials wrapped in
+      // mutableCredentials
+    } finally {
+      // Ensure the executor is shut down when the application exits or the client is closed
+      executorService.shutdown();
+    }
+  }
+}
+//[END mutable_credentials]