cleanup: remove deprecated ConnectionProperty class (#3701)

Removes the deprecated ConnectionOptions$ConnectionProperty class. This class is
defined in the com.google.cloud.spanner.connection package, which is marked as an
internal API package. In addition, the enclosing ConnectionProperties class is also
marked as `@InternalApi`, which makes it acceptable to remove this class without
doing a major version bump.

Author: olavloite

google-cloud-spanner/clirr-ignored-differences.xml

@@ -850,4 +850,16 @@
     <className>com/google/cloud/spanner/connection/Connection</className>
     <method>java.lang.String getDefaultSequenceKind()</method>
   </difference>
+
+  <!-- Removed ConnectionOptions$ConnectionProperty in favor of the more generic ConnectionProperty class. -->
+  <difference>
+    <differenceType>8001</differenceType>
+    <className>com/google/cloud/spanner/connection/ConnectionOptions$ConnectionProperty</className>
+  </difference>
+  <difference>
+    <differenceType>6001</differenceType>
+    <className>com/google/cloud/spanner/connection/ConnectionOptions</className>
+    <field>VALID_PROPERTIES</field>
+  </difference>
+  
 </differences>

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

@@ -79,21 +79,17 @@
 import com.google.common.base.Strings;
 import com.google.common.base.Suppliers;
 import com.google.common.collect.ImmutableMap;
-import com.google.common.collect.Sets;
 import io.opentelemetry.api.OpenTelemetry;
 import java.io.IOException;
 import java.net.URL;
 import java.time.Duration;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
-import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
@@ -127,90 +123,6 @@
  */
 @InternalApi
 public class ConnectionOptions {
-  /**
-   * Supported connection properties that can be included in the connection URI.
-   *
-   * @deprecated Replaced by {@link com.google.cloud.spanner.connection.ConnectionProperty}.
-   */
-  @Deprecated
-  public static class ConnectionProperty {
-    private static final String[] BOOLEAN_VALUES = new String[] {"true", "false"};
-    private final String name;
-    private final String description;
-    private final String defaultValue;
-    private final String[] validValues;
-    private final int hashCode;
-
-    private static ConnectionProperty createStringProperty(String name, String description) {
-      return new ConnectionProperty(name, description, "", null);
-    }
-
-    private static ConnectionProperty createBooleanProperty(
-        String name, String description, Boolean defaultValue) {
-      return new ConnectionProperty(
-          name,
-          description,
-          defaultValue == null ? "" : String.valueOf(defaultValue),
-          BOOLEAN_VALUES);
-    }
-
-    private static ConnectionProperty createIntProperty(
-        String name, String description, int defaultValue) {
-      return new ConnectionProperty(name, description, String.valueOf(defaultValue), null);
-    }
-
-    private static ConnectionProperty createEmptyProperty(String name) {
-      return new ConnectionProperty(name, "", "", null);
-    }
-
-    private ConnectionProperty(
-        String name, String description, String defaultValue, String[] validValues) {
-      Preconditions.checkNotNull(name);
-      Preconditions.checkNotNull(description);
-      Preconditions.checkNotNull(defaultValue);
-      this.name = name;
-      this.description = description;
-      this.defaultValue = defaultValue;
-      this.validValues = validValues;
-      this.hashCode = name.toLowerCase().hashCode();
-    }
-
-    @Override
-    public int hashCode() {
-      return hashCode;
-    }
-
-    @Override
-    public boolean equals(Object o) {
-      if (!(o instanceof ConnectionProperty)) {
-        return false;
-      }
-      return ((ConnectionProperty) o).name.equalsIgnoreCase(this.name);
-    }
-
-    /** @return the name of this connection property. */
-    public String getName() {
-      return name;
-    }
-
-    /** @return the description of this connection property. */
-    public String getDescription() {
-      return description;
-    }
-
-    /** @return the default value of this connection property. */
-    public String getDefaultValue() {
-      return defaultValue;
-    }
-
-    /**
-     * @return the valid values for this connection property. <code>null</code> indicates no
-     *     restriction.
-     */
-    public String[] getValidValues() {
-      return validValues;
-    }
-  }
 
   /**
    * Set this system property to true to enable transactional connection state by default for
@@ -380,210 +292,6 @@ static boolean isEnableTransactionalConnectionStateForPostgreSQL() {
         System.getProperty(ENABLE_TRANSACTIONAL_CONNECTION_STATE_FOR_POSTGRESQL_PROPERTY, "false"));
   }
 
-  /**
-   * All valid connection properties.
-   *
-   * @deprecated Replaced by {@link ConnectionProperties#CONNECTION_PROPERTIES}
-   */
-  @Deprecated
-  public static final Set<ConnectionProperty> VALID_PROPERTIES =
-      Collections.unmodifiableSet(
-          new HashSet<>(
-              Arrays.asList(
-                  ConnectionProperty.createBooleanProperty(
-                      AUTOCOMMIT_PROPERTY_NAME,
-                      "Should the connection start in autocommit (true/false)",
-                      DEFAULT_AUTOCOMMIT),
-                  ConnectionProperty.createBooleanProperty(
-                      READONLY_PROPERTY_NAME,
-                      "Should the connection start in read-only mode (true/false)",
-                      DEFAULT_READONLY),
-                  ConnectionProperty.createBooleanProperty(
-                      ROUTE_TO_LEADER_PROPERTY_NAME,
-                      "Should read/write transactions and partitioned DML be routed to leader region (true/false)",
-                      DEFAULT_ROUTE_TO_LEADER),
-                  ConnectionProperty.createBooleanProperty(
-                      RETRY_ABORTS_INTERNALLY_PROPERTY_NAME,
-                      "Should the connection automatically retry Aborted errors (true/false)",
-                      DEFAULT_RETRY_ABORTS_INTERNALLY),
-                  ConnectionProperty.createBooleanProperty(
-                      USE_VIRTUAL_THREADS_PROPERTY_NAME,
-                      "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),
-                  ConnectionProperty.createBooleanProperty(
-                      USE_VIRTUAL_GRPC_TRANSPORT_THREADS_PROPERTY_NAME,
-                      "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),
-                  ConnectionProperty.createStringProperty(
-                      CREDENTIALS_PROPERTY_NAME,
-                      "The location of the credentials file to use for this connection. If neither this property or encoded credentials are set, the connection will use the default Google Cloud credentials for the runtime environment."),
-                  ConnectionProperty.createStringProperty(
-                      ENCODED_CREDENTIALS_PROPERTY_NAME,
-                      "Base64-encoded credentials to use for this connection. If neither this property or a credentials location are set, the connection will use the default Google Cloud credentials for the runtime environment."),
-                  ConnectionProperty.createStringProperty(
-                      CREDENTIALS_PROVIDER_PROPERTY_NAME,
-                      "The class name of the com.google.api.gax.core.CredentialsProvider implementation that should be used to obtain credentials for connections."),
-                  ConnectionProperty.createStringProperty(
-                      OAUTH_TOKEN_PROPERTY_NAME,
-                      "A valid pre-existing OAuth token to use for authentication for this connection. Setting this property will take precedence over any value set for a credentials file."),
-                  ConnectionProperty.createStringProperty(
-                      MIN_SESSIONS_PROPERTY_NAME,
-                      "The minimum number of sessions in the backing session pool. The default is 100."),
-                  ConnectionProperty.createStringProperty(
-                      MAX_SESSIONS_PROPERTY_NAME,
-                      "The maximum number of sessions in the backing session pool. The default is 400."),
-                  ConnectionProperty.createStringProperty(
-                      NUM_CHANNELS_PROPERTY_NAME,
-                      "The number of gRPC channels to use to communicate with Cloud Spanner. The default is 4."),
-                  ConnectionProperty.createStringProperty(
-                      ENDPOINT_PROPERTY_NAME,
-                      "The endpoint that the JDBC driver should connect to. "
-                          + "The default is the default Spanner production endpoint when autoConfigEmulator=false, "
-                          + "and the default Spanner emulator endpoint (localhost:9010) when autoConfigEmulator=true. "
-                          + "This property takes precedence over any host name at the start of the connection URL."),
-                  ConnectionProperty.createStringProperty(
-                      CHANNEL_PROVIDER_PROPERTY_NAME,
-                      "The name of the channel provider class. The name must reference an implementation of ExternalChannelProvider. If this property is not set, the connection will use the default grpc channel provider."),
-                  ConnectionProperty.createBooleanProperty(
-                      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),
-                  ConnectionProperty.createBooleanProperty(
-                      IS_EXPERIMENTAL_HOST_PROPERTY_NAME,
-                      "Set this value to true for communication with an Experimental Host.",
-                      DEFAULT_IS_EXPERIMENTAL_HOST),
-                  ConnectionProperty.createStringProperty(
-                      CLIENT_CERTIFICATE_PROPERTY_NAME,
-                      "Specifies the file path to the client certificate required for establishing an mTLS connection."),
-                  ConnectionProperty.createStringProperty(
-                      CLIENT_KEY_PROPERTY_NAME,
-                      "Specifies the file path to the client private key required for establishing an mTLS connection."),
-                  ConnectionProperty.createStringProperty(
-                      USER_AGENT_PROPERTY_NAME,
-                      "The custom user-agent property name to use when communicating with Cloud Spanner. This property is intended for internal library usage, and should not be set by applications."),
-                  ConnectionProperty.createStringProperty(
-                      OPTIMIZER_VERSION_PROPERTY_NAME,
-                      "Sets the default query optimizer version to use for this connection."),
-                  ConnectionProperty.createStringProperty(
-                      OPTIMIZER_STATISTICS_PACKAGE_PROPERTY_NAME, ""),
-                  ConnectionProperty.createBooleanProperty(
-                      "returnCommitStats", "", DEFAULT_RETURN_COMMIT_STATS),
-                  ConnectionProperty.createStringProperty(
-                      "maxCommitDelay",
-                      "The maximum commit delay in milliseconds that should be applied to commit requests from this connection."),
-                  ConnectionProperty.createBooleanProperty(
-                      "autoConfigEmulator",
-                      "Automatically configure the connection to try to connect to the Cloud Spanner emulator (true/false). "
-                          + "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),
-                  ConnectionProperty.createBooleanProperty(
-                      "useAutoSavepointsForEmulator",
-                      "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),
-                  ConnectionProperty.createBooleanProperty(
-                      LENIENT_PROPERTY_NAME,
-                      "Silently ignore unknown properties in the connection string/properties (true/false)",
-                      DEFAULT_LENIENT),
-                  ConnectionProperty.createStringProperty(
-                      RPC_PRIORITY_NAME,
-                      "Sets the priority for all RPC invocations from this connection (HIGH/MEDIUM/LOW). The default is HIGH."),
-                  ConnectionProperty.createStringProperty(
-                      DDL_IN_TRANSACTION_MODE_PROPERTY_NAME,
-                      "Sets the behavior of a connection when a DDL statement is executed in a read/write transaction. The default is "
-                          + DEFAULT_DDL_IN_TRANSACTION_MODE
-                          + "."),
-                  ConnectionProperty.createStringProperty(
-                      DIALECT_PROPERTY_NAME,
-                      "Sets the dialect to use for new databases that are created by this connection."),
-                  ConnectionProperty.createStringProperty(
-                      DATABASE_ROLE_PROPERTY_NAME,
-                      "Sets the database role to use for this connection. The default is privileges assigned to IAM role"),
-                  ConnectionProperty.createBooleanProperty(
-                      DELAY_TRANSACTION_START_UNTIL_FIRST_WRITE_NAME,
-                      "Enabling this option will delay the actual start of a read/write transaction until the first write operation is seen in that transaction. "
-                          + "All reads that happen before the first write in a transaction will instead be executed as if the connection was in auto-commit mode. "
-                          + "Enabling this option will make read/write transactions lose their SERIALIZABLE isolation level. Read operations that are executed after "
-                          + "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),
-                  ConnectionProperty.createBooleanProperty(
-                      KEEP_TRANSACTION_ALIVE_PROPERTY_NAME,
-                      "Enabling this option will trigger the connection to keep read/write transactions alive by executing a SELECT 1 query once every 10 seconds "
-                          + "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),
-                  ConnectionProperty.createBooleanProperty(
-                      TRACK_SESSION_LEAKS_PROPERTY_NAME,
-                      "Capture the call stack of the thread that checked out a session of the session pool. This will "
-                          + "pre-create a LeakedSessionException already when a session is checked out. This can be disabled, "
-                          + "for example if a monitoring system logs the pre-created exception. "
-                          + "If disabled, the LeakedSessionException will only be created when an "
-                          + "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),
-                  ConnectionProperty.createBooleanProperty(
-                      TRACK_CONNECTION_LEAKS_PROPERTY_NAME,
-                      "Capture the call stack of the thread that created a connection. This will "
-                          + "pre-create a LeakedConnectionException already when a connection is created. "
-                          + "This can be disabled, for example if a monitoring system logs the pre-created exception. "
-                          + "If disabled, the LeakedConnectionException will only be created when an "
-                          + "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),
-                  ConnectionProperty.createBooleanProperty(
-                      DATA_BOOST_ENABLED_PROPERTY_NAME,
-                      "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),
-                  ConnectionProperty.createBooleanProperty(
-                      AUTO_PARTITION_MODE_PROPERTY_NAME,
-                      "Execute all queries on this connection as partitioned queries. "
-                          + "Executing a query that cannot be partitioned will fail. "
-                          + "Executing a query in a read/write transaction will also fail.",
-                      DEFAULT_AUTO_PARTITION_MODE),
-                  ConnectionProperty.createIntProperty(
-                      MAX_PARTITIONS_PROPERTY_NAME,
-                      "The max partitions hint value to use for partitioned queries. "
-                          + "Use 0 if you do not want to specify a hint.",
-                      DEFAULT_MAX_PARTITIONS),
-                  ConnectionProperty.createIntProperty(
-                      MAX_PARTITIONED_PARALLELISM_PROPERTY_NAME,
-                      "The maximum number of partitions that will be executed in parallel "
-                          + "for partitioned queries on this connection. Set this value to 0 to "
-                          + "dynamically use the number of processors available in the runtime.",
-                      DEFAULT_MAX_PARTITIONED_PARALLELISM),
-                  ConnectionProperty.createBooleanProperty(
-                      ENABLE_EXTENDED_TRACING_PROPERTY_NAME,
-                      "Include the SQL string in the OpenTelemetry traces that are generated "
-                          + "by this connection. The SQL string is added as the standard OpenTelemetry "
-                          + "attribute 'db.statement'.",
-                      DEFAULT_ENABLE_EXTENDED_TRACING),
-                  ConnectionProperty.createBooleanProperty(
-                      ENABLE_API_TRACING_PROPERTY_NAME,
-                      "Add OpenTelemetry traces for each individual RPC call. Enable this "
-                          + "to get a detailed view of each RPC that is being executed by your application, "
-                          + "or if you want to debug potential latency problems caused by RPCs that are "
-                          + "being retried.",
-                      DEFAULT_ENABLE_API_TRACING),
-                  ConnectionProperty.createBooleanProperty(
-                      ENABLE_END_TO_END_TRACING_PROPERTY_NAME,
-                      "Enable end-to-end tracing (true/false) to generate traces for both the time "
-                          + "that is spent in the client, as well as time that is spent in the Spanner server. "
-                          + "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))));
-
-  private static final Set<ConnectionProperty> INTERNAL_PROPERTIES =
-      Collections.unmodifiableSet(
-          new HashSet<>(
-              Collections.singletonList(
-                  ConnectionProperty.createStringProperty(USER_AGENT_PROPERTY_NAME, ""))));
-  private static final Set<ConnectionProperty> INTERNAL_VALID_PROPERTIES =
-      Sets.union(VALID_PROPERTIES, INTERNAL_PROPERTIES);
-
   /**
    * Gets the default project-id for the current environment as defined by {@link
    * ServiceOptions#getDefaultProjectId()}, and if none could be found, the project-id of the given

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

@@ -125,11 +125,7 @@
 import com.google.spanner.v1.DirectedReadOptions;
 import java.time.Duration;
 
-/**
- * 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}.
- */
+/** Utility class that defines all known connection properties. */
 public class ConnectionProperties {
   private static final ImmutableMap.Builder<String, ConnectionProperty<?>>
       CONNECTION_PROPERTIES_BUILDER = ImmutableMap.builder();