Package io.objectbox.relation

Class ToOne<TARGET>

java.lang.Object
io.objectbox.relation.ToOne<TARGET>
Type Parameters:
TARGET - target object type (@Entity class).
All Implemented Interfaces:
Serializable
public class ToOne<TARGET> extends Object implements Serializable
A to-one relation of an entity that references one object of a ToOne entity.

Example: 


 // Java
 @Entity
 public class Order {
     private ToOne<Customer> customer;
 }

 // Kotlin
 @Entity
 data class Order() {
     lateinit var customer: ToOne<Customer>
 }

Uses lazy initialization. The target object (getTarget()) is only read from the database when it is first accessed.

Common usage:

  • Set the target object with setTarget(TARGET) to create a relation. When the object with the ToOne is put, if the target object is new (its ID is 0), it will be put as well. Otherwise, only the target ID in the database is updated.
  • setTargetId(long) of the target object to create a relation.
  • setTarget(TARGET) with null or setTargetId(long) to 0 to remove the relation.

Then, to persist the changes Box.put(T) the object with the ToOne. 


 // Example 1: create a relation
 order.getCustomer().setTarget(customer);
 // or order.getCustomer().setTargetId(customerId);
 store.boxFor(Order.class).put(order);

 // Example 2: remove the relation
 order.getCustomer().setTarget(null);
 // or order.getCustomer().setTargetId(0);
 store.boxFor(Order.class).put(order);

The target object is referenced by its ID. This target ID (getTargetId()) is persisted as part of the object with the ToOne in a special property created for each ToOne (named like "customerId").

To get all objects with a ToOne that reference a target object, see Backlink.

See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      See Also:

    • entity

      private final Object entity

    • relationInfo

      private final RelationInfo<Object,TARGET> relationInfo

    • virtualProperty

      private final boolean virtualProperty

    • boxStore

      private transient BoxStore boxStore

    • entityBox

      private transient Box<Object> entityBox

    • targetBox

      private transient volatile Box<TARGET> targetBox

    • targetIdField

      private transient Field targetIdField

    • target

      private TARGET target
      Resolved target entity is cached

    • targetId

      private long targetId

    • resolvedTargetId

      private volatile long resolvedTargetId

    • checkIdOfTargetForPut

      private boolean checkIdOfTargetForPut
      To avoid calls to getTargetId(), which may involve expensive reflection.

    • debugRelations

      private boolean debugRelations

  • Constructor Details

    • ToOne

      public ToOne(Object sourceEntity, RelationInfo<?,TARGET> relationInfo)
      In Java, the constructor call is generated by the ObjectBox plugin.
      Parameters:
      sourceEntity - The source entity that owns the to-one relation.
      relationInfo - Meta info as generated in the Entity_ (entity name plus underscore) classes.

  • Method Details

    • getTarget

      public TARGET getTarget()
      Returns the target object or null if there is none.

      ToOne uses lazy initialization, so on first access this will read the target object from the database.

    • getTarget

      @Internal public TARGET getTarget(long targetId)
      If property backed, entities can pass the target ID to avoid reflection.

    • ensureBoxes

      private void ensureBoxes(@Nullable TARGET target)

    • getCachedTarget

      public TARGET getCachedTarget()

    • isResolved

      public boolean isResolved()

    • isResolvedAndNotNull

      public boolean isResolvedAndNotNull()

    • isNull

      public boolean isNull()

    • setTargetId

      public void setTargetId(long targetId)
      Prepares to set the target of this relation to the object with the given ID. Pass 0 to remove an existing one.

      To apply changes, put the object with the ToOne. For important details, see the notes about relations of Box.put(Object).

      See Also:

    • setAndUpdateTargetId

      void setAndUpdateTargetId(long targetId)

    • setTarget

      public void setTarget(@Nullable TARGET target)
      Prepares to set the target object of this relation. Pass null to remove an existing one.

      To apply changes, put the object with the ToOne. For important details, see the notes about relations of Box.put(Object).

      See Also:

    • setAndPutTarget

      public void setAndPutTarget(@Nullable TARGET target)
      Sets or clears the target entity and ID in the source entity, then puts the source entity to persist changes. Pass null to clear.

      If the target entity was not put yet (its ID is 0), it will be put before the source entity.

    • setAndPutTargetAlways

      public void setAndPutTargetAlways(@Nullable TARGET target)
      Sets or clears the target entity and ID in the source entity, then puts the target (if not null) and source entity to persist changes. Pass null to clear.

      When clearing the target entity, this does not remove it from its box. This only dissolves the relation.

    • setResolvedTarget

      private void setResolvedTarget(@Nullable TARGET target, long targetId)
      Both values should be set (and read) "atomically" using synchronized.

    • clearResolved

      private void clearResolved()
      Clears the target.

    • getTargetId

      public long getTargetId()

    • getTargetIdField

      private Field getTargetIdField()

    • internalRequiresPutTarget

      @Internal public boolean internalRequiresPutTarget()

    • internalPutTarget

      @Internal public void internalPutTarget(Cursor<TARGET> targetCursor)

    • getEntity

      Object getEntity()
      For tests

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object