chore: make valid connection properties public (googleapis#3546)

Make the list of valid connection properties public, so tools that
depend on the Connection API can use this to for example generate
documentation for valid properties.

Also add valid values to the connection properties that have that
(e.g. enums and booleans).

Co-authored-by: rahul2393 <[email protected]>

Author: olavloite

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

@@ -112,27 +112,30 @@
 import com.google.cloud.spanner.connection.ClientSideStatementValueConverters.StringValueConverter;
 import com.google.cloud.spanner.connection.ConnectionProperty.Context;
 import com.google.cloud.spanner.connection.DirectedReadOptionsUtil.DirectedReadOptionsConverter;
+import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.spanner.v1.DirectedReadOptions;
 import java.time.Duration;
-import java.util.Map;
 
 /**
  * Utility class that defines all known connection properties. This class will eventually replace
  * the list of {@link com.google.cloud.spanner.connection.ConnectionOptions.ConnectionProperty} in
  * {@link ConnectionOptions}.
  */
-class ConnectionProperties {
+public class ConnectionProperties {
   private static final ImmutableMap.Builder<String, ConnectionProperty<?>>
       CONNECTION_PROPERTIES_BUILDER = ImmutableMap.builder();
 
+  private static final Boolean[] BOOLEANS = new Boolean[] {Boolean.TRUE, Boolean.FALSE};
+
   static final ConnectionProperty<ConnectionState.Type> CONNECTION_STATE_TYPE =
       create(
           "connection_state_type",
           "The type of connection state to use for this connection. Can only be set at start up. "
               + "If no value is set, then the database dialect default will be used, "
               + "which is NON_TRANSACTIONAL for GoogleSQL and TRANSACTIONAL for PostgreSQL.",
           null,
+          ConnectionState.Type.values(),
           ConnectionStateTypeConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<String> TRACING_PREFIX =
@@ -148,6 +151,7 @@ class ConnectionProperties {
           LENIENT_PROPERTY_NAME,
           "Silently ignore unknown properties in the connection string/properties (true/false)",
           DEFAULT_LENIENT,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<String> ENDPOINT =
@@ -167,6 +171,7 @@ class ConnectionProperties {
               + "The instance and database in the connection string will automatically be created if these do not yet exist on the emulator. "
               + "Add dialect=postgresql to the connection string to make sure that the database that is created uses the PostgreSQL dialect.",
           false,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> USE_AUTO_SAVEPOINTS_FOR_EMULATOR =
@@ -175,13 +180,15 @@ class ConnectionProperties {
           "Automatically creates savepoints for each statement in a read/write transaction when using the Emulator. "
               + "This is no longer needed when using Emulator version 1.5.23 or higher.",
           false,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> USE_PLAIN_TEXT =
       create(
           USE_PLAIN_TEXT_PROPERTY_NAME,
           "Use a plain text communication channel (i.e. non-TLS) for communicating with the server (true/false). Set this value to true for communication with the Cloud Spanner emulator.",
           DEFAULT_USE_PLAIN_TEXT,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
 
@@ -226,6 +233,7 @@ class ConnectionProperties {
           DIALECT_PROPERTY_NAME,
           "Sets the dialect to use for new databases that are created by this connection.",
           Dialect.GOOGLE_STANDARD_SQL,
+          Dialect.values(),
           DialectConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> TRACK_SESSION_LEAKS =
@@ -238,6 +246,7 @@ class ConnectionProperties {
               + "actual session leak is detected. The stack trace of the exception will "
               + "in that case not contain the call stack of when the session was checked out.",
           DEFAULT_TRACK_SESSION_LEAKS,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> TRACK_CONNECTION_LEAKS =
@@ -250,13 +259,15 @@ class ConnectionProperties {
               + "actual connection leak is detected. The stack trace of the exception will "
               + "in that case not contain the call stack of when the connection was created.",
           DEFAULT_TRACK_CONNECTION_LEAKS,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> ROUTE_TO_LEADER =
       create(
           ROUTE_TO_LEADER_PROPERTY_NAME,
           "Should read/write transactions and partitioned DML be routed to leader region (true/false)",
           DEFAULT_ROUTE_TO_LEADER,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> USE_VIRTUAL_THREADS =
@@ -265,6 +276,7 @@ class ConnectionProperties {
           "Use a virtual thread instead of a platform thread for each connection (true/false). "
               + "This option only has any effect if the application is running on Java 21 or higher. In all other cases, the option is ignored.",
           DEFAULT_USE_VIRTUAL_THREADS,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> USE_VIRTUAL_GRPC_TRANSPORT_THREADS =
@@ -273,6 +285,7 @@ class ConnectionProperties {
           "Use a virtual thread instead of a platform thread for the gRPC executor (true/false). "
               + "This option only has any effect if the application is running on Java 21 or higher. In all other cases, the option is ignored.",
           DEFAULT_USE_VIRTUAL_GRPC_TRANSPORT_THREADS,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> ENABLE_EXTENDED_TRACING =
@@ -282,6 +295,7 @@ class ConnectionProperties {
               + "by this connection. The SQL string is added as the standard OpenTelemetry "
               + "attribute 'db.statement'.",
           DEFAULT_ENABLE_EXTENDED_TRACING,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> ENABLE_API_TRACING =
@@ -292,6 +306,7 @@ class ConnectionProperties {
               + "or if you want to debug potential latency problems caused by RPCs that are "
               + "being retried.",
           DEFAULT_ENABLE_API_TRACING,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Boolean> ENABLE_END_TO_END_TRACING =
@@ -302,6 +317,7 @@ class ConnectionProperties {
               + "Server side traces can only go to Google Cloud Trace, so to see end to end traces, "
               + "the application should configure an exporter that exports the traces to Google Cloud Trace.",
           DEFAULT_ENABLE_END_TO_END_TRACING,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.STARTUP);
   static final ConnectionProperty<Integer> MIN_SESSIONS =
@@ -345,20 +361,24 @@ class ConnectionProperties {
           AUTOCOMMIT_PROPERTY_NAME,
           "Should the connection start in autocommit (true/false)",
           DEFAULT_AUTOCOMMIT,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Boolean> READONLY =
       create(
           READONLY_PROPERTY_NAME,
           "Should the connection start in read-only mode (true/false)",
           DEFAULT_READONLY,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<AutocommitDmlMode> AUTOCOMMIT_DML_MODE =
       create(
           "autocommit_dml_mode",
-          "Should the connection automatically retry Aborted errors (true/false)",
+          "Determines the transaction type that is used to execute "
+              + "DML statements when the connection is in auto-commit mode.",
           AutocommitDmlMode.TRANSACTIONAL,
+          AutocommitDmlMode.values(),
           AutocommitDmlModeConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Boolean> RETRY_ABORTS_INTERNALLY =
@@ -371,13 +391,15 @@ class ConnectionProperties {
           RETRY_ABORTS_INTERNALLY_PROPERTY_NAME,
           "Should the connection automatically retry Aborted errors (true/false)",
           DEFAULT_RETRY_ABORTS_INTERNALLY,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Boolean> RETURN_COMMIT_STATS =
       create(
           "returnCommitStats",
           "Request that Spanner returns commit statistics for read/write transactions (true/false)",
           DEFAULT_RETURN_COMMIT_STATS,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Boolean> DELAY_TRANSACTION_START_UNTIL_FIRST_WRITE =
@@ -389,6 +411,7 @@ class ConnectionProperties {
               + "the first write operation in a read/write transaction will be executed using the read/write transaction. Enabling this mode can reduce locking "
               + "and improve performance for applications that can handle the lower transaction isolation semantics.",
           DEFAULT_DELAY_TRANSACTION_START_UNTIL_FIRST_WRITE,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Boolean> KEEP_TRANSACTION_ALIVE =
@@ -398,6 +421,7 @@ class ConnectionProperties {
               + "if no other statements are being executed. This option should be used with caution, as it can keep transactions alive and hold on to locks "
               + "longer than intended. This option should typically be used for CLI-type application that might wait for user input for a longer period of time.",
           DEFAULT_KEEP_TRANSACTION_ALIVE,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
 
@@ -415,6 +439,7 @@ class ConnectionProperties {
               + "Executing a query that cannot be partitioned will fail. "
               + "Executing a query in a read/write transaction will also fail.",
           DEFAULT_AUTO_PARTITION_MODE,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Boolean> DATA_BOOST_ENABLED =
@@ -423,6 +448,7 @@ class ConnectionProperties {
           "Enable data boost for all partitioned queries that are executed by this connection. "
               + "This setting is only used for partitioned queries and is ignored by all other statements.",
           DEFAULT_DATA_BOOST_ENABLED,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Integer> MAX_PARTITIONS =
@@ -468,20 +494,23 @@ class ConnectionProperties {
           RPC_PRIORITY_NAME,
           "Sets the priority for all RPC invocations from this connection (HIGH/MEDIUM/LOW). The default is HIGH.",
           DEFAULT_RPC_PRIORITY,
+          RpcPriority.values(),
           RpcPriorityConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<SavepointSupport> SAVEPOINT_SUPPORT =
       create(
           "savepoint_support",
           "Determines the behavior of the connection when savepoints are used.",
           SavepointSupport.FAIL_AFTER_ROLLBACK,
+          SavepointSupport.values(),
           SavepointSupportConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<DdlInTransactionMode> DDL_IN_TRANSACTION_MODE =
       create(
           DDL_IN_TRANSACTION_MODE_PROPERTY_NAME,
           "Determines how the connection should handle DDL statements in a read/write transaction.",
           DEFAULT_DDL_IN_TRANSACTION_MODE,
+          DdlInTransactionMode.values(),
           DdlInTransactionModeConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Duration> MAX_COMMIT_DELAY =
@@ -504,6 +533,7 @@ class ConnectionProperties {
               + "This setting is only in read/write transactions. DML statements in auto-commit mode "
               + "are executed directly.",
           DEFAULT_AUTO_BATCH_DML,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
   static final ConnectionProperty<Long> AUTO_BATCH_DML_UPDATE_COUNT =
@@ -538,23 +568,45 @@ class ConnectionProperties {
               + AUTO_BATCH_DML_UPDATE_COUNT_VERIFICATION_PROPERTY_NAME
               + " to false.",
           DEFAULT_AUTO_BATCH_DML_UPDATE_COUNT_VERIFICATION,
+          BOOLEANS,
           BooleanConverter.INSTANCE,
           Context.USER);
 
-  static final Map<String, ConnectionProperty<?>> CONNECTION_PROPERTIES =
+  static final ImmutableMap<String, ConnectionProperty<?>> CONNECTION_PROPERTIES =
       CONNECTION_PROPERTIES_BUILDER.build();
 
+  /** The list of all supported connection properties. */
+  public static ImmutableList<ConnectionProperty<?>> VALID_CONNECTION_PROPERTIES =
+      ImmutableList.copyOf(ConnectionProperties.CONNECTION_PROPERTIES.values());
+
   /** Utility method for creating a new core {@link ConnectionProperty}. */
   private static <T> ConnectionProperty<T> create(
       String name,
       String description,
       T defaultValue,
       ClientSideStatementValueConverter<T> converter,
       Context context) {
-    ConnectionProperty<T> property =
-        ConnectionProperty.create(name, description, defaultValue, converter, context);
-    CONNECTION_PROPERTIES_BUILDER.put(property.getKey(), property);
-    return property;
+    return create(name, description, defaultValue, null, converter, context);
+  }
+
+  /** Utility method for creating a new core {@link ConnectionProperty}. */
+  private static <T> ConnectionProperty<T> create(
+      String name,
+      String description,
+      T defaultValue,
+      T[] validValues,
+      ClientSideStatementValueConverter<T> converter,
+      Context context) {
+    try {
+      ConnectionProperty<T> property =
+          ConnectionProperty.create(
+              name, description, defaultValue, validValues, converter, context);
+      CONNECTION_PROPERTIES_BUILDER.put(property.getKey(), property);
+      return property;
+    } catch (Throwable t) {
+      t.printStackTrace();
+    }
+    return null;
   }
 
   /** Parse the connection properties that can be found in the given connection URL. */

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

@@ -37,12 +37,13 @@
  * connection state is an opt-in.
  */
 public class ConnectionProperty<T> {
+
   /**
    * Context indicates when a {@link ConnectionProperty} may be set. Each higher-ordinal value
    * includes the preceding values, meaning that a {@link ConnectionProperty} with {@link
    * Context#USER} can be set both at connection startup and during the connection's lifetime.
    */
-  enum Context {
+  public enum Context {
     /** The property can only be set at startup of the connection. */
     STARTUP,
     /**
@@ -79,8 +80,20 @@ static <T> ConnectionProperty<T> create(
       T defaultValue,
       ClientSideStatementValueConverter<T> converter,
       Context context) {
+    return create(name, description, defaultValue, null, converter, context);
+  }
+
+  /** Utility method for creating a typed {@link ConnectionProperty}. */
+  @Nonnull
+  static <T> ConnectionProperty<T> create(
+      @Nonnull String name,
+      String description,
+      T defaultValue,
+      T[] validValues,
+      ClientSideStatementValueConverter<T> converter,
+      Context context) {
     return new ConnectionProperty<>(
-        null, name, description, defaultValue, null, converter, context);
+        null, name, description, defaultValue, validValues, converter, context);
   }
 
   /**
@@ -163,35 +176,38 @@ ConnectionPropertyValue<T> convert(@Nullable String stringValue) {
     return new ConnectionPropertyValue<>(this, convertedValue, convertedValue);
   }
 
-  String getKey() {
+  @Nonnull
+  public String getKey() {
     return this.key;
   }
 
-  boolean hasExtension() {
+  public boolean hasExtension() {
     return this.extension != null;
   }
 
-  String getExtension() {
+  public String getExtension() {
     return this.extension;
   }
 
-  String getName() {
+  @Nonnull
+  public String getName() {
     return this.name;
   }
 
-  String getDescription() {
+  @Nonnull
+  public String getDescription() {
     return this.description;
   }
 
-  T getDefaultValue() {
+  public T getDefaultValue() {
     return this.defaultValue;
   }
 
-  T[] getValidValues() {
+  public T[] getValidValues() {
     return this.validValues;
   }
 
-  Context getContext() {
+  public Context getContext() {
     return this.context;
   }
 }