Merge branch '297-sync-clock-and-precedence-annotations' into dev

Author: greenrobot-team

CHANGELOG.md

@@ -6,6 +6,16 @@ For more insights into what changed in the database libraries, [check the Object
 
 ## Next release
 
+- Update Android and JVM libraries to database version `5.3.0-2026-03-23`
+- Admin: Status tab "Count and Sizes" and "System and Info" improved
+
+### Sync
+
+- Conflict resolution via the new annotations `@SyncClock` and `@SyncPrecedence` (allows last win with custom conflict
+  resolution)
+- Fix bad Sync client state after multiple full sync messages were interrupted
+- Fix adding indexes to Sync types
+
 ## 5.3.0 - 2026-03-10
 
 - Gradle plugin: to apply the plugin, it is no longer necessary to add a manual mapping of the plugin ID in your

objectbox-java-api/src/main/java/io/objectbox/annotation/SyncClock.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright © 2026 ObjectBox Ltd. <https://objectbox.io>
+ *
+ * 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.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a {@code long} (64-bit integer) field of a {@link Sync}-enabled {@link Entity} class as the sync clock, a
+ * "hybrid logical clock" to resolve Sync conflicts.
+ * <p>
+ * These clock values allow "last write wins" conflict resolution.
+ * <p>
+ * There can be only one sync clock per sync entity type; which is also recommended for basic conflict resolution.
+ * <p>
+ * For new objects, initialize the property value to {@code 0} to reserve "a slot" in the object data. ObjectBox Sync
+ * will update this property automatically on put operations.
+ * <p>
+ * As a hybrid clock, it combines a wall clock with a logical counter to compensate for some clock skew effects.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface SyncClock {
+}

objectbox-java-api/src/main/java/io/objectbox/annotation/SyncPrecedence.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright © 2026 ObjectBox Ltd. <https://objectbox.io>
+ *
+ * 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.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a {@code long} (64-bit integer) field of a {@link Sync}-enabled {@link Entity} class as the "sync precedence"
+ * to customize Sync conflict resolution.
+ * <p>
+ * Developer-assigned precedence values are then used to resolve conflicts via "higher precedence wins". Defining and
+ * assigning precedence values are completely in the hands of the developer (the ObjectBox user).
+ * <p>
+ * There can be only one sync precedence per sync entity type.
+ * <p>
+ * Typically, it is combined with a {@link SyncClock}, with the latter being the tie-breaker for equal precedence
+ * values.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface SyncPrecedence {
+}

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

@@ -92,7 +92,7 @@ public class BoxStore implements Closeable {
      * 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.2.0-2026-03-10";
+    private static final String VERSION = "5.3.0-2026-03-23";
 
     private static final String OBJECTBOX_PACKAGE_NAME = "objectbox";
     private static BoxStore defaultStore;

objectbox-java/src/main/java/io/objectbox/model/PropertyFlags.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 ObjectBox Ltd.
+ * Copyright 2026 ObjectBox Ltd. <https://objectbox.io>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -103,5 +103,29 @@ private PropertyFlags() { }
    * However, the deletion process can be triggered by an API call.
    */
   public static final int EXPIRATION_TIME = 65536;
+  /**
+   * Marks a Long (64-bit integer) property as a the sync clock, a "hybrid logical clock" to resolve Sync conflicts.
+   * These clock values allow "last write wins" conflict resolution.
+   * There can be only one sync clock per sync entity type; which is also recommended for basic conflict resolution.
+   * For new objects, initialize a property value to 0 to reserve "a slot" in the object data.
+   * ObjectBox Sync will update this property automatically on put operations.
+   * As a hybrid clock, it combines a wall clock with a logical counter to compensate for some clock skew effects.
+   */
+  public static final int SYNC_CLOCK = 131072;
+  /**
+   * Marks a Long (64-bit integer) property as a the "sync precedence" to customize Sync conflict resolution.
+   * Developer-assigned precedence values are then used to resolve conflicts via "higher precedence wins".
+   * Defining and assigning precedence values are completely in the hands of the developer (the ObjectBox user).
+   * There can be only one sync precedence per sync entity type.
+   * Typically, it is combined with a sync clock, with the latter being the tie-breaker for equal precedence values.
+   * This can be used to model some business logic use cases, for example:
+   *   - Setting an object a special state, e.g. a final/closed state, which may not be overwritten by a lesser state
+   *   - Multiple workflow states that occur linearly (i.e. using an increasing precedence value)
+   *   - Role based, e.g. only admins set or increment the precedence..
+   *   - “Checkpoint timestamps:” e.g. when some changes are “checked” as in approved/applied,
+   *     the precedence is updated to the current timestamp.
+   *     “Non-checked” or previously checkpointed changes are disregarded.
+   */
+  public static final int SYNC_PRECEDENCE = 262144;
 }