Merge branch '220-cluster-hybrid' into 'dev'

SyncHybrid (Server and Client) #220

See merge request objectbox/objectbox-java!144

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/BoxStoreBuilder.java

@@ -682,4 +682,43 @@ public BoxStore buildDefault() {
         BoxStore.setDefault(store);
         return store;
     }
-}
+
+
+    @Internal
+    BoxStoreBuilder createClone(String namePostfix) {
+        if (model == null) {
+            throw new IllegalStateException("BoxStoreBuilder must have a model");
+        }
+        if (initialDbFileFactory != null) {
+            throw new IllegalStateException("Initial DB files factories are not supported for sync-enabled DBs");
+        }
+
+        BoxStoreBuilder clone = new BoxStoreBuilder(model);
+        // Note: don't use absolute path for directories; it messes with in-memory paths ("memory:")
+        clone.directory = this.directory != null ? new File(this.directory.getPath() + namePostfix) : null;
+        clone.baseDirectory = this.baseDirectory != null ? new File(this.baseDirectory.getPath()) : null;
+        clone.name = this.name != null ? name + namePostfix : null;
+        clone.inMemory = this.inMemory;
+        clone.maxSizeInKByte = this.maxSizeInKByte;
+        clone.maxDataSizeInKByte = this.maxDataSizeInKByte;
+        clone.context = this.context;
+        clone.relinker = this.relinker;
+        clone.debugFlags = this.debugFlags;
+        clone.debugRelations = this.debugRelations;
+        clone.fileMode = this.fileMode;
+        clone.maxReaders = this.maxReaders;
+        clone.noReaderThreadLocals = this.noReaderThreadLocals;
+        clone.queryAttempts = this.queryAttempts;
+        clone.skipReadSchema = this.skipReadSchema;
+        clone.readOnly = this.readOnly;
+        clone.usePreviousCommit = this.usePreviousCommit;
+        clone.validateOnOpenModePages = this.validateOnOpenModePages;
+        clone.validateOnOpenPageLimit = this.validateOnOpenPageLimit;
+        clone.validateOnOpenModeKv = this.validateOnOpenModeKv;
+
+        clone.initialDbFileFactory = this.initialDbFileFactory;
+        clone.entityInfoList.addAll(this.entityInfoList); // Entity info is stateless & immutable; shallow clone is OK
+
+        return clone;
+    }
+}

objectbox-java/src/main/java/io/objectbox/InternalAccess.java

@@ -78,4 +78,9 @@ public static void enableCreationStackTracking() {
         Transaction.TRACK_CREATION_STACK = true;
         Cursor.TRACK_CREATION_STACK = true;
     }
+
+    @Internal
+    public static BoxStoreBuilder clone(BoxStoreBuilder original, String namePostfix) {
+        return original.createClone(namePostfix);
+    }
 }

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

@@ -17,13 +17,14 @@
 package io.objectbox.sync;
 
 import io.objectbox.BoxStore;
+import io.objectbox.BoxStoreBuilder;
 import io.objectbox.sync.server.SyncServer;
 import io.objectbox.sync.server.SyncServerBuilder;
 
 /**
  * <a href="https://objectbox.io/sync/">ObjectBox Sync</a> makes data available on other devices.
- * Start building a sync client using Sync.{@link #client(BoxStore, String, SyncCredentials)}
- * or an embedded server using Sync.{@link #server(BoxStore, String, SyncCredentials)}.
+ * <p>
+ * Use the static methods to build a Sync client or embedded server.
  */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public final class Sync {
@@ -43,8 +44,20 @@ public static boolean isServerAvailable() {
     }
 
     /**
-     * Start building a sync client. Requires the BoxStore that should be synced with the server,
-     * the URL and port of the server to connect to and credentials to authenticate against the server.
+     * Returns true if the included native (JNI) ObjectBox library supports Sync hybrids (server & client).
+     */
+    public static boolean isHybridAvailable() {
+        return isAvailable() && isServerAvailable();
+    }
+
+    /**
+     * Starts building a {@link SyncClient}. Once done, complete with {@link SyncBuilder#build() build()}.
+     *
+     * @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}.
+     * @param credentials {@link SyncCredentials} to authenticate with the server.
      */
     public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials credentials) {
         return new SyncBuilder(boxStore, url, credentials);
@@ -59,14 +72,38 @@ public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials
      * @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://0.0.0.0:9999}.
-     * @param authenticatorCredentials A list of enabled authentication methods available to Sync clients. Additional
-     * authenticator credentials can be supplied using the builder. For the embedded server, currently only
+     * @param authenticatorCredentials An authentication method available to Sync clients and peers. Additional
+     * authenticator credentials can be supplied using the returned builder. For the embedded server, currently only
      * {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none} are supported.
      */
     public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCredentials authenticatorCredentials) {
         return new SyncServerBuilder(boxStore, url, authenticatorCredentials);
     }
 
