feat: support multiplexed sessions for RO transactions

.github/workflows/ci.yaml

@@ -52,7 +52,7 @@ jobs:
     - run: .kokoro/build.sh
       env:
         JOB_TYPE: test
-        GOOGLE_CLOUD_SPANNER_ENABLE_MULTIPLEXED_SESSIONS: true
+        GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS: true
   units-java8:
     # Building using Java 17 and run the tests with Java 8 runtime
     name: "units (8)"
@@ -91,7 +91,7 @@ jobs:
       - run: .kokoro/build.sh
         env:
           JOB_TYPE: test
-          GOOGLE_CLOUD_SPANNER_ENABLE_MULTIPLEXED_SESSIONS: true
+          GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS: true
   windows:
     runs-on: windows-latest
     steps:

.github/workflows/integration-tests-against-emulator-with-multiplexed-session.yaml

@@ -39,4 +39,4 @@ jobs:
       env:
         JOB_TYPE: test
         SPANNER_EMULATOR_HOST: localhost:9010
-        GOOGLE_CLOUD_SPANNER_ENABLE_MULTIPLEXED_SESSIONS: true
+        GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS: true

.kokoro/presubmit/integration-multiplexed-sessions-enabled.cfg

@@ -33,6 +33,6 @@ env_vars: {
 }
 
 env_vars: {
-    key: "GOOGLE_CLOUD_SPANNER_ENABLE_MULTIPLEXED_SESSIONS"
+    key: "GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS"
     value: "true"
-}
+}

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

@@ -16,7 +16,6 @@
 
 package com.google.cloud.spanner;
 
-import com.google.api.core.BetaApi;
 import com.google.api.core.InternalApi;
 import com.google.cloud.spanner.SessionPool.Position;
 import com.google.common.annotations.VisibleForTesting;
@@ -105,11 +104,12 @@ private SessionPoolOptions(Builder builder) {
     this.randomizePositionQPSThreshold = builder.randomizePositionQPSThreshold;
     this.inactiveTransactionRemovalOptions = builder.inactiveTransactionRemovalOptions;
     this.poolMaintainerClock = builder.poolMaintainerClock;
-    // TODO: Remove when multiplexed sessions are guaranteed to be supported.
+    // useMultiplexedSession priority => Environment var > private setter > client default
+    Boolean useMultiplexedSessionFromEnvVariable = getUseMultiplexedSessionFromEnvVariable();
     this.useMultiplexedSession =
-        builder.useMultiplexedSession
-            && !Boolean.parseBoolean(
-                System.getenv("GOOGLE_CLOUD_SPANNER_FORCE_DISABLE_MULTIPLEXED_SESSIONS"));
+        (useMultiplexedSessionFromEnvVariable != null)
+            ? useMultiplexedSessionFromEnvVariable
+            : builder.useMultiplexedSession;
     this.useRandomChannelHint = builder.useRandomChannelHint;
     this.multiplexedSessionMaintenanceDuration = builder.multiplexedSessionMaintenanceDuration;
   }
@@ -312,6 +312,16 @@ public boolean getUseMultiplexedSession() {
     return useMultiplexedSession;
   }
 
+  private static Boolean getUseMultiplexedSessionFromEnvVariable() {
+    String useMultiplexedSessionFromEnvVariable =
+        System.getenv("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS");
+    if (useMultiplexedSessionFromEnvVariable != null
+        && useMultiplexedSessionFromEnvVariable.length() > 0) {
+      return Boolean.parseBoolean(useMultiplexedSessionFromEnvVariable);
+    }
+    return null;
+  }
+
   boolean isUseRandomChannelHint() {
     return useRandomChannelHint;
   }
