JVMCBC-1679 Add cluster.setAuthenticator()

Motivation
----------
Simplify the credential rotation API.

Modifications
-------------
Add a setAuthenticator() method to Java and Kotlin's
`Cluster` classes.

Mark `DelegatingAuthenticator` as internal API,
and remove references to it from Javadoc.

Change-Id: I46d9b2ed45542662acb3fe49e419fa583d0688b2
Reviewed-on: https://review.couchbase.org/c/couchbase-jvm-clients/+/234329
Tested-by: Build Bot <[email protected]>
Reviewed-by: Will Broadbelt <[email protected]>

Author: dnault

core-io/src/main/java/com/couchbase/client/core/env/Authenticator.java

@@ -34,7 +34,6 @@
  * @see PasswordAuthenticator
  * @see JwtAuthenticator
  * @see CertificateAuthenticator
- * @see DelegatingAuthenticator
  *
  * @since 2.0.0
  */

core-io/src/main/java/com/couchbase/client/core/env/DelegatingAuthenticator.java

@@ -16,6 +16,7 @@
 
 package com.couchbase.client.core.env;
 
+import com.couchbase.client.core.annotation.Stability;
 import org.jspecify.annotations.NullMarked;
 
 import static java.util.Objects.requireNonNull;
@@ -29,6 +30,7 @@
  * @see #create(Authenticator)
  */
 @NullMarked
+@Stability.Internal
 public class DelegatingAuthenticator extends AuthenticatorWrapper {
   private volatile Authenticator delegate;
 

core-io/src/main/java/com/couchbase/client/core/env/PasswordAuthenticator.java

@@ -89,7 +89,7 @@ public static PasswordAuthenticator.Builder builder(String username, String pass
    * in the volatile field.
    *
    * @deprecated This method is difficult to use safely, because it's easy to accidentally
-   * do blocking IO inside the supplier. Please use {@link DelegatingAuthenticator} instead.
+   * do blocking IO inside the supplier. Please use {@code cluster.setAuthenticator(newAuthenticator)} instead.
    */
   @Deprecated
   public static PasswordAuthenticator.Builder builder(Supplier<UsernameAndPassword> supplier) {
@@ -236,7 +236,7 @@ public Builder username(final String username) {
      * @param username A supplier that returns the username to use.
      * @return this builder for chaining purposes.
      * @deprecated This method does not support returning username and password as an atomic unit.
-     * Please use {@link DelegatingAuthenticator} instead.
+     * Please use {@code cluster.setAuthenticator(newAuthenticator)} instead.
      */
     @Deprecated
     public Builder username(final Supplier<String> username) {
@@ -278,7 +278,7 @@ public Builder password(final String password) {
      * @param password the password to alongside for the username provided.
      * @return this builder for chaining purposes.
      * @deprecated This method does not support returning username and password as an atomic unit.
-     * Please use {@link DelegatingAuthenticator} instead.
+     * Please use {@code cluster.setAuthenticator(newAuthenticator)} instead.
      */
     @Deprecated
     public Builder password(final Supplier<String> password) {

java-client/src/main/java/com/couchbase/client/java/AsyncCluster.java

@@ -35,6 +35,7 @@
 import com.couchbase.client.core.env.Authenticator;
 import com.couchbase.client.core.env.ConnectionStringPropertyLoader;
 import com.couchbase.client.core.env.CoreEnvironment;
+import com.couchbase.client.core.env.DelegatingAuthenticator;
 import com.couchbase.client.core.env.OwnedOrExternal;
 import com.couchbase.client.core.env.PasswordAuthenticator;
 import com.couchbase.client.core.env.SeedNode;
@@ -137,7 +138,7 @@ public class AsyncCluster {
 
   private final CoreCouchbaseOps couchbaseOps;
 
-  private final Authenticator authenticator;
+  private final DelegatingAuthenticator authenticator;
 
   /**
    * Stores already opened buckets for reuse.
@@ -244,13 +245,13 @@ String clusterToStringHelper(Class clusterClass) {
    */
   AsyncCluster(
     final OwnedOrExternal<ClusterEnvironment> environment,
-    final Authenticator authenticator,
+    final Authenticator initialAuthenticator,
     final ConnectionString connectionString
   ) {
     this.environment = environment;
     this.connectionString = connectionString;
-    this.couchbaseOps = CoreCouchbaseOps.create(environment.get(), authenticator, connectionString);
-    this.authenticator = authenticator;
+    this.authenticator = DelegatingAuthenticator.create(initialAuthenticator);
+    this.couchbaseOps = CoreCouchbaseOps.create(environment.get(), this.authenticator, connectionString);
     this.queryOps = couchbaseOps.queryOps();
     this.searchOps = couchbaseOps.searchOps(null);
 
@@ -268,6 +269,10 @@ String clusterToStringHelper(Class clusterClass) {
     ));
   }
 
+  public void setAuthenticator(Authenticator newAuthenticator) {
+    authenticator.setDelegate(newAuthenticator);
+  }
+
   /**
    * Provides access to the configured {@link ClusterEnvironment} for this cluster.
    */

java-client/src/main/java/com/couchbase/client/java/Cluster.java

@@ -317,6 +317,10 @@ public ReactiveCluster reactive() {
     return reactiveCluster;
   }
 
+  public void setAuthenticator(Authenticator newAuthenticator) {
+    asyncCluster.setAuthenticator(newAuthenticator);
+  }
+
   /**
    * Provides access to the underlying {@link Core}.
    *

java-client/src/main/java/com/couchbase/client/java/ReactiveCluster.java

@@ -188,6 +188,10 @@ private ReactiveCluster(
     this.reactor = asyncCluster.environment();
   }
 
+  public void setAuthenticator(Authenticator newAuthenticator) {
+    asyncCluster.setAuthenticator(newAuthenticator);
+  }
+
   /**
    * Provides access to the underlying {@link Core}.
    *

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/Cluster.kt

@@ -27,6 +27,7 @@ import com.couchbase.client.core.diagnostics.HealthPinger
 import com.couchbase.client.core.env.Authenticator
 import com.couchbase.client.core.env.CertificateAuthenticator
 import com.couchbase.client.core.env.ConnectionStringPropertyLoader
+import com.couchbase.client.core.env.DelegatingAuthenticator
 import com.couchbase.client.core.env.PasswordAuthenticator
 import com.couchbase.client.core.error.UnambiguousTimeoutException
 import com.couchbase.client.core.service.ServiceType
@@ -117,12 +118,19 @@ import kotlin.time.toKotlinDuration
 public class Cluster internal constructor(
     internal val env: ClusterEnvironment,
     private val ownsEnvironment: Boolean,
-    private val authenticator: Authenticator,
+    initialAuthenticator: Authenticator,
     connectionString: ConnectionString,
 ) {
-    private val couchbaseOps = CoreCouchbaseOps.create(env, authenticator, connectionString)
+    private val delegatingAuthenticator: DelegatingAuthenticator = DelegatingAuthenticator.create(initialAuthenticator)
+
+    private val couchbaseOps = CoreCouchbaseOps.create(env, delegatingAuthenticator, connectionString)
     private val searchOps = couchbaseOps.searchOps(null)
 
+    public var authenticator: Authenticator
+        @Deprecated("Property 'authenticator' is write-only.", level = DeprecationLevel.ERROR)
+        get() = throw UnsupportedOperationException()
+        set(value) { this.delegatingAuthenticator.setDelegate(value) }
+
     internal val core: Core
         get() = couchbaseOps.asCore()