external types: create two separate annotations, @ExternalType and @ExternalName

Author: Shubham

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
@@ -244,6 +244,8 @@ class CodeBuilder extends Builder {
 
     relInModel.name = rel.name;
     relInModel.targetName = rel.targetName;
+    relInModel.externalPropertyType = rel.externalPropertyType;
+    relInModel.externalPropertyName = rel.externalPropertyName;
   }
 
   IdUid mergeEntity(ModelInfo modelInfo, ModelEntity entity) {

generator/lib/src/code_chunks.dart

@@ -174,11 +174,19 @@ class CodeChunks {
   }
 
   static String createModelRelation(ModelRelation relation) {
+    var additionalArgs = '';
+    if (relation.externalPropertyType != null) {
+      additionalArgs += ", externalType: ${relation.externalPropertyType!}";
+    }
+    if (relation.externalPropertyName != null) {
+      additionalArgs += ", externalName: '${relation.externalPropertyName!}'";
+    }
     return '''
     $obxInt.ModelRelation(
       id: ${createIdUid(relation.id)},
       name: '${relation.name}',
       targetId: ${createIdUid(relation.targetId)}
+      $additionalArgs
     )
     ''';
   }

generator/lib/src/entity_resolver.dart

@@ -28,7 +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(ExternalProperty);
+  final _externalTypeChecker = const TypeChecker.fromRuntime(ExternalType);
+  final _externalNameChecker = const TypeChecker.fromRuntime(ExternalName);
 
   @override
   FutureOr<void> build(BuildStep buildStep) async {
@@ -172,6 +173,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.");
@@ -184,14 +186,37 @@ class EntityResolver extends Builder {
         entity.backlinks.add(backlink);
         log.info('  $backlink');
       } else if (isToManyRel) {
+        // Handles standalone (non backlink) ToMany relation
+
+        // @ExternalType
+        int? externalPropertyType;
+        _externalTypeChecker.runIfMatches(annotated, (annotation) {
+          final externalTypeId = _readExternalTypeParams(annotation);
+          externalPropertyType = externalTypeId;
+        });
+
+        // @ExternalName
+        String? externalPropertyName;
+        _externalNameChecker.runIfMatches(annotated, (annotation) {
+          if (externalPropertyType == null) {
+            throw InvalidGenerationSourceError(
+                "@ExternalName annotation requires @ExternalType annotation to be present");
+          }
+          externalPropertyName = _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,
+            externalPropertyName: externalPropertyName,
+            externalPropertyType: externalPropertyType);
+
         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,
@@ -227,8 +252,20 @@ class EntityResolver extends Builder {
           _readHnswIndexParams(annotation, prop);
         });
 
+        // @ExternalType
         _externalTypeChecker.runIfMatches(annotated, (annotation) {
-          _readExternalTypeParams(annotation, prop);
+          final externalTypeId = _readExternalTypeParams(annotation);
+          prop.externalPropertyType = externalTypeId;
+        });
+
+        // @ExternalName
+        _externalNameChecker.runIfMatches(annotated, (annotation) {
+          if (prop.externalPropertyType == null) {
+            throw InvalidGenerationSourceError(
+                "@ExternalName annotation requires @ExternalType annotation to be present");
+          }
+          final externalName = _readExternalNameParams(annotation);
+          prop.externalPropertyName = externalName;
         });
 
         // for code generation
@@ -561,17 +598,25 @@ class EntityResolver extends Builder {
     property.hnswParams = ModelHnswParams.fromAnnotation(hnswRestored);
   }
 
-  void _readExternalTypeParams(DartObject annotation, ModelProperty property) {
+  int _readExternalTypeParams(DartObject annotation) {
     final typeIndex =
-        _enumValueIndex(annotation.getField('type')!, "ExternalProperty.type");
-    final type = typeIndex != null ? ExternalType.values[typeIndex] : null;
+        _enumValueIndex(annotation.getField('type')!, "ExternalType.type");
+    final type =
+        typeIndex != null ? ExternalPropertyType.values[typeIndex] : null;
     if (type == null) {
       throw InvalidGenerationSourceError(
-          "'type' attribute not specified in @ExternalProperty annotation");
+          "'type' attribute not specified in @ExternalType annotation");
     }
+    return externalTypeToOBXExternalType(type);
+  }
+
+  String _readExternalNameParams(DartObject annotation) {
     final name = annotation.getField('name')!.toStringValue();
-    property.externalPropertyType = externalTypeToOBXExternalType(type);
-    property.externalPropertyName = name;
+    if (name == null) {
+      throw InvalidGenerationSourceError(
+          "'name' attribute not specified in @ExternalName annotation");
+    }
+    return name;
   }
 }
 

generator/test/code_builder_test.dart

@@ -379,8 +379,9 @@ void main() {
     });
   });
 
