SyncClient: support multiple URLs, move adding credentials to builder

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/sync/Sync.java

@@ -16,6 +16,9 @@
 
 package io.objectbox.sync;
 
+import java.util.Collections;
+import java.util.List;
+
 import io.objectbox.BoxStore;
 import io.objectbox.BoxStoreBuilder;
 import io.objectbox.sync.server.SyncServer;
@@ -50,6 +53,43 @@ public static boolean isHybridAvailable() {
         return isAvailable() && isServerAvailable();
     }
 
+    /**
+     * Starts building a {@link SyncClient} for the given {@link BoxStore} and server URL.
+     * <p>
+     * This does not initiate any connection attempts yet: call {@link SyncBuilder#buildAndStart()} to do so. Before,
+     * you must configure credentials via {@link SyncBuilder#credentials(SyncCredentials)}.
+     * <p>
+     * By default, a Sync client automatically receives updates from the server once login succeeded. To configure this
+     * differently, call {@link SyncBuilder#requestUpdatesMode(SyncBuilder.RequestUpdatesMode)} with the wanted mode.
+     *
+     * @param boxStore The {@link BoxStore} the client should use.
+     * @param url The URL of the Sync server on which the Sync protocol is exposed. This is typically a WebSockets URL
+     * starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
+     * {@code ws://127.0.0.1:9999}.
+     * @return a builder to configure the Sync client
+     * @see #client(BoxStore, List)
+     */
+    public static SyncBuilder client(BoxStore boxStore, String url) {
+        return client(boxStore, Collections.singletonList(url));
+    }
+
+    /**
+     * Like {@link #client(BoxStore, String)}, but supports passing multiple URLs.
+     * <p>
+     * Passing multiple URLs allows high availability and load balancing (i.e. using an ObjectBox Sync Server Cluster).
+     * <p>
+     * A random URL is selected for each connection attempt.
+     *
+     * @param boxStore The {@link BoxStore} the client should use.
+     * @param urls A list of URLs of Sync servers on which the Sync protocol is exposed. These are typically WebSockets
+     * URLs starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
+     * {@code ws://127.0.0.1:9999}.
+     * @return a builder to configure the Sync client
+     */
+    public static SyncBuilder client(BoxStore boxStore, List<String> urls) {
+        return new SyncBuilder(boxStore, urls);
+    }
+
     /**
      * Starts building a {@link SyncClient}. Once done, complete with {@link SyncBuilder#build() build()}.
      *
@@ -58,18 +98,31 @@ public static boolean isHybridAvailable() {
      * starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
      * {@code ws://127.0.0.1:9999}.
      * @param credentials {@link SyncCredentials} to authenticate with the server.
+     * @deprecated Use {@link #client(BoxStore, String)} and {@link SyncBuilder#credentials(SyncCredentials)} instead.
      */
+    @Deprecated
     public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials credentials) {
-        return new SyncBuilder(boxStore, url, credentials);
+        SyncBuilder builder = client(boxStore, url);
+        builder.credentials(credentials);
+        return builder;
     }
 
     /**
      * Like {@link #client(BoxStore, String, SyncCredentials)}, but supports passing a set of authentication methods.
      *
      * @param multipleCredentials An array of {@link SyncCredentials} to be used to authenticate with the server.
+     * @deprecated Use {@link #client(BoxStore, String)} and {@link SyncBuilder#credentials(SyncCredentials)} instead.
      */
+    @Deprecated
     public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials[] multipleCredentials) {
-        return new SyncBuilder(boxStore, url, multipleCredentials);
+        SyncBuilder builder = client(boxStore, url);
+        //noinspection ConstantValue
+        if (multipleCredentials != null) {
+            for (SyncCredentials credentials : multipleCredentials) {
+                builder.credentials(credentials);
+            }
+        }
+        return builder;
     }
 
     /**

objectbox-java/src/main/java/io/objectbox/sync/SyncBuilder.java

@@ -16,8 +16,8 @@
 
 package io.objectbox.sync;
 
+import java.util.ArrayList;
 import java.util.Arrays;
-import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 import java.util.TreeMap;
@@ -44,8 +44,13 @@ public final class SyncBuilder {
 
     final Platform platform;
     final BoxStore boxStore;
-    @Nullable private String url;
-    final List<SyncCredentials> credentials;
+    /**
+     * The server URLs this client may connect to.
+     * <p>
+     * See {@link Sync#client(BoxStore, List)} for notes on multiple URLs.
+     */
+    final List<String> urls = new ArrayList<>();
+    final List<SyncCredentials> credentials = new ArrayList<>();
 
     @Nullable SyncLoginListener loginListener;
     @Nullable SyncCompletedListener completedListener;