@@ -518,7 +528,9 @@ public static class Builder {
      */
     private long randomizePositionQPSThreshold = 0L;
 
-    private boolean useMultiplexedSession = getUseMultiplexedSessionFromEnvVariable();
+    // This field controls the default behavior of session management in Java client.
+    // Set useMultiplexedSession to true to make multiplexed session as default.
+    private boolean useMultiplexedSession = false;
 
     private boolean useRandomChannelHint;
 
@@ -538,18 +550,6 @@ private static Position getReleaseToPositionFromSystemProperty() {
       return Position.FIRST;
     }
 
-    /**
-     * This environment is only added to support internal spanner testing. Support for it can be
-     * removed in the future. Use {@link SessionPoolOptions#useMultiplexedSession} instead to use
-     * multiplexed sessions.
-     */
-    @InternalApi
-    @BetaApi
-    private static boolean getUseMultiplexedSessionFromEnvVariable() {
-      return Boolean.parseBoolean(
-          System.getenv("GOOGLE_CLOUD_SPANNER_ENABLE_MULTIPLEXED_SESSIONS"));
-    }
-
     public Builder() {}
 
     private Builder(SessionPoolOptions options) {

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

@@ -1266,14 +1266,20 @@ public Builder setHost(String host) {
       return this;
     }
 
-    /** Enables gRPC-GCP extension with the default settings. */
+    /**
+     * Enables gRPC-GCP extension with the default settings. Do not set
+     * GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS to true, since Multiplexed sessions is not
+     * supported for gRPC-GCP.
+     */
     public Builder enableGrpcGcpExtension() {
       return this.enableGrpcGcpExtension(null);
     }
 
     /**
      * Enables gRPC-GCP extension and uses provided options for configuration. The metric registry
-     * and default Spanner metric labels will be added automatically.
+     * and default Spanner metric labels will be added automatically. Do not set
+     * GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS to true, since Multiplexed sessions is not
+     * supported for gRPC-GCP.
      */
     public Builder enableGrpcGcpExtension(GcpManagedChannelOptions options) {
       this.grpcGcpExtensionEnabled = true;

google-cloud-spanner/src/test/java/com/google/cloud/spanner/MultiplexedSessionDatabaseClientTest.java

@@ -110,10 +110,9 @@ public void testMaintainer() {
   }
 
   @Test
-  public void testForceDisableEnvVar() throws Exception {
+  public void testDisableMultiplexedSessionEnvVar() throws Exception {
     assumeTrue(isJava8() && !isWindows());
-    assumeFalse(
-        System.getenv().containsKey("GOOGLE_CLOUD_SPANNER_FORCE_DISABLE_MULTIPLEXED_SESSIONS"));
+    assumeFalse(System.getenv().containsKey("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS"));
 
     // Assert that the mux sessions setting is respected by default.
     assertTrue(
@@ -129,17 +128,77 @@ public void testForceDisableEnvVar() throws Exception {
         (Map<String, String>) field.get(System.getenv());
 
     try {
-      writeableEnvironmentVariables.put(
-          "GOOGLE_CLOUD_SPANNER_FORCE_DISABLE_MULTIPLEXED_SESSIONS", "true");
+      writeableEnvironmentVariables.put("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS", "false");
       // Assert that the env var overrides the mux sessions setting.
       assertFalse(
           SessionPoolOptions.newBuilder()
               .setUseMultiplexedSession(true)
               .build()
               .getUseMultiplexedSession());
     } finally {
-      writeableEnvironmentVariables.remove(
-          "GOOGLE_CLOUD_SPANNER_FORCE_DISABLE_MULTIPLEXED_SESSIONS");
+      writeableEnvironmentVariables.remove("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS");
+    }
+  }
+
+  @Test
+  public void testEnableMultiplexedSessionEnvVar() throws Exception {
+    assumeTrue(isJava8() && !isWindows());
+    assumeFalse(System.getenv().containsKey("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS"));
+
+    // Assert that the mux sessions setting is respected by default.
+    assertFalse(
+        SessionPoolOptions.newBuilder()
+            .setUseMultiplexedSession(false)
+            .build()
+            .getUseMultiplexedSession());
+
+    Class<?> classOfMap = System.getenv().getClass();
+    Field field = classOfMap.getDeclaredField("m");
+    field.setAccessible(true);
+    Map<String, String> writeableEnvironmentVariables =
+        (Map<String, String>) field.get(System.getenv());
+
+    try {
+      writeableEnvironmentVariables.put("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS", "true");
+      // Assert that the env var overrides the mux sessions setting.
+      assertTrue(
+          SessionPoolOptions.newBuilder()
+              .setUseMultiplexedSession(false)
+              .build()
+              .getUseMultiplexedSession());
+    } finally {
+      writeableEnvironmentVariables.remove("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS");
+    }
+  }
+
+  @Test
+  public void testIgnoreMultiplexedSessionEnvVar() throws Exception {
+    assumeTrue(isJava8() && !isWindows());
+    assumeFalse(System.getenv().containsKey("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS"));
+
+    // Assert that the mux sessions setting is respected by default.
+    assertFalse(
+        SessionPoolOptions.newBuilder()
+            .setUseMultiplexedSession(false)
+            .build()
+            .getUseMultiplexedSession());
+
+    Class<?> classOfMap = System.getenv().getClass();
+    Field field = classOfMap.getDeclaredField("m");
+    field.setAccessible(true);
+    Map<String, String> writeableEnvironmentVariables =
+        (Map<String, String>) field.get(System.getenv());
+
+    try {
+      writeableEnvironmentVariables.put("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS", "");
+      // Assert that the env var overrides the mux sessions setting.
+      assertFalse(
+          SessionPoolOptions.newBuilder()
+              .setUseMultiplexedSession(false)
+              .build()
+              .getUseMultiplexedSession());
+    } finally {
+      writeableEnvironmentVariables.remove("GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS");
     }
   }