-  test('ExternalType annotation', () async {
-    final source = r'''
+  group("ExternalType and ExternalName annotations", () {
+    test('annotations work on properties', () async {
+      final source = r'''
       library example;     
       import 'package:objectbox/objectbox.dart';
       
@@ -390,25 +391,83 @@ void main() {
         int id = 0;
         
         @Property(type: PropertyType.byteVector)
-        @ExternalProperty(type: ExternalType.bson, name: 'my-mongo-bson')
-        List<int>? mongoBson;
+        @ExternalType(type: ExternalPropertyType.mongoId)
+        List<int>? mongoId;
+        
+        @ExternalType(type: ExternalPropertyType.uuid)
+        @ExternalName(name: 'my-mongo-uuid')
+        List<int>? mongoUuid;
+      }
+      ''';
+
+      final testEnv = GeneratorTestEnv();
+      await testEnv.run(source);
+
+      final property1 = testEnv.model.entities[0].properties
+          .firstWhere((element) => element.name == "mongoId");
+      expect(property1.externalPropertyType, OBXExternalPropertyType.MongoId);
+
+      final property2 = testEnv.model.entities[0].properties
+          .firstWhere((element) => element.name == "mongoUuid");
+      expect(property2.externalPropertyType, OBXExternalPropertyType.Uuid);
+      expect(property2.externalPropertyName, "my-mongo-uuid");
+    });
+
+    test('annotations work on ToMany (standalone) relations', () async {
+      final source = r'''
+      library example;     
+      import 'package:objectbox/objectbox.dart';
+      
+      @Entity()
+      class Student{
+        int id;
+        
+        @ExternalType(type: ExternalPropertyType.mongoId)
+        final rel1 = ToMany<Student>();
+        
+        @ExternalType(type: ExternalPropertyType.uuid)
+        @ExternalName(name: 'my-courses-rel')
+        final rel2 = ToMany<Student>();
+      }
+      ''';
+
+      final testEnv = GeneratorTestEnv();
+      await testEnv.run(source);
+
+      final relation1 = testEnv.model.entities[0].relations
+          .firstWhere((element) => element.name == "rel1");
+      expect(relation1.externalPropertyType, OBXExternalPropertyType.MongoId);
+
+      final relation2 = testEnv.model.entities[0].relations
+          .firstWhere((element) => element.name == "rel2");
+      expect(relation2.externalPropertyType, OBXExternalPropertyType.Uuid);
+      expect(relation2.externalPropertyName, "my-courses-rel");
+    });
+  });
+
+  test('Only ExternalName annotation fails', () async {
+    final source = r'''
+      library example;     
+      import 'package:objectbox/objectbox.dart';
+      
+      @Entity()
+      class Example {
+        @Id()
+        int id = 0;
         
-        @ExternalProperty(type: ExternalType.javaScript, name: 'my-mongo-js')
-        String? mongoJS;
+        @ExternalName(name: 'my-mongo-uuid')
+        List<int>? mongoUuid;
       }
       ''';
 
     final testEnv = GeneratorTestEnv();
-    await testEnv.run(source);
-
-    final property1 = testEnv.model.entities[0].properties
-        .firstWhere((element) => element.name == "mongoBson");
-    expect(property1.externalPropertyType, OBXExternalPropertyType.Bson);
-    expect(property1.externalPropertyName, "my-mongo-bson");
-    final property2 = testEnv.model.entities[0].properties
-        .firstWhere((element) => element.name == "mongoJS");
-    expect(property2.externalPropertyType, OBXExternalPropertyType.JavaScript);
-    expect(property2.externalPropertyName, "my-mongo-js");
+    await expectLater(
+        () async => await testEnv.run(source),
+        throwsA(isA<InvalidGenerationSourceError>().having(
+            (e) => e.message,
+            'message',
+            contains(
+                "@ExternalName annotation requires @ExternalType annotation to be present"))));
   });
 }
 

objectbox/lib/src/annotations.dart

@@ -491,8 +491,8 @@ class HnswIndex {
 /// A property type of an external system (e.g. another database) that has no
 /// default mapping to an ObjectBox type.
 ///
-/// Use with [ExternalProperty].
-enum ExternalType {
+/// Use with [ExternalType].
+enum ExternalPropertyType {
   /// Representing type: ByteVector
   ///
   /// Encoding: 1:1 binary representation, little endian (16 bytes)
@@ -581,15 +581,30 @@ enum ExternalType {
   mongoRegex
 }
 
-/// Annotates a property to be stored in an external system.
-class ExternalProperty {
-  /// The name assigned to the property in the external system.
-  final String? name;
-
+/// See the constructor documentation.
+class ExternalType {
   /// The type of the property in the external system.
-  /// See [ExternalType] for possible values.
-  final ExternalType type;
+  ///
+  /// See [ExternalPropertyType] for possible values.
+  final ExternalPropertyType type;
+
+  /// Sets the type of a property or the type of object IDs of a [ToMany] in an
+  /// external system (like another database).
+  ///
+  /// This is useful if there is no default mapping of the ObjectBox type to the
+  /// type in the external system.
+  ///
+  /// Carefully look at the documentation of the external type to ensure it is
+  /// compatible with the ObjectBox type.
+  const ExternalType({required this.type});
+}
+
+/// See the constructor documentation.
+class ExternalName {
+  /// The name assigned to the property in the external system.
+  final String name;
 
-  /// Create an ExternalProperty annotation.
-  const ExternalProperty({required this.type, this.name});
+  /// Sets the name of an @Entity, a property or a [ToMany] in an external
+  /// system (like another database).
+  const ExternalName({required this.name});
 }

objectbox/lib/src/modelinfo/enums.dart

@@ -240,37 +240,37 @@ abstract class OBXPropertyType {
   static const int DateNanoVector = 32;
 }
 
-int externalTypeToOBXExternalType(ExternalType type) {
+int externalTypeToOBXExternalType(ExternalPropertyType type) {
   switch (type) {
-    case ExternalType.int128:
+    case ExternalPropertyType.int128:
       return OBXExternalPropertyType.Int128;
-    case ExternalType.uuid:
+    case ExternalPropertyType.uuid:
       return OBXExternalPropertyType.Uuid;
-    case ExternalType.decimal128:
+    case ExternalPropertyType.decimal128:
       return OBXExternalPropertyType.Decimal128;
-    case ExternalType.flexMap:
+    case ExternalPropertyType.flexMap:
       return OBXExternalPropertyType.FlexMap;
-    case ExternalType.flexVector:
+    case ExternalPropertyType.flexVector:
       return OBXExternalPropertyType.FlexVector;
-    case ExternalType.json:
+    case ExternalPropertyType.json:
       return OBXExternalPropertyType.Json;
-    case ExternalType.bson:
+    case ExternalPropertyType.bson:
       return OBXExternalPropertyType.Bson;
-    case ExternalType.javaScript:
+    case ExternalPropertyType.javaScript:
       return OBXExternalPropertyType.JavaScript;
-    case ExternalType.int128Vector:
+    case ExternalPropertyType.int128Vector:
       return OBXExternalPropertyType.Int128Vector;
-    case ExternalType.uuidVector:
+    case ExternalPropertyType.uuidVector:
       return OBXExternalPropertyType.UuidVector;
-    case ExternalType.mongoId:
+    case ExternalPropertyType.mongoId:
       return OBXExternalPropertyType.MongoId;
-    case ExternalType.mongoIdVector:
+    case ExternalPropertyType.mongoIdVector:
       return OBXExternalPropertyType.MongoIdVector;
-    case ExternalType.mongoTimestamp:
+    case ExternalPropertyType.mongoTimestamp:
       return OBXExternalPropertyType.MongoTimestamp;
-    case ExternalType.mongoBinary:
+    case ExternalPropertyType.mongoBinary:
       return OBXExternalPropertyType.MongoBinary;
-    case ExternalType.mongoRegex:
+    case ExternalPropertyType.mongoRegex:
       return OBXExternalPropertyType.MongoRegex;
     default:
       throw ArgumentError.value(type, 'type', 'Invalid ExternalType');