Add SyncHybrid; a combo of SyncClient and SyncServer

Useful for embedded cluster setups that also want a local DB for
immediate persistence (like Sync clients).

Author: greenrobot

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,6 +17,8 @@
 package io.objectbox.sync;
 
 import io.objectbox.BoxStore;
+import io.objectbox.BoxStoreBuilder;
+import io.objectbox.sync.server.SyncHybridBuilder;
 import io.objectbox.sync.server.SyncServer;
 import io.objectbox.sync.server.SyncServerBuilder;
 
@@ -42,6 +44,13 @@ public static boolean isServerAvailable() {
         return BoxStore.isSyncServerAvailable();
     }
 
+    /**
+     * Returns true if the included native (JNI) ObjectBox library supports Sync hybrids (server & client).
+     */
+    public static boolean isHybridAvailable() {
+        return isAvailable() && 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.
@@ -67,6 +76,29 @@ public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCreden
         return new SyncServerBuilder(boxStore, url, authenticatorCredentials);
     }
 
+    /**
+     * Starts building a {@link SyncHybridBuilder}, a client/server hybrid typically used for embedded cluster setups.
+     * <p/>
+     * Unlike {@link #client(BoxStore, String, SyncCredentials)} and {@link #server(BoxStore, String, SyncCredentials)},
+     * you cannot pass in an already built store. Instead, you must pass in the store builder.
+     * The store will be created internally when calling this method.
+     * <p/>
+     * As this is a hybrid, you can configure client and server aspects using the {@link SyncHybridBuilder}.
+     *
+     * @param storeBuilder the BoxStoreBuilder to use for building the main 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 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
+     * {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none} are supported.
+     * @return an instance of 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;
@@ -38,7 +39,7 @@ public 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,24 @@ public SyncBuilder(BoxStore boxStore, String url, SyncCredentials credentials) {
         }
         this.platform = Platform.findPlatform();
         this.boxStore = boxStore;
-        this.url = url;
         this.credentials = credentials;
     }
 
+    public SyncBuilder(BoxStore boxStore, String url, SyncCredentials credentials) {
+        this(boxStore, credentials);
+        checkNotNull(url, "Sync server URL is required.");
+        this.url = url;
+    }
+
+    /**
+     * Internal URL setter for late assignment (used by {@link io.objectbox.sync.server.SyncHybridBuilder}).
+     */
+    @Internal
+    public SyncBuilder lateUrl(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.

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

@@ -60,6 +60,10 @@ public class SyncClientImpl implements SyncClient {
     private volatile boolean started;
 
     SyncClientImpl(SyncBuilder builder) {
+        if (builder.url == null) {
+            throw new IllegalArgumentException("Sync client destination URL was not specified");
+        }
+
         this.boxStore = builder.boxStore;
         this.serverUrl = builder.url;
         this.connectivityMonitor = builder.platform.getConnectivityMonitor();

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.
+     */
+    public abstract SyncCredentials createClone();
+
 }

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

@@ -74,4 +74,15 @@ public void clear() {
         this.token = null;
     }
 
+    @Override
+    public 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
+    public SyncCredentials createClone() {
+        return new SyncCredentialsUserPassword(this.username, this.password);
+    }
 }

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

@@ -0,0 +1,97 @@
+/*
+ * 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.server;
+
+import java.io.Closeable;
+
+import io.objectbox.BoxStore;
+import io.objectbox.sync.SyncClient;
+
+/**
+ * The SyncHybrid combines the functionality of a Sync Client and a Sync Server.
+ * 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 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;
+
+    public 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;
+    }
+
+    /**
+     * Typically only used to set sync listeners.
+     * <p/>
+     * Note: you should not directly call start(), stop(), close() on the {@link SyncClient} directly.
+     * Instead, call {@link #stop()} or {@link #close()} on this instance (it is already started during creation).
+     */
+    public SyncClient getClient() {
+        return client;
+    }
+
+    /**
+     * Typically, you won't need access to the SyncServer.
+     * It is still exposed for advanced use cases if you know what you are doing.
+     * <p/>
+     * Note: you should not directly call start(), stop(), close() on the {@link SyncServer} directly.
+     * Instead, call {@link #stop()} or {@link #close()} on this instance (it is already started during creation).
+     */
+    public SyncServer getServer() {
+        return server;
+    }
+
+    public void stop() {
+        client.stop();
+        server.stop();
+    }
+
+    @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 we can 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();
+    }
+}