Support Unique conflict resolution strategy replace.

Author: greenrobot-team

generator/lib/src/entity_resolver.dart

@@ -257,6 +257,11 @@ class EntityResolver extends Builder {
       }
     }
 
+    // Verify there is at most 1 unique property with REPLACE strategy.
+    ensureSingleUniqueReplace(entity);
+    // If sync enabled, verify all unique properties use REPLACE strategy.
+    ifSyncEnsureAllUniqueAreReplace(entity);
+
     entity.properties.forEach((p) => log.info('  $p'));
 
     return entity;
@@ -301,9 +306,9 @@ class EntityResolver extends Builder {
       FieldElement f, int? fieldType, Element elementBare, ModelProperty prop) {
     IndexType? indexType;
 
-    final hasIndexAnnotation = _indexChecker.hasAnnotationOfExact(f);
-    final hasUniqueAnnotation = _uniqueChecker.hasAnnotationOfExact(f);
-    if (!hasIndexAnnotation && !hasUniqueAnnotation) return null;
+    final indexAnnotation = _indexChecker.firstAnnotationOfExact(f);
+    final uniqueAnnotation = _uniqueChecker.firstAnnotationOfExact(f);
+    if (indexAnnotation == null && uniqueAnnotation == null) return null;
 
     // Throw if property type does not support any index.
     if (fieldType == OBXPropertyType.Float ||
@@ -319,8 +324,6 @@ class EntityResolver extends Builder {
     }
 
     // If available use index type from annotation.
-    final indexAnnotation =
-        hasIndexAnnotation ? _indexChecker.firstAnnotationOfExact(f) : null;
     if (indexAnnotation != null && !indexAnnotation.isNull) {
       final enumValItem = enumValueItem(indexAnnotation.getField('type')!);
       if (enumValItem != null) indexType = IndexType.values[enumValItem];
@@ -343,8 +346,15 @@ class EntityResolver extends Builder {
           "entity ${elementBare.name}: a hash index is not supported for type '${f.type}' of field '${f.name}'");
     }
 
-    if (hasUniqueAnnotation) {
+    if (uniqueAnnotation != null && !uniqueAnnotation.isNull) {
       prop.flags |= OBXPropertyFlags.UNIQUE;
+      // Determine unique conflict resolution.
+      final onConflictVal =
+          enumValueItem(uniqueAnnotation.getField('onConflict')!);
+      if (onConflictVal != null &&
+          ConflictStrategy.values[onConflictVal] == ConflictStrategy.replace) {
+        prop.flags |= OBXPropertyFlags.UNIQUE_ON_CONFLICT_REPLACE;
+      }
     }
 
     switch (indexType) {
@@ -363,6 +373,27 @@ class EntityResolver extends Builder {
     }
   }
 
+  void ensureSingleUniqueReplace(ModelEntity entity) {
+    final uniqueReplaceProps = entity.properties
+        .where((p) => p.hasFlag(OBXPropertyFlags.UNIQUE_ON_CONFLICT_REPLACE));
+    if (uniqueReplaceProps.length > 1) {
+      throw InvalidGenerationSourceError(
+          "ConflictStrategy.replace can only be used on a single property, but found multiple in '${entity.name}':\n  ${uniqueReplaceProps.join('\n  ')}");
+    }
+  }
+
+  void ifSyncEnsureAllUniqueAreReplace(ModelEntity entity) {
+    if (!entity.hasFlag(OBXEntityFlags.SYNC_ENABLED)) return;
+    final uniqueButNotReplaceProps = entity.properties.where((p) {
+      return p.hasFlag(OBXPropertyFlags.UNIQUE) &&
+          !p.hasFlag(OBXPropertyFlags.UNIQUE_ON_CONFLICT_REPLACE);
+    });
+    if (uniqueButNotReplaceProps.isNotEmpty) {
+      throw InvalidGenerationSourceError(
+          "Synced entities must use @Unique(onConflict: ConflictStrategy.replace) on all unique properties, but found others in '${entity.name}':\n  ${uniqueButNotReplaceProps.join('\n  ')}");
+    }
+  }
+
   int? enumValueItem(DartObject typeField) {
     if (!typeField.isNull) {
       final enumValues = (typeField.type as InterfaceType)

objectbox/lib/src/annotations.dart

@@ -1,3 +1,5 @@
+import 'package:objectbox/objectbox.dart';
+
 /// Entity annotation is used on a class to let ObjectBox know it should store
 /// it - making the class a "persistable Entity".
 ///
@@ -190,17 +192,31 @@ enum IndexType {
   hash64,
 }
 
-/// Unique annotation forces that the value of a property is unique among all
-/// objects stored for the given entity.
+/// Enforces that the value of a property is unique among all objects in a box
+/// before an object can be put.
 ///
-/// Trying to put an Object with offending values will result in an exception.
+/// Trying to put an object with offending values will result in a
+/// [UniqueViolationException] (see [ConflictStrategy.fail]).
+/// Set [onConflict] to change this strategy.
 ///
-/// Unique properties are based on an [Index], so the same restrictions apply.
+/// Note: Unique properties are based on an [Index], so the same restrictions apply.
 /// It is supported to explicitly add the [Index] annotation to configure the
-/// index type.
+/// index.
 class Unique {
+  /// The strategy to use when a conflict is detected when an object is put.
+  final ConflictStrategy onConflict;
+
   /// Create a Unique annotation.
-  const Unique();
+  const Unique({this.onConflict = ConflictStrategy.fail});
+}
+
+/// Used with [Unique] to specify the conflict resolution strategy.
+enum ConflictStrategy {
+  /// Throws [UniqueViolationException] if any property violates a [Unique] constraint.
+  fail,
+
+  /// Any conflicting objects are deleted before the object is inserted.
+  replace,
 }
 
 /// Backlink annotation specifies a link in a reverse direction of another

objectbox/lib/src/modelinfo/enums.dart

@@ -122,6 +122,9 @@ abstract class OBXPropertyFlags {
   /// ///
   /// /// For Time Series IDs, a companion property of type Date or DateNano represents the exact timestamp.
   static const int ID_COMPANION = 16384;
+
+  /// Unique on-conflict strategy: the object being put replaces any existing conflicting object (deletes it).
+  static const int UNIQUE_ON_CONFLICT_REPLACE = 32768;
 }
 
 abstract class OBXPropertyType {