External name: add annotation, model API #239

Author: greenrobot-team

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

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 ObjectBox Ltd.
+ *
+ * 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;
+
+/**
+ * Sets the name of an {@link Entity @Entity}, a property or a ToMany in an external system (like another database).
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.TYPE, ElementType.FIELD})
+public @interface ExternalName {
+
+    /**
+     * The name assigned to the annotated element in the external system.
+     */
+    String value();
+
+}

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

@@ -21,6 +21,8 @@
 
 import javax.annotation.Nullable;
 
+import io.objectbox.annotation.ExternalName;
+import io.objectbox.annotation.ExternalType;
 import io.objectbox.annotation.HnswIndex;
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.flatbuffers.FlatBufferBuilder;
@@ -123,6 +125,7 @@ public static class PropertyBuilder extends PartBuilder {
         private int indexId;
         private long indexUid;
         private int indexMaxValueLength;
+        private int externalNameOffset;
         private int externalType;
         private int hnswParamsOffset;
         private int flags;
@@ -166,9 +169,16 @@ public PropertyBuilder indexMaxValueLength(int indexMaxValueLength) {
         }
 
         /**
-         * Sets the {@link ExternalPropertyType} constant for this.
-         *
-         * @return this builder.
+         * Sets the {@link ExternalName} of this property.
+         */
+        public PropertyBuilder externalName(String externalName) {
+            checkNotFinished();
+            externalNameOffset = getFbb().createString(externalName);
+            return this;
+        }
+
+        /**
+         * Sets the {@link ExternalType} of this property. Should be one of {@link ExternalPropertyType}.
          */
         public PropertyBuilder externalType(int externalType) {
             checkNotFinished();
@@ -247,6 +257,7 @@ public int createFlatBufferTable(FlatBufferBuilder fbb) {
                 ModelProperty.addIndexId(fbb, indexIdOffset);
             }
             if (indexMaxValueLength > 0) ModelProperty.addMaxIndexValueLength(fbb, indexMaxValueLength);
+            if (externalNameOffset != 0) ModelProperty.addExternalName(fbb, externalNameOffset);
             if (externalType != 0) ModelProperty.addExternalType(fbb, externalType);
             if (hnswParamsOffset != 0) ModelProperty.addHnswParams(fbb, hnswParamsOffset);
             if (flags != 0) ModelProperty.addFlags(fbb, flags);
@@ -262,6 +273,7 @@ public static class RelationBuilder extends PartBuilder {
         private final int targetEntityId;
         private final long targetEntityUid;
 
+        private int externalNameOffset;
         private int externalType;
 
         private RelationBuilder(FlatBufferBuilder fbb, String name, int relationId, long relationUid,
@@ -275,9 +287,16 @@ private RelationBuilder(FlatBufferBuilder fbb, String name, int relationId, long
         }
 
         /**
-         * Sets the {@link ExternalPropertyType} constant for this.
-         *
-         * @return this builder.
+         * Sets the {@link ExternalName} of this relation.
+         */
+        public RelationBuilder externalName(String externalName) {
+            checkNotFinished();
+            externalNameOffset = getFbb().createString(externalName);
+            return this;
+        }
+
+        /**
+         * Sets the {@link ExternalType} of this relation. Should be one of {@link ExternalPropertyType}.
          */
         public RelationBuilder externalType(int externalType) {
             checkNotFinished();
@@ -295,6 +314,7 @@ public int createFlatBufferTable(FlatBufferBuilder fbb) {
             ModelRelation.addId(fbb, relationIdOffset);
             int targetEntityIdOffset = IdUid.createIdUid(fbb, targetEntityId, targetEntityUid);
             ModelRelation.addTargetEntityId(fbb, targetEntityIdOffset);
+            if (externalNameOffset != 0) ModelRelation.addExternalName(fbb, externalNameOffset);
             if (externalType != 0) ModelRelation.addExternalType(fbb, externalType);
             return ModelRelation.endModelRelation(fbb);
         }
@@ -311,6 +331,7 @@ public static class EntityBuilder extends PartBuilder {
         private Long uid;
         private Integer lastPropertyId;
         private Long lastPropertyUid;
+        @Nullable private String externalName;
         private Integer flags;
         @Nullable private PropertyBuilder propertyBuilder;
         @Nullable private RelationBuilder relationBuilder;
@@ -335,6 +356,15 @@ public EntityBuilder lastPropertyId(int lastPropertyId, long lastPropertyUid) {
             return this;
         }
 
+        /**
+         * Sets the {@link ExternalName} of this entity.
+         */
+        public EntityBuilder externalName(String externalName) {
+            checkNotFinished();
+            this.externalName = externalName;
+            return this;
+        }
+
         /**
          * One or more of {@link io.objectbox.model.EntityFlags}.
          */
@@ -402,6 +432,7 @@ public ModelBuilder entityDone() {
         @Override
         public int createFlatBufferTable(FlatBufferBuilder fbb) {
             int nameOffset = fbb.createString(name);
+            int externalNameOffset = externalName != null ? fbb.createString(externalName) : 0;
             int propertiesOffset = model.createVector(propertyOffsets);
             int relationsOffset = relationOffsets.isEmpty() ? 0 : model.createVector(relationOffsets);
 
@@ -417,6 +448,7 @@ public int createFlatBufferTable(FlatBufferBuilder fbb) {
                 int idOffset = IdUid.createIdUid(fbb, lastPropertyId, lastPropertyUid);
                 ModelEntity.addLastPropertyId(fbb, idOffset);
             }
+            if (externalNameOffset != 0) ModelEntity.addExternalName(fbb, externalNameOffset);
             if (flags != null) ModelEntity.addFlags(fbb, flags);
             return ModelEntity.endModelEntity(fbb);
         }