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 in the box (aka persisting it). If this is a new entity (its ID property is 0), a new ID will be assigned to the entity (and returned). If the entity was already put in the box before, it will be overwritten.

      Performance note: if you want to put several entities, 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.

    • put

      public void put(@Nullable Collection<T> entities)
      Puts the given entities in a box using a single transaction.
      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.
      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 by its ID.
      Returns:
      true if an entity was actually removed (false if no entity exists with the given ID)

    • remove

      public void remove(@Nullable long... ids)
      Removes (deletes) Objects by their ID 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)
      Due to type erasure collision, we cannot simply use "remove" as a method name here.

    • remove

      public boolean remove(T object)
      Removes (deletes) the given Object.
      Returns:
      true if an entity was actually removed (false if no entity exists with the given ID)

    • remove

      @SafeVarargs public final void remove(@Nullable T... objects)
      Removes (deletes) the given Objects in a single transaction.

    • remove

      public void remove(@Nullable Collection<T> objects)
      Removes (deletes) the given Objects in a single transaction.

    • removeAll

      public void removeAll()
      Removes (deletes) 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()
      Returns a builder to create queries for Object matching supplied criteria.

    • query

      @Experimental public QueryBuilder<T> query(QueryCondition<T> queryCondition)
      Experimental. This API might change or be removed in the future based on user feedback.

      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

      @Beta public void attach(T entity)

    • 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()