ModelBuilder: make relation buildable, extract common builder code

Author: greenrobot-team

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-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.
@@ -34,34 +34,82 @@
 import io.objectbox.model.ModelProperty;
 import io.objectbox.model.ModelRelation;
 
-// Remember: IdUid is a struct, not a table, and thus must be inlined
-@SuppressWarnings("WeakerAccess,UnusedReturnValue, unused")
+// To learn how to use the FlatBuffers API see https://flatbuffers.dev/tutorial/
+// Note: IdUid is a struct, not a table, and thus must be inlined
+
+/**
+ * Builds a flatbuffer representation of the database model to be passed when opening a store.
+ * <p>
+ * This is an internal API that should only be called by the generated MyObjectBox code.
+ */
 @Internal
 public class ModelBuilder {
     private static final int MODEL_VERSION = 2;
 
-    final FlatBufferBuilder fbb = new FlatBufferBuilder();
-    final List<Integer> entityOffsets = new ArrayList<>();
+    private final FlatBufferBuilder fbb = new FlatBufferBuilder();
+    private final List<Integer> entityOffsets = new ArrayList<>();
+
+    private long version = 1;
+
+    private Integer lastEntityId;
+    private Long lastEntityUid;
+
+    private Integer lastIndexId;
+    private Long lastIndexUid;
+
+    private Integer lastRelationId;
+    private Long lastRelationUid;
+
+    /**
+     * Base class for builders.
+     * <p>
+     * Methods adding properties to be used by {@link #createFlatBufferTable(FlatBufferBuilder)} should call
+     * {@link #checkNotFinished()}.
+     * <p>
+     * The last call should be {@link #finish()}.
+     */
+    abstract static class PartBuilder {
+
+        private final FlatBufferBuilder fbb;
+        private boolean finished;
+
+        PartBuilder(FlatBufferBuilder fbb) {
+            this.fbb = fbb;
+        }
 
-    long version = 1;
+        FlatBufferBuilder getFbb() {
+            return fbb;
+        }
 
-    Integer lastEntityId;
-    Long lastEntityUid;
+        void checkNotFinished() {
+            if (finished) {
+                throw new IllegalStateException("Already finished");
+            }
+        }
+
+        /**
+         * Marks this as finished and returns {@link #createFlatBufferTable(FlatBufferBuilder)}.
+         */
+        public final int finish() {
+            checkNotFinished();
+            finished = true;
+            return createFlatBufferTable(getFbb());
+        }
 
-    Integer lastIndexId;
-    Long lastIndexUid;
+        /**
+         * Creates a flatbuffer table using the given builder and returns its offset.
+         */
+        public abstract int createFlatBufferTable(FlatBufferBuilder fbb);
+    }
 
-    Integer lastRelationId;
-    Long lastRelationUid;
+    public static class PropertyBuilder extends PartBuilder {
 
-    public class PropertyBuilder {
         private final int type;
         private final int virtualTargetOffset;
         private final int propertyNameOffset;
         private final int targetEntityOffset;
 
         private int secondaryNameOffset;
-        boolean finished;
         private int flags;
         private int id;
         private long uid;
@@ -71,7 +119,9 @@ public class PropertyBuilder {
         private int externalPropertyType;
         private int hnswParamsOffset;
 
-        PropertyBuilder(String name, @Nullable String targetEntityName, @Nullable String virtualTarget, int type) {
+        private PropertyBuilder(FlatBufferBuilder fbb, String name, @Nullable String targetEntityName,
+                                @Nullable String virtualTarget, int type) {
+            super(fbb);
             this.type = type;
             propertyNameOffset = fbb.createString(name);
             targetEntityOffset = targetEntityName != null ? fbb.createString(targetEntityName) : 0;
@@ -129,6 +179,7 @@ public PropertyBuilder hnswParams(long dimensions,
                                           @Nullable Float reparationBacklinkProbability,
                                           @Nullable Long vectorCacheHintSizeKb) {
             checkNotFinished();
+            FlatBufferBuilder fbb = getFbb();
             HnswParams.startHnswParams(fbb);
             HnswParams.addDimensions(fbb, dimensions);
             if (neighborsPerNode != null) {
@@ -161,19 +212,12 @@ public PropertyBuilder flags(int flags) {
 
         public PropertyBuilder secondaryName(String secondaryName) {
             checkNotFinished();
-            secondaryNameOffset = fbb.createString(secondaryName);
+            secondaryNameOffset = getFbb().createString(secondaryName);
             return this;
         }
 
-        private void checkNotFinished() {
-            if (finished) {
-                throw new IllegalStateException("Already finished");
-            }
-        }
-
-        public int finish() {
-            checkNotFinished();
-            finished = true;
+        @Override
+        public int createFlatBufferTable(FlatBufferBuilder fbb) {
             ModelProperty.startModelProperty(fbb);
             ModelProperty.addName(fbb, propertyNameOffset);
             if (targetEntityOffset != 0) {
@@ -210,7 +254,41 @@ public int finish() {
         }
     }
 
-    public class EntityBuilder {
+    public static class RelationBuilder extends PartBuilder {
+
+        private final String name;
+        private final int relationId;
+        private final long relationUid;
+        private final int targetEntityId;
+        private final long targetEntityUid;
+
+        private RelationBuilder(FlatBufferBuilder fbb, String name, int relationId, long relationUid,
+                                int targetEntityId, long targetEntityUid) {
+            super(fbb);
+            this.name = name;
+            this.relationId = relationId;
+            this.relationUid = relationUid;
+            this.targetEntityId = targetEntityId;
+            this.targetEntityUid = targetEntityUid;
+        }
+
+        @Override
+        public int createFlatBufferTable(FlatBufferBuilder fbb) {
+            int nameOffset = fbb.createString(name);
+
+            ModelRelation.startModelRelation(fbb);
+            ModelRelation.addName(fbb, nameOffset);
+            int relationIdOffset = IdUid.createIdUid(fbb, relationId, relationUid);
+            ModelRelation.addId(fbb, relationIdOffset);
+            int targetEntityIdOffset = IdUid.createIdUid(fbb, targetEntityId, targetEntityUid);
+            ModelRelation.addTargetEntityId(fbb, targetEntityIdOffset);
+            return ModelRelation.endModelRelation(fbb);
+        }
+    }
+
+    public static class EntityBuilder extends PartBuilder {
+
+        private final ModelBuilder model;
         final String name;
         final List<Integer> propertyOffsets = new ArrayList<>();
         final List<Integer> relationOffsets = new ArrayList<>();
@@ -220,10 +298,13 @@ public class EntityBuilder {
         Integer flags;
         Integer lastPropertyId;
         Long lastPropertyUid;
-        PropertyBuilder propertyBuilder;
+        @Nullable PropertyBuilder propertyBuilder;
+        @Nullable RelationBuilder relationBuilder;
         boolean finished;
 
-        EntityBuilder(String name) {
+        EntityBuilder(ModelBuilder model, FlatBufferBuilder fbb, String name) {
+            super(fbb);
+            this.model = model;
             this.name = name;
         }
 
@@ -246,12 +327,6 @@ public EntityBuilder flags(int flags) {
             return this;
         }
 
-        private void checkNotFinished() {
-            if (finished) {
-                throw new IllegalStateException("Already finished");
-            }
-        }
-
         public PropertyBuilder property(String name, int type) {
             return property(name, null, type);
         }
@@ -263,43 +338,48 @@ public PropertyBuilder property(String name, @Nullable String targetEntityName,
         public PropertyBuilder property(String name, @Nullable String targetEntityName, @Nullable String virtualTarget,
                                         int type) {
             checkNotFinished();
-            checkFinishProperty();
-            propertyBuilder = new PropertyBuilder(name, targetEntityName, virtualTarget, type);
+            finishPropertyOrRelation();
+            propertyBuilder = new PropertyBuilder(getFbb(), name, targetEntityName, virtualTarget, type);
             return propertyBuilder;
         }
 
-        void checkFinishProperty() {
+        public RelationBuilder relation(String name, int relationId, long relationUid, int targetEntityId,
+                                        long targetEntityUid) {
+            checkNotFinished();
+            finishPropertyOrRelation();
+
+            RelationBuilder relationBuilder = new RelationBuilder(getFbb(), name, relationId, relationUid, targetEntityId, targetEntityUid);
+            this.relationBuilder = relationBuilder;
+            return relationBuilder;
+        }
+
+        private void finishPropertyOrRelation() {
+            if (propertyBuilder != null && relationBuilder != null) {
+                throw new IllegalStateException("Must not build property and relation at the same time.");
+            }
             if (propertyBuilder != null) {
                 propertyOffsets.add(propertyBuilder.finish());
                 propertyBuilder = null;
             }
+            if (relationBuilder != null) {
+                relationOffsets.add(relationBuilder.finish());
+                relationBuilder = null;
+            }
         }
 
-        public EntityBuilder relation(String name, int relationId, long relationUid, int targetEntityId,
-                                      long targetEntityUid) {
+        public ModelBuilder entityDone() {
+            // Make sure any pending property or relation is finished first
             checkNotFinished();
-            checkFinishProperty();
-
-            int propertyNameOffset = fbb.createString(name);
-
-            ModelRelation.startModelRelation(fbb);
-            ModelRelation.addName(fbb, propertyNameOffset);
-            int relationIdOffset = IdUid.createIdUid(fbb, relationId, relationUid);
-            ModelRelation.addId(fbb, relationIdOffset);
-            int targetEntityIdOffset = IdUid.createIdUid(fbb, targetEntityId, targetEntityUid);
-            ModelRelation.addTargetEntityId(fbb, targetEntityIdOffset);
-            relationOffsets.add(ModelRelation.endModelRelation(fbb));
-
-            return this;
+            finishPropertyOrRelation();
+            model.entityOffsets.add(finish());
+            return model;
         }
 
-        public ModelBuilder entityDone() {
-            checkNotFinished();
-            checkFinishProperty();
-            finished = true;
+        @Override
+        public int createFlatBufferTable(FlatBufferBuilder fbb) {
             int testEntityNameOffset = fbb.createString(name);
-            int propertiesOffset = createVector(propertyOffsets);
-            int relationsOffset = relationOffsets.isEmpty() ? 0 : createVector(relationOffsets);
+            int propertiesOffset = model.createVector(propertyOffsets);
+            int relationsOffset = relationOffsets.isEmpty() ? 0 : model.createVector(relationOffsets);
 
             ModelEntity.startModelEntity(fbb);
             ModelEntity.addName(fbb, testEntityNameOffset);
@@ -316,12 +396,12 @@ public ModelBuilder entityDone() {
             if (flags != null) {
                 ModelEntity.addFlags(fbb, flags);
             }
-            entityOffsets.add(ModelEntity.endModelEntity(fbb));
-            return ModelBuilder.this;
+            return ModelEntity.endModelEntity(fbb);
         }
+
     }
 
-    int createVector(List<Integer> offsets) {
+    private int createVector(List<Integer> offsets) {
         int[] offsetArray = new int[offsets.size()];
         for (int i = 0; i < offsets.size(); i++) {
             offsetArray[i] = offsets.get(i);
@@ -335,7 +415,7 @@ public ModelBuilder version(long version) {
     }
 
     public EntityBuilder entity(String name) {
-        return new EntityBuilder(name);
+        return new EntityBuilder(this, fbb, name);
     }
 
     public ModelBuilder lastEntityId(int lastEntityId, long lastEntityUid) {