Server options: create server using new FlatBuffer based options

Also add some API docs.

Author: greenrobot-team

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

@@ -569,7 +569,7 @@ public BoxStoreBuilder initialDbFile(Factory<InputStream> initialDbFileFactory)
 
     byte[] buildFlatStoreOptions(String canonicalPath) {
         FlatBufferBuilder fbb = new FlatBufferBuilder();
-        // FlatBuffer default values are set in generated code, e.g. may be different from here, so always store value.
+        // Always put values, even if they match the default values (defined in the generated classes)
         fbb.forceDefaults(true);
 
         // Add non-integer values first...

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2020 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-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.
@@ -16,15 +16,18 @@
 
 package io.objectbox.sync.server;
 
-import io.objectbox.annotation.apihint.Experimental;
-import io.objectbox.sync.SyncCredentials;
+import io.objectbox.annotation.apihint.Internal;
+import io.objectbox.sync.SyncCredentialsToken;
 
-@Experimental
+/**
+ * Internal class to keep configuration for a cluster peer.
+ */
+@Internal
 class PeerInfo {
     String url;
-    SyncCredentials credentials;
+    SyncCredentialsToken credentials;
 
-    PeerInfo(String url, SyncCredentials credentials) {
+    PeerInfo(String url, SyncCredentialsToken credentials) {
         this.url = url;
         this.credentials = credentials;
     }

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

@@ -23,22 +23,25 @@
 
 import io.objectbox.BoxStore;
 import io.objectbox.annotation.apihint.Experimental;
+import io.objectbox.flatbuffers.FlatBufferBuilder;
+import io.objectbox.sync.Credentials;
 import io.objectbox.sync.SyncCredentials;
+import io.objectbox.sync.SyncCredentialsToken;
 import io.objectbox.sync.listener.SyncChangeListener;
 
 /**
  * Creates a {@link SyncServer} and allows to set additional configuration.
  */
-@SuppressWarnings({"unused", "UnusedReturnValue", "WeakerAccess"})
+@SuppressWarnings({"unused", "UnusedReturnValue"})
 @Experimental
 public class SyncServerBuilder {
 
     final BoxStore boxStore;
     final String url;
-    final List<SyncCredentials> credentials = new ArrayList<>();
+    private final List<SyncCredentialsToken> credentials = new ArrayList<>();
     final List<PeerInfo> peers = new ArrayList<>();
 
-    @Nullable String certificatePath;
+    private @Nullable String certificatePath;
     SyncChangeListener changeListener;
 
     public SyncServerBuilder(BoxStore boxStore, String url, SyncCredentials authenticatorCredentials) {
@@ -55,7 +58,14 @@ public SyncServerBuilder(BoxStore boxStore, String url, SyncCredentials authenti
         authenticatorCredentials(authenticatorCredentials);
     }
 
+    /**
+     * Sets the path to a directory that contains a cert.pem and key.pem file to use to establish encrypted
+     * connections.
+     * <p>
+     * Use the "wss://" protocol for the server URL to turn on encrypted connections.
+     */
     public SyncServerBuilder certificatePath(String certificatePath) {
+        checkNotNull(certificatePath, "Certificate path must not be null");
         this.certificatePath = certificatePath;
         return this;
     }
@@ -68,7 +78,11 @@ public SyncServerBuilder certificatePath(String certificatePath) {
      */
     public SyncServerBuilder authenticatorCredentials(SyncCredentials authenticatorCredentials) {
         checkNotNull(authenticatorCredentials, "Authenticator credentials must not be null.");
-        credentials.add(authenticatorCredentials);
+        if (!(authenticatorCredentials instanceof SyncCredentialsToken)) {
+            throw new IllegalArgumentException("Sync credentials of type " + authenticatorCredentials.getType()
+                    + " are not supported");
+        }
+        credentials.add((SyncCredentialsToken) authenticatorCredentials);
         return this;
     }
 
@@ -94,7 +108,11 @@ public SyncServerBuilder peer(String url) {
      * Adds a server peer, to which this server should connect to as a client using the given credentials.
      */
     public SyncServerBuilder peer(String url, SyncCredentials credentials) {
-        peers.add(new PeerInfo(url, credentials));
+        if (!(credentials instanceof SyncCredentialsToken)) {
+            throw new IllegalArgumentException("Sync credentials of type " + credentials.getType()
+                    + " are not supported");
+        }
+        peers.add(new PeerInfo(url, (SyncCredentialsToken) credentials));
         return this;
     }
 
@@ -125,4 +143,100 @@ private void checkNotNull(Object object, String message) {
         }
     }
 
+    /**
+     * From this configuration, builds a {@link SyncServerOptions} FlatBuffer and returns it as bytes.
+     * <p>
+     * Clears configured credentials, they can not be used again after this returns.
+     */
+    byte[] buildSyncServerOptions() {
+        FlatBufferBuilder fbb = new FlatBufferBuilder();
+        // Always put values, even if they match the default values (defined in the generated classes)
+        fbb.forceDefaults(true);
+
+        // Serialize non-integer values first to get their offset
+        int urlOffset = fbb.createString(url);
+        int certificatePathOffset = 0;
+        if (certificatePath != null) {
+            certificatePathOffset = fbb.createString(certificatePath);
+        }
+        int authenticationMethodsOffset = buildAuthenticationMethods(fbb);
+        int clusterPeersVectorOffset = buildClusterPeers(fbb);
+
+        // TODO Support remaining options
+        // After collecting all offsets, create options
+        SyncServerOptions.startSyncServerOptions(fbb);
+        SyncServerOptions.addUrl(fbb, urlOffset);
+        SyncServerOptions.addAuthenticationMethods(fbb, authenticationMethodsOffset);
+//        SyncServerOptions.addSyncFlags();
+//        SyncServerOptions.addSyncServerFlags();
+        if (certificatePathOffset > 0) {
+            SyncServerOptions.addCertificatePath(fbb, certificatePathOffset);
+        }
+//        SyncServerOptions.addWorkerThreads();
+//        SyncServerOptions.addHistorySizeMaxKb();
+//        SyncServerOptions.addHistorySizeTargetKb();
+//        SyncServerOptions.addAdminUrl();
+//        SyncServerOptions.addAdminThreads();
+//        SyncServerOptions.addClusterId();
+        if (clusterPeersVectorOffset > 0) {
+            SyncServerOptions.addClusterPeers(fbb, clusterPeersVectorOffset);
+        }
+//        SyncServerOptions.addClusterFlags();
+        int offset = SyncServerOptions.endSyncServerOptions(fbb);
+        fbb.finish(offset);
+
+        return fbb.sizedByteArray();
+    }
+
+    private int buildAuthenticationMethods(FlatBufferBuilder fbb) {
+        int[] credentialsOffsets = new int[credentials.size()];
+        for (int i = 0; i < credentials.size(); i++) {
+            credentialsOffsets[i] = buildCredentials(fbb, credentials.get(i));
+        }
+        return SyncServerOptions.createAuthenticationMethodsVector(fbb, credentialsOffsets);
+    }
+
+    private int buildCredentials(FlatBufferBuilder fbb, SyncCredentialsToken tokenCredentials) {
+        int tokenBytesOffset = 0;
+        byte[] tokenBytes = tokenCredentials.getTokenBytes();
+        if (tokenBytes != null) {
+            tokenBytesOffset = Credentials.createBytesVector(fbb, tokenBytes);
+        }
+
+        Credentials.startCredentials(fbb);
+        // TODO Will this still be necessary?
+        // The core API used by nativeSetAuthenticator only supports the NONE and SHARED_SECRET types
+        // (however, protocol v3 versions do also add SHARED_SECRET_SIPPED if SHARED_SECRET is given).
+        final SyncCredentials.CredentialsType type = tokenCredentials.getType() == SyncCredentials.CredentialsType.SHARED_SECRET_SIPPED
+                ? SyncCredentials.CredentialsType.SHARED_SECRET
+                : tokenCredentials.getType();
+        Credentials.addType(fbb, type.id);
+        if (tokenBytesOffset > 0) {
+            Credentials.addBytes(fbb, tokenBytesOffset);
+        }
+        int credentialsOffset = Credentials.endCredentials(fbb);
+
+        tokenCredentials.clear(); // Clear immediately, not needed anymore.
+
+        return credentialsOffset;
+    }
+
+    private int buildClusterPeers(FlatBufferBuilder fbb) {
+        if (peers.isEmpty()) {
+            return 0;
+        }
+
+        int[] peersOffsets = new int[peers.size()];
+        for (int i = 0; i < peers.size(); i++) {
+            PeerInfo peer = peers.get(i);
+
+            int urlOffset = fbb.createString(peer.url);
+            int credentialsOffset = buildCredentials(fbb, peer.credentials);
+
+            peersOffsets[i] = ClusterPeerConfig.createClusterPeerConfig(fbb, urlOffset, credentialsOffset);
+        }
+
+        return SyncServerOptions.createClusterPeersVector(fbb, peersOffsets);
+    }
+
 }

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

@@ -19,9 +19,6 @@
 import javax.annotation.Nullable;
 
 import io.objectbox.annotation.apihint.Internal;
-import io.objectbox.sync.SyncCredentials;
-import io.objectbox.sync.SyncCredentials.CredentialsType;
-import io.objectbox.sync.SyncCredentialsToken;
 import io.objectbox.sync.listener.SyncChangeListener;
 
 /**
@@ -34,38 +31,23 @@ public class SyncServerImpl implements SyncServer {
     private final String url;
     private volatile long handle;
 
+    /**
+     * Protects listener instance from garbage collection.
+     */
+    @SuppressWarnings("unused")
     @Nullable
     private volatile SyncChangeListener syncChangeListener;
 
     SyncServerImpl(SyncServerBuilder builder) {
         this.url = builder.url;
 
         long storeHandle = builder.boxStore.getNativeStore();
-        long handle = nativeCreate(storeHandle, url, builder.certificatePath);
+        long handle = nativeCreateFromFlatOptions(storeHandle, builder.buildSyncServerOptions());
         if (handle == 0) {
             throw new RuntimeException("Failed to create sync server: handle is zero.");
         }
         this.handle = handle;
 
-        for (SyncCredentials credentials : builder.credentials) {
-            if (!(credentials instanceof SyncCredentialsToken)) {
-                throw new IllegalArgumentException("Sync credentials of type " + credentials.getType() + " are not supported");
-            }
-            SyncCredentialsToken credentialsInternal = (SyncCredentialsToken) credentials;
-            // The core API used by nativeSetAuthenticator only supports the NONE and SHARED_SECRET types
-            // (however, protocol v3 versions do also add SHARED_SECRET_SIPPED if SHARED_SECRET is given).
-            final CredentialsType type = credentialsInternal.getType() == CredentialsType.SHARED_SECRET_SIPPED
-                    ? CredentialsType.SHARED_SECRET
-                    : credentialsInternal.getType();
-            nativeSetAuthenticator(handle, type.id, credentialsInternal.getTokenBytes());
-            credentialsInternal.clear(); // Clear immediately, not needed anymore.
-        }
-
-        for (PeerInfo peer : builder.peers) {
-            SyncCredentialsToken credentialsInternal = (SyncCredentialsToken) peer.credentials;
-            nativeAddPeer(handle, peer.url, credentialsInternal.getTypeId(), credentialsInternal.getTokenBytes());
-        }
-
         if (builder.changeListener != null) {
             setSyncChangeListener(builder.changeListener);
         }
@@ -134,7 +116,12 @@ protected void finalize() throws Throwable {
         super.finalize();
     }
 
-    private static native long nativeCreate(long storeHandle, String uri, @Nullable String certificatePath);
+    /**
+     * Creates a native Sync server instance with FlatBuffer {@link SyncServerOptions} {@code flatOptionsByteArray}.
+     *
+     * @return The handle of the native server instance.
+     */
+    private static native long nativeCreateFromFlatOptions(long storeHandle, byte[] flatOptionsByteArray);
 
     private native void nativeDelete(long handle);