+    /**
+     * Starts building a {@link SyncHybrid}, a client/server hybrid typically used for embedded cluster setups.
+     * <p>
+     * Unlike {@link #client(BoxStore, String, SyncCredentials)} and {@link #server(BoxStore, String, SyncCredentials)},
+     * the client Store is not built before. Instead, a Store builder must be passed. The client and server Store will
+     * be built internally when calling this method.
+     * <p>
+     * To configure client and server use the methods on {@link SyncHybridBuilder}.
+     *
+     * @param storeBuilder The {@link BoxStoreBuilder} to use for building the client store.
+     * @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://0.0.0.0:9999}.
+     * @param authenticatorCredentials An authentication method available to Sync clients and peers. The client of the
+     * hybrid is pre-configured with them. Additional credentials can be supplied using the client and server builder of
+     * the returned builder. For the embedded server, currently only {@link SyncCredentials#sharedSecret} and
+     * {@link SyncCredentials#none} are supported.
+     * @return An instance of {@link SyncHybridBuilder}.
+     */
+    public static SyncHybridBuilder hybrid(BoxStoreBuilder storeBuilder, String url,
+                                           SyncCredentials authenticatorCredentials) {
+        return new SyncHybridBuilder(storeBuilder, url, authenticatorCredentials);
+    }
+
     private Sync() {
     }
 }

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

@@ -21,6 +21,7 @@
 import javax.annotation.Nullable;
 
 import io.objectbox.BoxStore;
+import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.sync.internal.Platform;
 import io.objectbox.sync.listener.SyncChangeListener;
 import io.objectbox.sync.listener.SyncCompletedListener;