@@ -98,49 +103,42 @@ private static void checkSyncFeatureAvailable() {
         }
     }
 
-    private SyncBuilder(BoxStore boxStore, @Nullable String url, @Nullable List<SyncCredentials> credentials) {
-        checkNotNull(boxStore, "BoxStore is required.");
-        checkNotNull(credentials, "Sync credentials are required.");
+    /**
+     * Creates a builder for a {@link SyncClient}.
+     * <p>
+     * Don't use this directly, use the {@link Sync#client} methods instead.
+     */
+    SyncBuilder(BoxStore boxStore, List<String> urls) {
+        checkNotNull(boxStore, "boxStore");
+        checkNotNull(urls, "urls");
         this.boxStore = boxStore;
-        this.url = url;
-        this.credentials = credentials;
+        // For SyncHybridBuilder, delay validating there is a URL until the build call
+        for (String url : urls) {
+            url(url);
+        }
         checkSyncFeatureAvailable();
         this.platform = Platform.findPlatform(); // Requires APIs only present in Android Sync library
     }
 
-    @Internal
-    public SyncBuilder(BoxStore boxStore, String url, @Nullable SyncCredentials credentials) {
-        this(boxStore, url, credentials == null ? null : Collections.singletonList(credentials));
-    }
-
-    @Internal
-    public SyncBuilder(BoxStore boxStore, String url, @Nullable SyncCredentials[] multipleCredentials) {
-        this(boxStore, url, multipleCredentials == null ? null : Arrays.asList(multipleCredentials));
-    }
-
     /**
-     * When using this constructor, make sure to set the server URL before starting.
+     * Allows internal code to set the Sync server URL after creating this builder.
      */
     @Internal
-    public SyncBuilder(BoxStore boxStore, @Nullable SyncCredentials credentials) {
-        this(boxStore, null, credentials == null ? null : Collections.singletonList(credentials));
+    SyncBuilder url(String url) {
+        checkNotNull(url, "url");
+        this.urls.add(url);
+        return this;
     }
 
     /**
-     * Allows internal code to set the Sync server URL after creating this builder.
+     * Adds {@link SyncCredentials} to authenticate the client with the server.
      */
-    @Internal
-    SyncBuilder serverUrl(String url) {
-        this.url = url;
+    public SyncBuilder credentials(SyncCredentials credentials) {
+        checkNotNull(credentials, "credentials");
+        this.credentials.add(credentials);
         return this;
     }
 
-    @Internal
-    String serverUrl() {
-        checkNotNull(url, "Sync Server URL is null.");
-        return url;
-    }
-
     /**
      * Adds or replaces a <a href="https://sync.objectbox.io/sync-server/sync-filters">Sync filter</a> variable value
      * for the given name.
@@ -151,8 +149,8 @@ String serverUrl() {
      * @see SyncClient#putFilterVariable
      */
     public SyncBuilder filterVariable(String name, String value) {
-        checkNotNull(name, "Filter variable name is null.");
-        checkNotNull(value, "Filter variable value is null.");
+        checkNotNull(name, "name");
+        checkNotNull(value, "value");
         filterVariables.put(name, value);
         return this;
     }
@@ -265,23 +263,25 @@ public SyncClient build() {
         if (boxStore.getSyncClient() != null) {
             throw new IllegalStateException("The given store is already associated with a Sync client, close it first.");
         }
-        checkNotNull(url, "Sync Server URL is required.");
         return new SyncClientImpl(this);
     }
 
     /**
-     * Builds, {@link SyncClient#start() starts} and returns a Sync client.
+     * {@link #build() Builds}, {@link SyncClient#start() starts} and returns a Sync client.
      */
     public SyncClient buildAndStart() {
         SyncClient syncClient = build();
         syncClient.start();
         return syncClient;
     }
 
-    private void checkNotNull(@Nullable Object object, String message) {
-        //noinspection ConstantConditions Non-null annotation does not enforce, so check for null.
+    /**
+     * Nullness annotations are only a hint in Java, so explicitly check nonnull annotated parameters
+     * (see package-info.java for package settings).
+     */
+    private void checkNotNull(@Nullable Object object, String name) {
         if (object == null) {
-            throw new IllegalArgumentException(message);
+            throw new IllegalArgumentException(name + " must not be null.");
         }
     }
 

objectbox-java/src/main/java/io/objectbox/sync/SyncClient.java

@@ -17,9 +17,11 @@
 package io.objectbox.sync;
 
 import java.io.Closeable;
+import java.util.List;
 
 import javax.annotation.Nullable;
 
+import io.objectbox.BoxStore;
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.sync.SyncBuilder.RequestUpdatesMode;
 import io.objectbox.sync.listener.SyncChangeListener;
@@ -42,9 +44,19 @@ public interface SyncClient extends Closeable {
 
     /**
      * Gets the sync server URL this client is connected to.
+     *
+     * @deprecated Use {@link #getUrls()}
      */
+    @Deprecated
     String getServerUrl();
 
+    /**
+     * Gets the sync server URLs this client may connect to.
+     * <p>
+     * See {@link Sync#client(BoxStore, List)} for notes on multiple URLs.
+     */
+    List<String> getUrls();
+
     /**
      * Flag indicating if the sync client was started.
      * Started clients try to connect, login, and sync with the sync destination.

objectbox-java/src/main/java/io/objectbox/sync/SyncClientImpl.java

@@ -16,6 +16,7 @@
 
 package io.objectbox.sync;
 
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
@@ -43,7 +44,7 @@ public final class SyncClientImpl implements SyncClient {
 
     @Nullable
     private BoxStore boxStore;
-    private final String serverUrl;
+    private final List<String> urls;
     private final InternalSyncClientListener internalListener;
     @Nullable
     private final ConnectivityMonitor connectivityMonitor;
@@ -62,7 +63,7 @@ public final class SyncClientImpl implements SyncClient {
 
     SyncClientImpl(SyncBuilder builder) {
         this.boxStore = builder.boxStore;
-        this.serverUrl = builder.serverUrl();
+        this.urls = builder.urls;
         this.connectivityMonitor = builder.platform.getConnectivityMonitor();
 
         // Build the options
@@ -71,8 +72,10 @@ public final class SyncClientImpl implements SyncClient {
             throw new RuntimeException("Failed to create Sync client options: handle is zero.");
         }
         try {
-            // Add server URL
-            nativeSyncOptAddUrl(optHandle, serverUrl);
+            // Add all server URLs
+            for (String url : urls) {
+                nativeSyncOptAddUrl(optHandle, url);
+            }
 
             // Add trusted certificate paths if provided
             if (builder.trustedCertPaths != null) {
@@ -144,7 +147,13 @@ private long getHandle() {
 
     @Override
     public String getServerUrl() {
-        return serverUrl;
+        // nativeSyncOptCreateClient guarantees there is at least one URL
+        return getUrls().get(0);
+    }
+
+    @Override
+    public List<String> getUrls() {
+        return urls;
     }
 
     @Override

objectbox-java/src/main/java/io/objectbox/sync/SyncHybridBuilder.java

@@ -16,6 +16,8 @@
 
 package io.objectbox.sync;
 
+import java.util.Collections;
+
 import io.objectbox.BoxStore;
 import io.objectbox.BoxStoreBuilder;
 import io.objectbox.InternalAccess;
@@ -46,7 +48,7 @@ public final class SyncHybridBuilder {
         boxStore = storeBuilder.build();
         boxStoreServer = storeBuilderServer.build();
         SyncCredentials clientCredentials = authenticatorCredentials.createClone();
-        clientBuilder = new SyncBuilder(boxStore, clientCredentials);  // Do not yet set URL, port may be dynamic
+        clientBuilder = new SyncBuilder(boxStore, Collections.emptyList()).credentials(clientCredentials);  // Do not yet set URL, port may be dynamic
         serverBuilder = new SyncServerBuilder(boxStoreServer, url, authenticatorCredentials);
     }
 
@@ -75,7 +77,7 @@ public SyncHybrid buildAndStart() {
         SyncServer server = serverBuilder.buildAndStart();
 
         SyncClient client = clientBuilder
-                .serverUrl(server.getUrl())
+                .url(server.getUrl())
                 .buildAndStart();
 
         return new SyncHybrid(boxStore, client, boxStoreServer, server);

objectbox-java/src/main/java/io/objectbox/sync/package-info.java

@@ -18,17 +18,15 @@
  * <a href="https://objectbox.io/sync/">ObjectBox Sync</a> allows to automatically synchronize local data with a sync
  * destination (e.g. a sync server) and vice versa. This is the sync <b>client</b> package.
  * <p>
- * These are the typical steps to setup a sync client:
+ * These are the typical steps to set up a sync client:
  * <ol>
  *     <li>Create a BoxStore as usual (using MyObjectBox).</li>
- *     <li>Get a {@link io.objectbox.sync.SyncBuilder} using
- *     {@link io.objectbox.sync.Sync#client(io.objectbox.BoxStore, java.lang.String, io.objectbox.sync.SyncCredentials) Sync.client(boxStore, url, credentials)}.
- *     Here you need to pass the {@link io.objectbox.BoxStore BoxStore}, along with an URL to the sync destination (server),
- *     and credentials. For demo set ups, you could start with {@link io.objectbox.sync.SyncCredentials#none()}
- *     credentials.</li>
+ *     <li>Build a {@link io.objectbox.sync.SyncClient} using
+ *     {@link io.objectbox.sync.Sync#client(io.objectbox.BoxStore, java.lang.String) Sync.client(boxStore, url)} and at
+ *     least one set of credentials with {@link io.objectbox.sync.SyncBuilder#credentials(io.objectbox.sync.SyncCredentials)}.</li>
  *     <li>Optional: use the {@link io.objectbox.sync.SyncBuilder} instance from the last step to configure the sync
  *     client and set initial listeners.</li>
- *     <li>Call {@link io.objectbox.sync.SyncBuilder#build()} to get an instance of
+ *     <li>Call {@link io.objectbox.sync.SyncBuilder#buildAndStart()} to get an instance of
  *     {@link io.objectbox.sync.SyncClient} (and hold on to it). Synchronization is now active.</li>
  *     <li>Optional: Interact with {@link io.objectbox.sync.SyncClient}.</li>
  * </ol>

tests/objectbox-java-test/src/test/java/io/objectbox/sync/ConnectivityMonitorTest.java

@@ -18,6 +18,8 @@
 
 import org.junit.Test;
 
+import java.util.List;
+
 import javax.annotation.Nullable;
 
 import io.objectbox.sync.listener.SyncChangeListener;
@@ -114,6 +116,11 @@ public String getServerUrl() {
             return null;
         }
 
+        @Override
+        public List<String> getUrls() {
+            return null;
+        }
+
         @Override
         public boolean isStarted() {
             return false;

tests/objectbox-java-test/src/test/java/io/objectbox/sync/SyncTest.java

@@ -57,14 +57,10 @@ public void serverIsNotAvailable() {
 
     @Test
     public void creatingSyncClient_throws() {
-        // If no credentials are passed
-        assertThrows(IllegalArgumentException.class, () -> Sync.client(store, SERVER_URL, (SyncCredentials) null));
-        assertThrows(IllegalArgumentException.class, () -> Sync.client(store, SERVER_URL, (SyncCredentials[]) null));
-
         // If no Sync feature is available
         FeatureNotAvailableException exception = assertThrows(
                 FeatureNotAvailableException.class,
-                () -> Sync.client(store, SERVER_URL, SyncCredentials.none())
+                () -> Sync.client(store, SERVER_URL)
         );
         String message = exception.getMessage();
         assertTrue(message, message.contains("does not include ObjectBox Sync") &&