Tests: update docs on relation test classes

Author: greenrobot-team

tests/objectbox-java-test/src/main/java/io/objectbox/relation/Customer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 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.
@@ -24,10 +24,15 @@
 import io.objectbox.annotation.Entity;
 import io.objectbox.annotation.Id;
 import io.objectbox.annotation.Index;
-import io.objectbox.annotation.apihint.Internal;
 
 /**
- * Entity mapped to table "CUSTOMER".
+ * Customer entity to test relations together with {@link Order}.
+ * <p>
+ * The annotations in this class have no effect as the Gradle plugin is not configured in this project. However, test
+ * code builds a model like if the annotations were processed.
+ * <p>
+ * There is a matching test in the internal integration test project where this is tested and model builder code can be
+ * "stolen" from.
  */
 @Entity
 public class Customer implements Serializable {
@@ -38,12 +43,16 @@ public class Customer implements Serializable {
     @Index
     private String name;
 
-    @Backlink(to = "customer") // Annotation not processed in this test, is set up manually.
+    // Note: in a typical project the relation fields are initialized by the ObjectBox byte code transformer
+    // https://docs.objectbox.io/relations#initialization-magic
+
+    @Backlink(to = "customer")
     List<Order> orders = new ToMany<>(this, Customer_.orders);
 
     ToMany<Order> ordersStandalone = new ToMany<>(this, Customer_.ordersStandalone);
 
-    /** Used to resolve relations. */
+    // Note: in a typical project the BoxStore field is added by the ObjectBox byte code transformer
+    // https://docs.objectbox.io/relations#initialization-magic
     transient BoxStore __boxStore;
 
     public Customer() {

tests/objectbox-java-test/src/main/java/io/objectbox/relation/CustomerCursor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 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.
@@ -22,7 +22,8 @@
 import io.objectbox.Transaction;
 import io.objectbox.internal.CursorFactory;
 
-// THIS CODE IS ADAPTED from generated resources of the test-entity-annotations project
+// NOTE: Instead of updating this by hand, copy changes from the internal integration test project after updating its
+// Customer class.
 
 /**
  * Cursor for DB entity "Customer".

tests/objectbox-java-test/src/main/java/io/objectbox/relation/Customer_.java

@@ -1,6 +1,5 @@
-
 /*
- * Copyright 2017 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.
@@ -28,7 +27,8 @@
 import io.objectbox.internal.ToOneGetter;
 import io.objectbox.relation.CustomerCursor.Factory;
 
-// THIS CODE IS ADAPTED from generated resources of the test-entity-annotations project
+// NOTE: Instead of updating this by hand, copy changes from the internal integration test project after updating its
+// Customer class.
 
 /**
  * Properties for entity "Customer". Can be used for QueryBuilder and for referencing DB names.

tests/objectbox-java-test/src/main/java/io/objectbox/relation/MyObjectBox.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 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.
@@ -23,8 +23,9 @@
 import io.objectbox.model.PropertyFlags;
 import io.objectbox.model.PropertyType;
 
+// NOTE: Instead of updating this by hand, copy changes from the internal integration test project after updating its
+// Customer class.
 
-// THIS CODE IS ADAPTED from generated resources of the test-entity-annotations project
 /**
  * Starting point for working with your ObjectBox. All boxes are set up for your objects here.
  * <p>

tests/objectbox-java-test/src/main/java/io/objectbox/relation/Order.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 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.
@@ -18,16 +18,19 @@
 
 import java.io.Serializable;
 
-import javax.annotation.Nullable;
-
 import io.objectbox.BoxStore;
 import io.objectbox.annotation.Entity;
 import io.objectbox.annotation.Id;
 import io.objectbox.annotation.NameInDb;
-import io.objectbox.annotation.apihint.Internal;
 
 /**
- * Entity mapped to table "ORDERS".
+ * Order entity to test relations together with {@link Customer}.
+ * <p>
+ * The annotations in this class have no effect as the Gradle plugin is not configured in this project. However, test
+ * code builds a model like if the annotations were processed.
+ * <p>
+ * There is a matching test in the internal integration test project where this is tested and model builder code can be
+ * "stolen" from.
  */
 @Entity
 @NameInDb("ORDERS")
@@ -39,10 +42,13 @@ public class Order implements Serializable {
     long customerId;
     String text;
 
+    // Note: in a typical project the relation fields are initialized by the ObjectBox byte code transformer
+    // https://docs.objectbox.io/relations#initialization-magic
     @SuppressWarnings("FieldMayBeFinal")
     private ToOne<Customer> customer = new ToOne<>(this, Order_.customer);
 
-    /** Used to resolve relations. */
+    // Note: in a typical project the BoxStore field is added by the ObjectBox byte code transformer
+    // https://docs.objectbox.io/relations#initialization-magic
     transient BoxStore __boxStore;
 
     public Order() {

tests/objectbox-java-test/src/main/java/io/objectbox/relation/OrderCursor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 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.
@@ -18,11 +18,11 @@
 
 import io.objectbox.BoxStore;
 import io.objectbox.Cursor;
-import io.objectbox.EntityInfo;
 import io.objectbox.Transaction;
 import io.objectbox.internal.CursorFactory;
 
-// THIS CODE IS ADAPTED from generated resources of the test-entity-annotations project
+// NOTE: Instead of updating this by hand, copy changes from the internal integration test project after updating its
+// Customer class.
 
 /**
  * Cursor for DB entity "ORDERS".

tests/objectbox-java-test/src/main/java/io/objectbox/relation/Order_.java

@@ -1,6 +1,6 @@
 
 /*
- * Copyright 2017 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.
@@ -25,7 +25,8 @@
 import io.objectbox.internal.ToOneGetter;
 import io.objectbox.relation.OrderCursor.Factory;
 
-// THIS CODE IS ADAPTED from generated resources of the test-entity-annotations project
+// NOTE: Instead of updating this by hand, copy changes from the internal integration test project after updating its
+// Customer class.
 
 /**
  * Properties for entity "ORDERS". Can be used for QueryBuilder and for referencing DB names.