Merge branch '139-add-externaltype-annotation-for-properties-and-standalone-tomany' into 'main'

Add @ExternalType and @ExternalName annotations #139

See merge request objectbox/objectbox-dart!102

Author: greenrobot-team

dev-doc/updating-c-library.md

@@ -19,35 +19,35 @@ for the binding update script (see below) and
 for Flutter (`flutter_libs` and `sync_flutter_libs` plugins) on Linux and Windows:
 
 ```bash
-./tool/set-c-version.sh 4.1.0
+./tool/set-c-version.sh 4.2.0
 ```
 
 ```text
-* Flutter for Linux/Windows, Dart Native: update to [objectbox-c 4.1.0](https://github.com/objectbox/objectbox-c/releases/tag/v4.1.0).
+* Update ObjectBox database for Flutter Linux/Windows, Dart Native apps to [4.2.0](https://github.com/objectbox/objectbox-c/releases/tag/v4.2.0).
 ```
 
 ```text
-Update C library [4.0.2 -> 4.1.0]
+Update C library [4.1.0 -> 4.2.0]
 ```
 
 ### Android
 
 For the Flutter plugins on Android ([view releases](https://github.com/objectbox/objectbox-java/releases)):
 
 ```bash
-./tool/set-android-version.sh 4.1.0
+./tool/set-android-version.sh 4.2.0
 ```
 
 ```text
-* Flutter for Android: update to [objectbox-android 4.1.0](https://github.com/objectbox/objectbox-java/releases/tag/V4.1.0).
-  If your project is [using Admin](https://docs.objectbox.io/data-browser#admin-for-android), make sure to
-  update to `io.objectbox:objectbox-android-objectbrowser:4.1.0` in `android/app/build.gradle`.
+* Update ObjectBox database for Flutter Android apps to 4.2.0.
+  If your project is [using Admin](https://docs.objectbox.io/data-browser#admin-for-android), make 
+  sure to update to `io.objectbox:objectbox-android-objectbrowser:4.2.0` in `android/app/build.gradle`.
 ```
 
 ```text
-Update objectbox-android [4.0.3 -> 4.1.0]
+Update objectbox-android [4.1.0 -> 4.2.0]
 
-Bundled with C API 4.1.0 and ObjectBox 4.1.0-2025-01-28
+Bundled with C API 4.2.0 and ObjectBox 4.2.0-2025-03-04
 ```
 
 Note: the embedded C API and ObjectBox version can be looked up
@@ -58,18 +58,18 @@ from the relevant objectbox repository release tag (like `java-4.1.0`).
 For the Flutter plugins on iOS/macOS ([view releases](https://github.com/objectbox/objectbox-swift/releases))
 
 ```bash
-./tool/set-swift-version.sh 4.1.0
+./tool/set-swift-version.sh 4.2.0
 ```
 
 ```text
-* Flutter for iOS/macOS: update to [objectbox-swift 4.1.0](https://github.com/objectbox/objectbox-swift/releases/tag/v4.1.0).
+* Update ObjectBox database for Flutter iOS/macOS apps to 4.2.0.
   For existing projects, run `pod repo update` and `pod update ObjectBox` in the `ios` or `macos` directories.
 ```
 
 ```text
-Update ObjectBox Swift [4.0.0 -> 4.0.1]
+Update ObjectBox Swift [4.1.0 -> 4.2.0]
 
-Bundled with C API 4.1.0 and ObjectBox 4.1.0-2025-01-30
+Bundled with C API 4.2.0 and ObjectBox 4.2.0-2025-03-04
 ```
 
 Note: the embedded C API and ObjectBox version can be looked up 
@@ -96,5 +96,5 @@ Then manually:
 - Commit as
 
 ```text
-Update C-API [4.0.2 -> 4.1.0]
+Update C-API [4.1.0 -> 4.2.0]
 ```

flutter_libs/android/build.gradle

@@ -52,6 +52,6 @@ android {
         // ObjectBox Android library that includes an ObjectBox C library version compatible with
         // the C API binding of the ObjectBox Dart package.
         // https://central.sonatype.com/search?q=g:io.objectbox%20objectbox-android
-        implementation "io.objectbox:objectbox-android:4.1.0"
+        implementation "io.objectbox:objectbox-android:4.2.0"
     }
 }

flutter_libs/ios/objectbox_flutter_libs.podspec

@@ -18,7 +18,7 @@ Pod::Spec.new do |s|
   s.source_files     = 'Classes/**/*'
 
   s.dependency 'Flutter'
-  s.dependency 'ObjectBox', '4.1.0'
+  s.dependency 'ObjectBox', '4.2.0'
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }

flutter_libs/linux/CMakeLists.txt

@@ -44,7 +44,7 @@ target_link_libraries(${PLUGIN_NAME} PRIVATE PkgConfig::GTK)
 # ----------------------------------------------------------------------
 # Download and add objectbox-c prebuilt library.
 
-set(OBJECTBOX_VERSION 4.1.0)
+set(OBJECTBOX_VERSION 4.2.0)
 
 set(OBJECTBOX_ARCH ${CMAKE_SYSTEM_PROCESSOR})
 if (${OBJECTBOX_ARCH} MATCHES "x86_64")

flutter_libs/macos/objectbox_flutter_libs.podspec

@@ -18,7 +18,7 @@ Pod::Spec.new do |s|
   s.source_files     = 'Classes/**/*'
 
   s.dependency 'FlutterMacOS'
-  s.dependency 'ObjectBox', '4.1.0'
+  s.dependency 'ObjectBox', '4.2.0'
 
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
   s.swift_version = '5.3'

flutter_libs/windows/CMakeLists.txt

@@ -50,7 +50,7 @@ set(objectbox_flutter_libs_bundled_libraries
 # ----------------------------------------------------------------------
 # Download and add objectbox-c prebuilt library.
 
-set(OBJECTBOX_VERSION 4.1.0)
+set(OBJECTBOX_VERSION 4.2.0)
 
 set(OBJECTBOX_ARCH ${CMAKE_SYSTEM_PROCESSOR})
 if (${OBJECTBOX_ARCH} MATCHES "AMD64")

generator/lib/src/code_builder.dart

@@ -1,21 +1,21 @@
 import 'dart:async';
-import 'dart:io';
 import 'dart:convert';
+import 'dart:io';
 
 import 'package:build/build.dart';
 import 'package:collection/collection.dart';
+import 'package:dart_style/dart_style.dart';
 import 'package:glob/glob.dart';
+import 'package:objectbox/internal.dart';
 import 'package:objectbox_generator/src/analysis/analysis.dart';
 import 'package:objectbox_generator/src/builder_dirs.dart';
 import 'package:path/path.dart' as path;
-import 'package:objectbox/internal.dart';
-import 'package:dart_style/dart_style.dart';
-import 'package:source_gen/source_gen.dart';
 import 'package:pubspec_parse/pubspec_parse.dart';
+import 'package:source_gen/source_gen.dart';
 
+import 'code_chunks.dart';
 import 'config.dart';
 import 'entity_resolver.dart';
-import 'code_chunks.dart';
 
 /// CodeBuilder collects all '.objectbox.info' files created by EntityResolver and generates objectbox-model.json and
 /// objectbox_model.dart
@@ -213,6 +213,8 @@ class CodeBuilder extends Builder {
     propInModel.dartFieldType = prop.dartFieldType;
     propInModel.relationTarget = prop.relationTarget;
     propInModel.hnswParams = prop.hnswParams;
+    propInModel.externalType = prop.externalType;
+    propInModel.externalName = prop.externalName;
 
     if (!prop.hasIndexFlag()) {
       propInModel.removeIndex();
@@ -242,6 +244,8 @@ class CodeBuilder extends Builder {
 
     relInModel.name = rel.name;
     relInModel.targetName = rel.targetName;
+    relInModel.externalType = rel.externalType;
+    relInModel.externalName = rel.externalName;
   }
 
   IdUid mergeEntity(ModelInfo modelInfo, ModelEntity entity) {
@@ -267,6 +271,7 @@ class CodeBuilder extends Builder {
 
     entityInModel.name = entity.name;
     entityInModel.flags = entity.flags;
+    entityInModel.externalName = entity.externalName;
     entityInModel.constructorParams = entity.constructorParams;
 
     // here, the entity was found already and entityInModel and entity might differ, i.e. conflicts need to be resolved, so merge all properties first

generator/lib/src/code_chunks.dart

@@ -122,12 +122,16 @@ class CodeChunks {
   }
 
   static String createModelEntity(ModelEntity entity) {
+    var additionalArgs = '';
+    if (entity.externalName != null) {
+      additionalArgs += " externalName: '${entity.externalName}',";
+    }
     return '''
     $obxInt.ModelEntity(
       id: ${createIdUid(entity.id)},
       name: '${entity.name}',
       lastPropertyId: ${createIdUid(entity.lastPropertyId)},
-      flags: ${entity.flags},
+      flags: ${entity.flags},$additionalArgs
       properties: <$obxInt.ModelProperty>[
         ${entity.properties.map(createModelProperty).join(',')}
       ],
@@ -154,6 +158,12 @@ class CodeChunks {
       additionalArgs +=
           ", hnswParams: ${property.hnswParams!.toCodeString(obxInt)}";
     }
+    if (property.externalType != null) {
+      additionalArgs += ", externalType: ${property.externalType!}";
+    }
+    if (property.externalName != null) {
+      additionalArgs += ", externalName: '${property.externalName!}'";
+    }
     return '''
     $obxInt.ModelProperty(
       id: ${createIdUid(property.id)},
@@ -166,11 +176,19 @@ class CodeChunks {
   }
 
   static String createModelRelation(ModelRelation relation) {
+    var additionalArgs = '';
+    if (relation.externalType != null) {
+      additionalArgs += ", externalType: ${relation.externalType!}";
+    }
+    if (relation.externalName != null) {
+      additionalArgs += ", externalName: '${relation.externalName!}'";
+    }
     return '''
     $obxInt.ModelRelation(
       id: ${createIdUid(relation.id)},
       name: '${relation.name}',
       targetId: ${createIdUid(relation.targetId)}
+      $additionalArgs
     )
     ''';
   }

generator/lib/src/entity_resolver.dart

@@ -28,6 +28,8 @@ class EntityResolver extends Builder {
   final _indexChecker = const TypeChecker.fromRuntime(Index);
   final _backlinkChecker = const TypeChecker.fromRuntime(Backlink);
   final _hnswChecker = const TypeChecker.fromRuntime(HnswIndex);
+  final _externalTypeChecker = const TypeChecker.fromRuntime(ExternalType);
+  final _externalNameChecker = const TypeChecker.fromRuntime(ExternalName);
 
   @override
   FutureOr<void> build(BuildStep buildStep) async {
@@ -68,6 +70,11 @@ class EntityResolver extends Builder {
         null,
         uidRequest: !entityUid.isNull && entityUid.intValue == 0);
 
+    // @ExternalName
+    _externalNameChecker.runIfMatches(classElement, (annotation) {
+      entity.externalName = _readExternalNameParams(annotation);
+    });
+
     // Sync: check if enabled and options
     _syncChecker.runIfMatches(classElement, (annotation) {
       entity.flags |= OBXEntityFlags.SYNC_ENABLED;
@@ -171,6 +178,7 @@ class EntityResolver extends Builder {
       final backlinkAnnotations =
           _backlinkChecker.annotationsOfExact(annotated);
       if (backlinkAnnotations.isNotEmpty) {
+        // Handles ToMany based on other ToOne or ToMany relation (backlink)
         if (!isToManyRel) {
           log.severe(
               "  Skipping property '${f.name}': @Backlink() may only be used with ToMany.");
@@ -183,14 +191,33 @@ class EntityResolver extends Builder {
         entity.backlinks.add(backlink);
         log.info('  $backlink');
       } else if (isToManyRel) {
+        // Handles standalone (non backlink) ToMany relation
+
+        // @ExternalType
+        int? externalType;
+        _externalTypeChecker.runIfMatches(annotated, (annotation) {
+          final externalTypeId = _readExternalTypeParams(annotation);
+          externalType = externalTypeId;
+        });
+
+        // @ExternalName
+        String? externalName;
+        _externalNameChecker.runIfMatches(annotated, (annotation) {
+          externalName = _readExternalNameParams(annotation);
+        });
+
         // create relation
         final rel = ModelRelation.create(IdUid(0, propUid ?? 0), f.name,
             targetName: relTargetName,
-            uidRequest: propUid != null && propUid == 0);
+            uidRequest: propUid != null && propUid == 0,
+            externalName: externalName,
+            externalType: externalType);
+
         entity.relations.add(rel);
 
         log.info('  $rel');
       } else {
+        // Handles regular properties
         // create property (do not use readEntity.createProperty in order to avoid generating new ids)
         final prop = ModelProperty.create(
             IdUid(0, propUid ?? 0), f.name, fieldType,
@@ -226,6 +253,17 @@ class EntityResolver extends Builder {
           _readHnswIndexParams(annotation, prop);
         });
 
+        // @ExternalType
+        _externalTypeChecker.runIfMatches(annotated, (annotation) {
+          final externalTypeId = _readExternalTypeParams(annotation);
+          prop.externalType = externalTypeId;
+        });
+
+        // @ExternalName
+        _externalNameChecker.runIfMatches(annotated, (annotation) {
+          prop.externalName = _readExternalNameParams(annotation);
+        });
+
         // for code generation
         prop.dartFieldType =
             f.type.element!.name! + (isNullable(f.type) ? '?' : '');
@@ -555,6 +593,27 @@ class EntityResolver extends Builder {
             annotation.getField('vectorCacheHintSizeKB')!.toIntValue());
     property.hnswParams = ModelHnswParams.fromAnnotation(hnswRestored);
   }
+
+  int _readExternalTypeParams(DartObject annotation) {
+    final typeIndex =
+        _enumValueIndex(annotation.getField('type')!, "ExternalType.type");
+    final type =
+        typeIndex != null ? ExternalPropertyType.values[typeIndex] : null;
+    if (type == null) {
+      throw InvalidGenerationSourceError(
+          "'type' attribute not specified in @ExternalType annotation");
+    }
+    return externalTypeToOBXExternalType(type);
+  }
+
+  String _readExternalNameParams(DartObject annotation) {
+    final name = annotation.getField('name')!.toStringValue();
+    if (name == null) {
+      throw InvalidGenerationSourceError(
+          "'name' attribute not specified in @ExternalName annotation");
+    }
+    return name;
+  }
 }
 
 extension _TypeCheckerExtensions on TypeChecker {