@@ -34,11 +35,11 @@
  * {@link Sync#client(BoxStore, String, SyncCredentials)}.
  */
 @SuppressWarnings({"unused", "WeakerAccess"})
-public class SyncBuilder {
+public final class SyncBuilder {
 
     final Platform platform;
     final BoxStore boxStore;
-    final String url;
+    String url;
     final SyncCredentials credentials;
 
     @Nullable SyncLoginListener loginListener;
@@ -82,9 +83,9 @@ public enum RequestUpdatesMode {
         AUTO_NO_PUSHES
     }
 
-    public SyncBuilder(BoxStore boxStore, String url, SyncCredentials credentials) {
+    @Internal
+    public SyncBuilder(BoxStore boxStore, SyncCredentials credentials) {
         checkNotNull(boxStore, "BoxStore is required.");
-        checkNotNull(url, "Sync server URL is required.");
         checkNotNull(credentials, "Sync credentials are required.");
         if (!BoxStore.isSyncAvailable()) {
             throw new IllegalStateException(
@@ -93,10 +94,25 @@ public SyncBuilder(BoxStore boxStore, String url, SyncCredentials credentials) {
         }
         this.platform = Platform.findPlatform();
         this.boxStore = boxStore;
-        this.url = url;
         this.credentials = credentials;
     }
 
+    @Internal
+    public SyncBuilder(BoxStore boxStore, String url, SyncCredentials credentials) {
+        this(boxStore, credentials);
+        checkNotNull(url, "Sync server URL is required.");
+        this.url = url;
+    }
+
+    /**
+     * Allows internal code to set the Sync server URL after creating this builder.
+     */
+    @Internal
+    SyncBuilder serverUrl(String url) {
+        this.url = url;
+        return this;
+    }
+
     /**
      * Configures a custom set of directory or file paths to search for trusted certificates in.
      * The first path that exists will be used.
@@ -205,6 +221,7 @@ 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);
     }
 

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

@@ -38,7 +38,7 @@
  * this class may change without notice.
  */
 @Internal
-public class SyncClientImpl implements SyncClient {
+public final class SyncClientImpl implements SyncClient {
 
     @Nullable
     private BoxStore boxStore;

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

@@ -21,7 +21,7 @@
  * for example {@link #sharedSecret(String) SyncCredentials.sharedSecret("secret")}.
  */
 @SuppressWarnings("unused")
-public class SyncCredentials {
+public abstract class SyncCredentials {
 
     private final CredentialsType type;
 
@@ -86,4 +86,12 @@ public long getTypeId() {
         return type.id;
     }
 
+    /**
+     * Creates a copy of these credentials.
+     * <p>
+     * This can be useful to use the same credentials when creating multiple clients or a server in combination with a
+     * client as some credentials may get cleared when building a client or server.
+     */
+    abstract SyncCredentials createClone();
+
 }

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

@@ -62,8 +62,11 @@ public byte[] getTokenBytes() {
     /**
      * Clear after usage.
      * <p>
-     * Note that actual data is not removed from memory until the next garbage collector run.
-     * Anyhow, the credentials are still kept in memory by the native component.
+     * Note that when the token is passed as a String, that String is removed from memory at the earliest with the next
+     * garbage collector run.
+     * <p>
+     * Also note that while the token is removed from the Java heap, it is present on the native heap of the Sync
+     * component using it.
      */
     public void clear() {
         cleared = true;
@@ -74,4 +77,15 @@ public void clear() {
         this.token = null;
     }
 
+    @Override
+    SyncCredentialsToken createClone() {
+        if (cleared) {
+            throw new IllegalStateException("Cannot clone: credentials already have been cleared");
+        }
+        if (token == null) {
+            return new SyncCredentialsToken(getType());
+        } else {
+            return new SyncCredentialsToken(getType(), Arrays.copyOf(token, token.length));
+        }
+    }
 }

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

@@ -41,4 +41,9 @@ public String getUsername() {
     public String getPassword() {
         return password;
     }
+
+    @Override
+    SyncCredentials createClone() {
+        return new SyncCredentialsUserPassword(this.username, this.password);
+    }
 }

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

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2024 ObjectBox Ltd. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.objectbox.sync;
+
+import java.io.Closeable;
+
+import io.objectbox.BoxStore;
+import io.objectbox.sync.server.SyncServer;
+
+/**
+ * Combines the functionality of a Sync client and a Sync server.
+ * <p>
+ * It is typically used in local cluster setups, in which a "hybrid" functions as a client & cluster peer (server).
+ * <p>
+ * Call {@link #getStore()} to retrieve the store. To set sync listeners use the {@link SyncClient} that is available
+ * from {@link #getClient()}.
+ * <p>
+ * This class implements the {@link Closeable} interface, ensuring that resources are cleaned up properly.
+ */
+public final class SyncHybrid implements Closeable {
+    private BoxStore store;
+    private final SyncClient client;
+    private BoxStore storeServer;
+    private final SyncServer server;
+
+    SyncHybrid(BoxStore store, SyncClient client, BoxStore storeServer, SyncServer server) {
+        this.store = store;
+        this.client = client;
+        this.storeServer = storeServer;
+        this.server = server;
+    }
+
+    public BoxStore getStore() {
+        return store;
+    }
+
+    /**
+     * Returns the {@link SyncClient} of this hybrid, typically only to set Sync listeners.
+     * <p>
+     * Note: do not stop or close the client directly. Instead, use the {@link #stop()} and {@link #close()} methods of
+     * this hybrid.
+     */
+    public SyncClient getClient() {
+        return client;
+    }
+
+    /**
+     * Returns the {@link SyncServer} of this hybrid.
+     * <p>
+     * Typically, the server should not be touched. Yet, it is still exposed for advanced use cases.
+     * <p>
+     * Note: do not stop or close the server directly. Instead, use the {@link #stop()} and {@link #close()} methods of
+     * this hybrid.
+     */
+    public SyncServer getServer() {
+        return server;
+    }
+
+    /**
+     * Stops the client and server.
+     */
+    public void stop() {
+        client.stop();
+        server.stop();
+    }
+
+    /**
+     * Closes and cleans up all resources used by this Sync hybrid.
+     * <p>
+     * It can no longer be used afterward, build a new one instead.
+     * <p>
+     * Does nothing if this has already been closed.
+     */
+    @Override
+    public void close() {
+        // Clear reference to boxStore but do not close it (same behavior as SyncClient and SyncServer)
+        store = null;
+        client.close();
+        server.close();
+        if (storeServer != null) {
+            storeServer.close(); // The server store is "internal", so can safely close it
+            storeServer = null;
+        }
+    }
+
+    /**
+     * Users of this class should explicitly call {@link #close()} instead to avoid expensive finalization.
+     */
+    @SuppressWarnings("deprecation") // finalize()
+    @Override
+    protected void finalize() throws Throwable {
+        close();
+        super.finalize();
+    }
+}