Merge branch 'publish'

Author: greenrobot-team

.github/workflows/close-no-response.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: write
     steps:
       # https://github.com/marketplace/actions/close-stale-issues
-      - uses: actions/stale@28ca1036281a5e5922ead5184a1bbf96e5fc984e # v9.0.0
+      - uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
         with:
           days-before-stale: -1 # Add the stale label manually.
           days-before-close: 21

CHANGELOG.md

@@ -4,6 +4,19 @@ Notable changes to the ObjectBox Java library.
 
 For more insights into what changed in the ObjectBox C++ core, [check the ObjectBox C changelog](https://github.com/objectbox/objectbox-c/blob/main/CHANGELOG.md).
 
+## 5.2.0 - 2026-02-16
+
+- The [ObjectBox Gradle plugin](https://github.com/objectbox/objectbox-java-generator) requires JDK 11 and Android
+  Gradle Plugin 8.1 or newer.
+- Update database libraries for Android and JVM to database version `5.1.1-pre-2026-02-16`.
+
+### Sync
+
+- Add simplified `Sync.client(boxStore)` helper method. Move URL and credentials options to builder, add variants that 
+  accept multiple URLs and credentials. Deprecate the existing helper methods.
+- Add Sync client builder option to configure Sync behavior using 
+  [SyncFlags](objectbox-java/src/main/java/io/objectbox/sync/SyncFlags.java).
+
 ## 5.1.0 - 2026-01-26
 
 - Add [ObjectBoxThreadPoolExecutor](objectbox-java/src/main/java/io/objectbox/ObjectBoxThreadPoolExecutor.java), a

README.md

@@ -123,11 +123,16 @@ The database libraries available for the ObjectBox Java SDK support:
   - Windows (x64)
 - Android 5.0 (API level 21) or newer
 
-The APIs and tools of the ObjectBox Java SDK support:
+The ObjectBox Java SDK supports:
 
 - Java 8 or newer
 - Kotlin 1.7 or newer
-- Android Gradle Plugin 8.0 or newer
+
+The [ObjectBox Gradle plugin](https://github.com/objectbox/objectbox-java-generator) supports:
+
+- Gradle 7.0 or newer
+- Android Gradle Plugin 8.1 or newer
+- JDK 11 or newer
 
 ### Gradle setup
 
@@ -141,7 +146,13 @@ When using a [TOML version catalog](https://docs.gradle.org/current/userguide/ve
 
 [versions]
 # Define a variable for the version of the plugin
-objectbox = "5.1.0"
+objectbox = "5.2.0"
+
+# For an Android project
+agp = "<AGP_VERSION>"
+
+# If using Kotlin
+kotlin = "<KOTLIN_VERSION>"
 
 # For an Android project
 agp = "<AGP_VERSION>"
@@ -248,7 +259,7 @@ Your project can now use ObjectBox, continue by [defining entity classes](https:
 
 plugins {
     // Add the plugin
-    id("io.objectbox") version "5.1.0" apply false
+    id("io.objectbox") version "5.2.0" apply false
 }
 ```
 
@@ -281,7 +292,7 @@ pluginManagement {
 
 buildscript {
     // Define a variable for the plugin version
-    val objectboxVersion by extra("5.1.0")
+    val objectboxVersion by extra("5.2.0")
 
     repositories { 
         // Add the Maven Central repository       
@@ -304,7 +315,7 @@ buildscript {
 
 buildscript {
     // Define a variable for the plugin version
-    ext.objectboxVersion = "5.1.0"
+    ext.objectboxVersion = "5.2.0"
   
     repositories {        
         // Add the Maven Central repository

build.gradle.kts

@@ -20,7 +20,7 @@ plugins {
 buildscript {
     // Version of Maven artifacts
     // Should only be changed as part of the release process, see the release checklist in the objectbox repo
-    val versionNumber = "5.1.0"
+    val versionNumber = "5.2.0"
 
     // Release mode should only be enabled when manually triggering a CI pipeline,
     // see the release checklist in the objectbox repo.

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

@@ -82,10 +82,17 @@ public class BoxStore implements Closeable {
      * ReLinker uses this as a suffix for the extracted shared library file. If different, it will update it. Should be
      * unique to avoid conflicts.
      */
-    public static final String JNI_VERSION = "5.1.0-2026-01-19";
+    public static final String JNI_VERSION = "5.1.1-2026-02-16";
 
-    /** The ObjectBox database version this Java library is known to work with. */
-    private static final String VERSION = "5.1.0-2026-01-19";
+    /**
+     * The ObjectBox database version this Java library is known to work with.
+     * <p>
+     * This should be a version number followed by a date (MAJOR.MINOR.PATCH-YYYY-MM-DD).
+     * <p>
+     * This is used (currently only in tests) to make sure a database library has a compatible JNI API by checking the
+     * version number matches exactly and the date is the same or newer.
+     */
+    private static final String VERSION = "5.1.1-2026-02-16";
 
     private static final String OBJECTBOX_PACKAGE_NAME = "objectbox";
     private static BoxStore defaultStore;

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

@@ -16,6 +16,8 @@
 
 package io.objectbox.sync;
 
+import java.util.Arrays;
+
 import io.objectbox.BoxStore;
 import io.objectbox.BoxStoreBuilder;
 import io.objectbox.sync.server.SyncServer;
@@ -50,6 +52,23 @@ public static boolean isHybridAvailable() {
         return isAvailable() && isServerAvailable();
     }
 
+    /**
+     * Starts building a {@link SyncClient} for the given {@link BoxStore}.
+     * <p>
+     * This does not initiate any connection attempts yet: call {@link SyncBuilder#buildAndStart()} to do so. Before,
+     * you must configure the server URL via {@link SyncBuilder#url(String)} and add 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.
+     * @return a builder to configure the Sync client
+     */
+    public static SyncBuilder client(BoxStore boxStore) {
+        return new SyncBuilder(boxStore);
+    }
+
     /**
      * Starts building a {@link SyncClient}. Once done, complete with {@link SyncBuilder#build() build()}.
      *
@@ -58,18 +77,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)}, {@link SyncBuilder#url(String)} and
+     * {@link SyncBuilder#credentials(SyncCredentials)} instead.
      */
+    @Deprecated
     public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials credentials) {
-        return new SyncBuilder(boxStore, url, credentials);
+        return client(boxStore)
+                .url(url)
+                .credentials(credentials);
     }
 
     /**
      * 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)}, {@link SyncBuilder#url(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(url);
+        //noinspection ConstantValue
+        if (multipleCredentials != null) {
+            builder.credentials(Arrays.asList(multipleCredentials));
+        }
+        return builder;
     }
 
     /**

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

@@ -16,16 +16,15 @@
 
 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;
 
 import javax.annotation.Nullable;
 
 import io.objectbox.BoxStore;
-import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.exception.FeatureNotAvailableException;
 import io.objectbox.sync.internal.Platform;
 import io.objectbox.sync.listener.SyncChangeListener;
@@ -36,16 +35,15 @@
 import io.objectbox.sync.listener.SyncTimeListener;
 
 /**
- * A builder to create a {@link SyncClient}; the builder itself should be created via
- * {@link Sync#client(BoxStore, String, SyncCredentials)}.
+ * A builder to create a {@link SyncClient}; the builder itself should be created via {@link Sync#client(BoxStore)}.
  */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public final class SyncBuilder {
 
     final Platform platform;
     final BoxStore boxStore;
-    @Nullable private String url;
-    final List<SyncCredentials> credentials;
+    final List<String> urls = new ArrayList<>();
+    final List<SyncCredentials> credentials = new ArrayList<>();
 
     @Nullable SyncLoginListener loginListener;
     @Nullable SyncCompletedListener completedListener;
@@ -56,6 +54,7 @@ public final class SyncBuilder {
 
     @Nullable
     String[] trustedCertPaths;
+    int flags;
     boolean uncommittedAcks;
 
     RequestUpdatesMode requestUpdatesMode = RequestUpdatesMode.AUTO;
@@ -98,47 +97,80 @@ 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} method instead.
+     */
+    SyncBuilder(BoxStore boxStore) {
+        checkNotNull(boxStore, "boxStore");
         this.boxStore = boxStore;
-        this.url = url;
-        this.credentials = credentials;
         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));
+    /**
+     * Adds a Sync server URL the client should connect to.
+     * <p>
+     * This is typically a WebSockets URL starting with {@code ws://} or {@code wss://} (for encrypted connections), for
+     * example if the server is running on localhost {@code ws://127.0.0.1:9999}.
+     * <p>
+     * Can be called multiple times to add multiple URLs for high availability and load balancing (like when using an
+     * ObjectBox Sync Server Cluster). A random URL is selected for each connection attempt.
+     *
+     * @param url The URL of the Sync server on which the Sync protocol is exposed.
+     * @return this builder for chaining
+     * @see #urls(List)
+     */
+    public SyncBuilder url(String url) {
+        checkNotNull(url, "url");
+        this.urls.add(url);
+        return this;
     }
 
     /**
-     * When using this constructor, make sure to set the server URL before starting.
+     * Like {@link #url(String)}, but accepts a list of URLs.
+     *
+     * @param urls A list of URLs of Sync servers on which the Sync protocol is exposed.
+     * @return this builder for chaining
+     * @see #url(String)
      */
-    @Internal
-    public SyncBuilder(BoxStore boxStore, @Nullable SyncCredentials credentials) {
-        this(boxStore, null, credentials == null ? null : Collections.singletonList(credentials));
+    public SyncBuilder urls(List<String> urls) {
+        checkNotNull(urls, "urls");
+        for (String url : urls) {
+            url(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.
+     * <p>
+     * The accepted credentials types depend on your Sync server configuration.
+     *
+     * @param credentials credentials created using a {@link SyncCredentials} factory method, for example
+     * {@code SyncCredentials.jwtIdToken(idToken)}.
+     * @see #credentials(List)
      */
-    @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;
+    /**
+     * Like {@link #credentials(SyncCredentials)}, but accepts a list of credentials.
+     *
+     * @param credentials a list of credentials where each element is created using a {@link SyncCredentials} factory
+     * method, for example {@code SyncCredentials.jwtIdToken(idToken)}.
+     * @return this builder for chaining
+     */
+    public SyncBuilder credentials(List<SyncCredentials> credentials) {
+        checkNotNull(credentials, "credentials");
+        for (SyncCredentials credential : credentials) {
+            credentials(credential);
+        }
+        return this;
     }
 
     /**
@@ -151,8 +183,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;
     }
@@ -170,6 +202,16 @@ public SyncBuilder trustedCertificates(String[] paths) {
         return this;
     }
 
+    /**
+     * Sets bit flags to adjust Sync behavior, like additional logging.
+     *
+     * @param flags One or multiple {@link SyncFlags}, combined with bitwise or.
+     */
+    public SyncBuilder flags(int flags) {
+        this.flags = flags;
+        return this;
+    }
+
     /**
      * Configure automatic sync updates from the server.
      * If automatic sync updates are turned off, they will need to be requested using the sync client.
@@ -265,23 +307,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.");
         }
     }