Package io.objectbox

Class Box<T>

java.lang.Object
io.objectbox.Box<T>
@ThreadSafe public class Box<T> extends Object
A Box to put and get Objects of a specific Entity class.

Thread-safe.

  • Method Details

    • closeThreadResources

      public void closeThreadResources()
      Like BoxStore.closeThreadResources(), but limited to only this Box.

      Rule of thumb: prefer BoxStore.closeThreadResources() unless you know that your thread only interacted with this Box.

    • getId

      @Internal public long getId(T entity)

    • get

      public T get(long id)
      Get the stored object for the given ID.
      Returns:
      null if not found

    • get

      public List<T> get(Iterable<Long> ids)
      Get the stored objects for the given IDs.
      Returns:
      null if not found

    • get

      public List<T> get(long[] ids)
      Get the stored objects for the given IDs.
      Returns:
      null if not found

    • getMap

      public Map<Long,T> getMap(Iterable<Long> ids)
      Get the stored objects for the given IDs as a Map with IDs as keys, and entities as values. IDs for which no entity is found will be put in the map with null values.
      Returns:
      null if not found

    • count

      public long count()
      Returns the count of all stored objects in this box.

    • count

      public long count(long maxCount)
      Returns the count of all stored objects in this box or the given maxCount, whichever is lower.
      Parameters:
      maxCount - maximum value to count or 0 (zero) to have no maximum limit

    • isEmpty

      public boolean isEmpty()
      Returns true if no objects are in this box.

    • getAll

      public List<T> getAll()
      Returns all stored Objects in this Box.
      Returns:
      since 2.4 the returned list is always mutable (before an empty result list was immutable)

    • contains

      public boolean contains(long id)
      Check if an object with the given ID exists in the database. This is more efficient than a get(long) and comparing against null.
      Returns:
      true if an object with the given ID was found, false otherwise.
      Since:
      2.7

    • put

      public long put(T entity)
      Puts the given object and returns its (new) ID.

      This means that if its @Id property is 0 or null, it is inserted as a new object and assigned the next available ID. For example, if there is an object with ID 1 and another with ID 100, it will be assigned ID 101. The new ID is also set on the given object before this returns.

      If instead the object has an assigned ID set, if an object with the same ID exists it is updated. Otherwise, it is inserted with that ID.

      If the ID was not assigned before an IllegalArgumentException is thrown.

      When the object contains ToOne or ToMany relations, they are created (or updated) to point to the (new) target objects. The target objects themselves are typically not updated or removed. To do so, put or remove them using their Box. However, for convenience, if a target object is new, it will be inserted and assigned an ID in its Box before creating or updating the relation. Also, for ToMany relations based on a Backlink the target objects are updated (to store changes in the linked ToOne or ToMany relation).

      Performance note: if you want to put several objects, consider put(Collection), put(Object[]), BoxStore.runInTx(Runnable), etc. instead.

    • put

      @SafeVarargs public final void put(@Nullable T... entities)
      Puts the given entities in a box using a single transaction.

      See put(Object) for more details.

    • put

      public void put(@Nullable Collection<T> entities)
      Puts the given entities in a box using a single transaction.

      See put(Object) for more details.

      Parameters:
      entities - It is fine to pass null or an empty collection: this case is handled efficiently without overhead.

    • putBatched

      public void putBatched(@Nullable Collection<T> entities, int batchSize)
      Puts the given entities in a box in batches using a separate transaction for each batch.

      See put(Object) for more details.

      Parameters:
      entities - It is fine to pass null or an empty collection: this case is handled efficiently without overhead.
      batchSize - Number of entities that will be put in one transaction. Must be 1 or greater.

    • remove

      public boolean remove(long id)
      Removes (deletes) the object with the given ID.

      If the object is part of a relation, it will be removed from that relation as well.

      Returns:
      true if the object did exist and was removed, otherwise false.

    • remove

      public void remove(@Nullable long... ids)
      Like remove(long), but removes multiple objects in a single transaction.

    • removeByKeys

      @Deprecated public void removeByKeys(@Nullable Collection<Long> ids)
      Deprecated.
      use removeByIds(Collection) instead.

    • removeByIds

      public void removeByIds(@Nullable Collection<Long> ids)
      Like remove(long), but removes multiple objects in a single transaction.

    • remove

      public boolean remove(T object)
      Like remove(long), but obtains the ID from the @Id property of the given object instead.

    • remove

      @SafeVarargs public final void remove(@Nullable T... objects)
      Like remove(Object), but removes multiple objects in a single transaction.

    • remove

      public void remove(@Nullable Collection<T> objects)
      Like remove(Object), but removes multiple objects in a single transaction.

    • removeAll

      public void removeAll()
      Like remove(long), but removes all objects in a single transaction.

    • panicModeRemoveAll

      @Experimental public long panicModeRemoveAll()
      WARNING: this method should generally be avoided as it is not transactional and thus may leave the DB in an inconsistent state. It may be the a last resort option to recover from a full DB. Like removeAll(), it removes all objects, returns the count of objects removed. Logs progress using warning log level.

    • query

      public QueryBuilder<T> query()
      Create a query with no conditions.
      See Also:

    • query

      public QueryBuilder<T> query(QueryCondition<T> queryCondition)
      Applies the given query conditions and returns the builder for further customization, such as result order. Build the condition using the properties from your entity underscore classes.

      An example with a nested OR condition: 

       # Java
 box.query(User_.name.equal("Jane")
         .and(User_.age.less(12)
                 .or(User_.status.equal("child"))));

 # Kotlin
 box.query(User_.name.equal("Jane")
         and (User_.age.less(12)
         or User_.status.equal("child")))
      This method is a shortcut for query().apply(condition).
      See Also:

    • getStore

      public BoxStore getStore()

    • getEntityInfo

      public EntityInfo<T> getEntityInfo()

    • attach

      public void attach(T entity)
      Attaches the given object to this.

      This typically should only be used when manually assigning IDs.

      Parameters:
      entity - The object to attach this to.

    • getEntityClass

      public Class<T> getEntityClass()

    • internalGetBacklinkEntities

      @Internal public List<T> internalGetBacklinkEntities(int entityId, Property<?> relationIdProperty, long key)

    • internalGetRelationEntities

      @Internal public List<T> internalGetRelationEntities(int sourceEntityId, int relationId, long key, boolean backlink)

    • internalGetRelationIds

      @Internal public long[] internalGetRelationIds(int sourceEntityId, int relationId, long key, boolean backlink)

    • getRelationEntities

      public List<T> getRelationEntities(RelationInfo<?,T> relationInfo, long id)
      Given a ToMany relation and the ID of a source entity gets the target entities of the relation from their box, for example orderBox.getRelationEntities(Customer_.orders, customer.getId()).

    • getRelationBacklinkEntities

      public List<T> getRelationBacklinkEntities(RelationInfo<T,?> relationInfo, long id)
      Given a ToMany relation and the ID of a target entity gets all source entities pointing to this target entity, for example customerBox.getRelationEntities(Customer_.orders, order.getId()).

    • getRelationIds

      public long[] getRelationIds(RelationInfo<?,T> relationInfo, long id)
      Like getRelationEntities(RelationInfo, long), but only returns the IDs of the target entities.

    • getRelationBacklinkIds

      public long[] getRelationBacklinkIds(RelationInfo<T,?> relationInfo, long id)
      Like getRelationBacklinkEntities(RelationInfo, long), but only returns the IDs of the source entities.

    • internalCallWithReaderHandle

      @Internal public <RESULT> RESULT internalCallWithReaderHandle(io.objectbox.internal.CallWithHandle<RESULT> task)

    • internalCallWithWriterHandle

      @Internal public <RESULT> RESULT internalCallWithWriterHandle(io.objectbox.internal.CallWithHandle<RESULT> task)

    • getReaderDebugInfo

      public String getReaderDebugInfo()