feat: Add ConnectorRegistry.reset() and update shutdown()

Fixes #1687
Fixes #776

Author: hessjcg

core/src/main/java/com/google/cloud/sql/ConnectorRegistry.java

@@ -49,6 +49,14 @@ public static void shutdown() {
     InternalConnectorRegistry.shutdownInstance();
   }
 
+  /**
+   * Resets the entire CloudSQL JDBC Connector. This will stop all background threads. The next
+   * attempt to open a connection or register a configuration will start a new ConnectorRegistry.
+   */
+  public static void reset() {
+    InternalConnectorRegistry.resetInstance();
+  }
+
   /**
    * Adds an external application name to the user agent string for tracking. This is known to be
    * used by the spring-cloud-gcp project.

core/src/main/java/com/google/cloud/sql/core/InternalConnectorRegistry.java

@@ -55,6 +55,7 @@ public final class InternalConnectorRegistry {
   private static final String version = getVersion();
   private static final long MIN_REFRESH_DELAY_MS = 30000; // Minimum 30 seconds between refresh.
   private static InternalConnectorRegistry internalConnectorRegistry;
+  private static boolean shutdown = false;
   private final ListenableFuture<KeyPair> localKeyPair;
   private final ConcurrentHashMap<ConnectorConfig, Connector> unnamedConnectors =
       new ConcurrentHashMap<>();
@@ -91,6 +92,10 @@ public final class InternalConnectorRegistry {
 
   /** Returns the {@link InternalConnectorRegistry} singleton. */
   public static synchronized InternalConnectorRegistry getInstance() {
+    if (shutdown) {
+      throw new IllegalStateException("ConnectorRegistry was shut down.");
+    }
+
     if (internalConnectorRegistry == null) {
       logger.debug("First Cloud SQL connection, generating RSA key pair.");
 
@@ -114,14 +119,24 @@ public static synchronized InternalConnectorRegistry getInstance() {
    * Calls shutdown on the singleton and removes the singleton. After calling shutdownInstance(),
    * the next call to getInstance() will start a new singleton instance.
    */
-  public static synchronized void shutdownInstance() {
+  public static synchronized void resetInstance() {
     if (internalConnectorRegistry != null) {
       InternalConnectorRegistry old = internalConnectorRegistry;
       internalConnectorRegistry = null;
       old.shutdown();
+      resetUserAgent();
     }
   }
 
+  /**
+   * Calls shutdown on the singleton and removes the singleton. After calling shutdownInstance(),
+   * the next call to getInstance() will start a new singleton instance.
+   */
+  public static synchronized void shutdownInstance() {
+    shutdown = true;
+    resetInstance();
+  }
+
   // TODO(kvg): Figure out better executor to use for testing
   @VisibleForTesting
   // Returns a listenable, scheduled executor that exits upon shutdown.

docs/configuration.md

@@ -182,20 +182,33 @@ No updates to the database connection pool are required.
 Existing open connections in the pool will continue to work until they are
 closed. New connections will be established using the new configuration.
 
-### Shutdown The Connector Registry
+### Reset The Connector Registry
 
 The application may shut down the ConnectorRegistry. This closes all existing
 named and unnamed connectors, and stops internal background threads.
 
 ```java
-ConnectorRegistry.shutdown();
+ConnectorRegistry.reset();
 ```
 
-After calling `ConnectorRegistry.shutdown()`, the next attempt to connect to a
+After calling `ConnectorRegistry.reset()`, the next attempt to connect to a
 database using a SocketFactory or R2DBC ConnectionFactory, or
 to `ConnectorRegistry.register()` will start a new connector registry, restart
 the background threads, and create a new connector.
 
+### Shutdown The Connector Registry
+
+The application may shut down the ConnectorRegistry. This closes all existing
+named and unnamed connectors, and stops internal background threads.
+
+```java
+ConnectorRegistry.shutdown();
+```
+
+After calling `ConnectorRegistry.shutdown()`, subsequent attempts to connect to
+a database using a SocketFactory or R2DBC ConnectionFactory, or
+to `ConnectorRegistry.register()` will fail, throwing `IllegalStateException`.
+
 ## Configuring Google Credentials
 
 By default, connectors will use the Google Application Default credentials to