External type: add annotation, model API and smoke test objectbox-java#239

Author: greenrobot-team

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

@@ -0,0 +1,123 @@
+/*
+ * Copyright 2025 ObjectBox Ltd. All rights reserved.
+ *
+ * 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;
+
+
+/**
+ * A property type of an external system (e.g. another database) that has no default mapping to an ObjectBox type.
+ * <p>
+ * Use with {@link ExternalType @ExternalType}.
+ */
+public enum ExternalPropertyType {
+
+    /**
+     * Representing type: ByteVector
+     * <p>
+     * Encoding: 1:1 binary representation, little endian (16 bytes)
+     */
+    INT_128,
+    /**
+     * Representing type: ByteVector
+     * <p>
+     * Encoding: 1:1 binary representation (16 bytes)
+     */
+    UUID,
+    /**
+     * IEEE 754 decimal128 type, e.g. supported by MongoDB.
+     * <p>
+     * Representing type: ByteVector
+     * <p>
+     * Encoding: 1:1 binary representation (16 bytes)
+     */
+    DECIMAL_128,
+    /**
+     * A key/value map; e.g. corresponds to a JSON object or a MongoDB document (although not keeping the key order).
+     * Unlike the Flex type, this must contain a map value (e.g. not a vector or a scalar).
+     * <p>
+     * Representing type: Flex
+     * <p>
+     * Encoding: Flex
+     */
+    FLEX_MAP,
+    /**
+     * A vector (aka list or array) of flexible elements; e.g. corresponds to a JSON array or a MongoDB array. Unlike
+     * the Flex type, this must contain a vector value (e.g. not a map or a scalar).
+     * <p>
+     * Representing type: Flex
+     * <p>
+     * Encoding: Flex
+     */
+    FLEX_VECTOR,
+    /**
+     * Placeholder (not yet used) for a JSON document.
+     * <p>
+     * Representing type: String
+     */
+    JSON,
+    /**
+     * Placeholder (not yet used) for a BSON document.
+     * <p>
+     * Representing type: ByteVector
+     */
+    BSON,
+    /**
+     * JavaScript source code.
+     * <p>
+     * Representing type: String
+     */
+    JAVASCRIPT,
+    /**
+     * A vector (array) of Int128 values.
+     */
+    INT_128_VECTOR,
+    /**
+     * A vector (array) of Int128 values.
+     */
+    UUID_VECTOR,
+    /**
+     * The 12-byte ObjectId type in MongoDB.
+     * <p>
+     * Representing type: ByteVector
+     * <p>
+     * Encoding: 1:1 binary representation (12 bytes)
+     */
+    MONGO_ID,
+    /**
+     * A vector (array) of MongoId values.
+     */
+    MONGO_ID_VECTOR,
+    /**
+     * Representing type: Long
+     * <p>
+     * Encoding: Two unsigned 32-bit integers merged into a 64-bit integer.
+     */
+    MONGO_TIMESTAMP,
+    /**
+     * Representing type: ByteVector
+     * <p>
+     * Encoding: 3 zero bytes (reserved, functions as padding), fourth byte is the sub-type, followed by the binary
+     * data.
+     */
+    MONGO_BINARY,
+    /**
+     * Representing type: string vector with 2 elements (index 0: pattern, index 1: options)
+     * <p>
+     * Encoding: 1:1 string representation
+     */
+    MONGO_REGEX
+
+}

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

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2025 ObjectBox Ltd. All rights reserved.
+ *
+ * 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;
+
+/**
+ * Use to set the type of property in an external system (like another database).
+ * <p>
+ * This is useful if there is no default mapping of the ObjectBox type to the type in the external system.
+ * <p>
+ * Carefully look at the documentation of the external type to ensure it is compatible with the ObjectBox type.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.FIELD})
+public @interface ExternalType {
+
+    ExternalPropertyType value();
+
+}

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

@@ -24,6 +24,7 @@
 import io.objectbox.annotation.HnswIndex;
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.flatbuffers.FlatBufferBuilder;
+import io.objectbox.model.ExternalPropertyType;
 import io.objectbox.model.HnswDistanceType;
 import io.objectbox.model.HnswFlags;
 import io.objectbox.model.HnswParams;
@@ -67,6 +68,7 @@ public class PropertyBuilder {
         private int indexId;
         private long indexUid;
         private int indexMaxValueLength;
+        private int externalPropertyType;
         private int hnswParamsOffset;
 
         PropertyBuilder(String name, @Nullable String targetEntityName, @Nullable String virtualTarget, int type) {
@@ -96,6 +98,17 @@ public PropertyBuilder indexMaxValueLength(int indexMaxValueLength) {
             return this;
         }
 
+        /**
+         * Set a {@link ExternalPropertyType} constant.
+         *
+         * @return this builder.
+         */
+        public PropertyBuilder externalType(int externalPropertyType) {
+            checkNotFinished();
+            this.externalPropertyType = externalPropertyType;
+            return this;
+        }
+
         /**
          * Set parameters for {@link HnswIndex}.
          *
@@ -183,6 +196,9 @@ public int finish() {
             if (indexMaxValueLength > 0) {
                 ModelProperty.addMaxIndexValueLength(fbb, indexMaxValueLength);
             }
+            if (externalPropertyType != 0) {
+                ModelProperty.addExternalType(fbb, externalPropertyType);
+            }
             if (hnswParamsOffset != 0) {
                 ModelProperty.addHnswParams(fbb, hnswParamsOffset);
             }

tests/objectbox-java-test/src/main/java/io/objectbox/TestEntity.java

@@ -24,6 +24,8 @@
 import javax.annotation.Nullable;
 
 import io.objectbox.annotation.Entity;
+import io.objectbox.annotation.ExternalPropertyType;
+import io.objectbox.annotation.ExternalType;
 import io.objectbox.annotation.Id;
 import io.objectbox.annotation.Unsigned;
 
@@ -73,6 +75,9 @@ public class TestEntity {
     private float[] floatArray;
     private double[] doubleArray;
     private Date date;
+    // Just smoke testing, also use UUID instead of the default Mongo ID
+    @ExternalType(ExternalPropertyType.UUID)
+    private byte[] externalId;
 
     transient boolean noArgsConstructorCalled;
 
@@ -107,7 +112,8 @@ public TestEntity(long id,
                       long[] longArray,
                       float[] floatArray,
                       double[] doubleArray,
-                      Date date
+                      Date date,
+                      byte[] externalId
     ) {
         this.id = id;
         this.simpleBoolean = simpleBoolean;
@@ -133,6 +139,7 @@ public TestEntity(long id,
         this.floatArray = floatArray;
         this.doubleArray = doubleArray;
         this.date = date;
+        this.externalId = externalId;
         if (STRING_VALUE_THROW_IN_CONSTRUCTOR.equals(simpleString)) {
             throw new RuntimeException(EXCEPTION_IN_CONSTRUCTOR_MESSAGE);
         }
@@ -348,6 +355,17 @@ public void setDate(Date date) {
         this.date = date;
     }
 
+    @Nullable
+    public byte[] getExternalId() {
+        return externalId;
+    }
+
+    @Nullable
+    public TestEntity setExternalId(byte[] externalId) {
+        this.externalId = externalId;
+        return this;
+    }
+
     @Override
     public String toString() {
         return "TestEntity{" +
@@ -375,6 +393,7 @@ public String toString() {
                 ", floatArray=" + Arrays.toString(floatArray) +
                 ", doubleArray=" + Arrays.toString(doubleArray) +
                 ", date=" + date +
+                ", externalId=" + Arrays.toString(externalId) +
                 ", noArgsConstructorCalled=" + noArgsConstructorCalled +
                 '}';
     }

tests/objectbox-java-test/src/main/java/io/objectbox/TestEntityCursor.java

@@ -73,6 +73,7 @@ public Cursor<TestEntity> createCursor(io.objectbox.Transaction tx, long cursorH
     private final static int __ID_floatArray = TestEntity_.floatArray.id;
     private final static int __ID_doubleArray = TestEntity_.doubleArray.id;
     private final static int __ID_date = TestEntity_.date.id;
+    private final static int __ID_externalId = TestEntity_.externalId.id;
 
     public TestEntityCursor(io.objectbox.Transaction tx, long cursor, BoxStore boxStore) {
         super(tx, cursor, TestEntity_.__INSTANCE, boxStore);
@@ -143,23 +144,25 @@ public long put(TestEntity entity) {
         int __id8 = simpleString != null ? __ID_simpleString : 0;
         byte[] simpleByteArray = entity.getSimpleByteArray();
         int __id9 = simpleByteArray != null ? __ID_simpleByteArray : 0;
+        byte[] externalId = entity.getExternalId();
+        int __id24 = externalId != null ? __ID_externalId : 0;
         Map stringObjectMap = entity.getStringObjectMap();
         int __id15 = stringObjectMap != null ? __ID_stringObjectMap : 0;
-        Object flexProperty = entity.getFlexProperty();
-        int __id16 = flexProperty != null ? __ID_flexProperty : 0;
 
         collect430000(cursor, 0, 0,
                 __id8, simpleString, 0, null,
                 0, null, 0, null,
-                __id9, simpleByteArray, __id15, __id15 != 0 ? stringObjectMapConverter.convertToDatabaseValue(stringObjectMap) : null,
-                __id16, __id16 != 0 ? flexPropertyConverter.convertToDatabaseValue(flexProperty) : null);
+                __id9, simpleByteArray, __id24, externalId,
+                __id15, __id15 != 0 ? stringObjectMapConverter.convertToDatabaseValue(stringObjectMap) : null);
 
+        Object flexProperty = entity.getFlexProperty();
+        int __id16 = flexProperty != null ? __ID_flexProperty : 0;
         java.util.Date date = entity.getDate();
         int __id23 = date != null ? __ID_date : 0;
 
         collect313311(cursor, 0, 0,
                 0, null, 0, null,
-                0, null, 0, null,
+                0, null, __id16, __id16 != 0 ? flexPropertyConverter.convertToDatabaseValue(flexProperty) : null,
                 __ID_simpleLong, entity.getSimpleLong(), __ID_simpleLongU, entity.getSimpleLongU(),
                 __id23, __id23 != 0 ? date.getTime() : 0, INT_NULL_HACK ? 0 : __ID_simpleInt, entity.getSimpleInt(),
                 __ID_simpleIntU, entity.getSimpleIntU(), __ID_simpleShort, entity.getSimpleShort(),

tests/objectbox-java-test/src/main/java/io/objectbox/TestEntity_.java

@@ -124,6 +124,9 @@ public final class TestEntity_ implements EntityInfo<TestEntity> {
     public final static io.objectbox.Property<TestEntity> date =
             new io.objectbox.Property<>(__INSTANCE, 23, 24, java.util.Date.class, "date");
 
+    public final static io.objectbox.Property<TestEntity> externalId =
+            new io.objectbox.Property<>(__INSTANCE, 24, 25, byte[].class, "externalId");
+
     @SuppressWarnings("unchecked")
     public final static io.objectbox.Property<TestEntity>[] __ALL_PROPERTIES = new io.objectbox.Property[]{
             id,
@@ -149,7 +152,8 @@ public final class TestEntity_ implements EntityInfo<TestEntity> {
             longArray,
             floatArray,
             doubleArray,
-            date
+            date,
+            externalId
     };
 
     public final static io.objectbox.Property<TestEntity> __ID_PROPERTY = id;

tests/objectbox-java-test/src/test/java/io/objectbox/AbstractObjectBoxTest.java

@@ -42,6 +42,7 @@
 import io.objectbox.ModelBuilder.PropertyBuilder;
 import io.objectbox.annotation.IndexType;
 import io.objectbox.config.DebugFlags;
+import io.objectbox.model.ExternalPropertyType;
 import io.objectbox.model.PropertyFlags;
 import io.objectbox.model.PropertyType;
 
@@ -303,7 +304,14 @@ private void addTestEntity(ModelBuilder modelBuilder, @Nullable IndexType simple
         // Date property
         entityBuilder.property("date", PropertyType.Date).id(TestEntity_.date.id, ++lastUid);
 
-        int lastId = TestEntity_.date.id;
+        int lastId = TestEntity_.externalId.id;
+
+        // External type property
+        // Note: there is no way to test external type mapping works here. Instead, verify passing a model with
+        // externalType(int) works.
+        entityBuilder.property("externalId", PropertyType.ByteVector).id(lastId, ++lastUid)
+                .externalType(ExternalPropertyType.Uuid);
+
         entityBuilder.lastPropertyId(lastId, lastUid);
         addOptionalFlagsToTestEntity(entityBuilder);
         entityBuilder.entityDone();
@@ -357,6 +365,9 @@ protected TestEntity createTestEntity(@Nullable String simpleString, int nr) {
         entity.setFloatArray(new float[]{-entity.getSimpleFloat(), entity.getSimpleFloat()});
         entity.setDoubleArray(new double[]{-entity.getSimpleDouble(), entity.getSimpleDouble()});
         entity.setDate(new Date(1000 + nr));
+        // Note: there is no way to test external type mapping works here. Instead, verify that
+        // there are no side effects for put and get.
+        entity.setExternalId(entity.getSimpleByteArray());
         return entity;
     }
 

tests/objectbox-java-test/src/test/java/io/objectbox/BoxStoreBuilderTest.java

@@ -302,7 +302,7 @@ public void maxDataSize() {
                 DbMaxDataSizeExceededException.class,
                 () -> getTestEntityBox().put(testEntity2)
         );
-        assertEquals("Exceeded user-set maximum by [bytes]: 544", maxDataExc.getMessage());
+        assertEquals("Exceeded user-set maximum by [bytes]: 560", maxDataExc.getMessage());
 
         // Remove to get below max data size, then put again.
         getTestEntityBox().remove(testEntity1);