Package io.objectbox

Class Box<T>


  • @Beta
    @ThreadSafe
    public class Box<T>
    extends java.lang.Object
    A box to store objects of a particular class.

    Thread-safe.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void attach​(T entity)  
      void closeThreadResources()
      Like BoxStore.closeThreadResources(), but limited to only this Box.
      long count()
      Returns the count of all stored objects in this box.
      long count​(long maxCount)
      Returns the count of all stored objects in this box or the given maxCount, whichever is lower.
      T get​(long id)
      Get the stored object for the given ID.
      java.util.List<T> get​(long[] ids)
      Get the stored objects for the given IDs.
      java.util.List<T> get​(java.lang.Iterable<java.lang.Long> ids)
      Get the stored objects for the given IDs.
      java.util.List<T> getAll()
      Returns all stored Objects in this Box.
      java.lang.Class<T> getEntityClass()  
      EntityInfo getEntityInfo()  
      long getId​(T entity)  
      java.util.Map<java.lang.Long,​T> getMap​(java.lang.Iterable<java.lang.Long> ids)
      Get the stored objects for the given IDs as a Map with IDs as keys, and entities as values.
      java.lang.String getReaderDebugInfo()  
      java.util.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()).
      long[] getRelationBacklinkIds​(RelationInfo<T,​?> relationInfo, long id)
      Like getRelationBacklinkEntities(RelationInfo, long), but only returns the IDs of the source entities.
      java.util.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()).
      long[] getRelationIds​(RelationInfo<?,​T> relationInfo, long id)
      Like getRelationEntities(RelationInfo, long), but only returns the IDs of the target entities.
      BoxStore getStore()  
      <RESULT> RESULT internalCallWithReaderHandle​(io.objectbox.internal.CallWithHandle<RESULT> task)  
      <RESULT> RESULT internalCallWithWriterHandle​(io.objectbox.internal.CallWithHandle<RESULT> task)  
      java.util.List<T> internalGetBacklinkEntities​(int entityId, Property relationIdProperty, long key)  
      java.util.List<T> internalGetRelationEntities​(int sourceEntityId, int relationId, long key, boolean backlink)  
      long[] internalGetRelationIds​(int sourceEntityId, int relationId, long key, boolean backlink)  
      boolean isEmpty()
      Returns true if no objects are in this box.
      long panicModeRemoveAll()
      WARNING: this method should generally be avoided as it is not transactional and thus may leave the DB in an inconsistent state.
      void put​(java.util.Collection<T> entities)
      Puts the given entities in a box using a single transaction.
      long put​(T entity)
      Puts the given object in the box (aka persisting it).
      void put​(T... entities)
      Puts the given entities in a box using a single transaction.
      void putBatched​(java.util.Collection<T> entities, int batchSize)
      Puts the given entities in a box in batches using a separate transaction for each batch.
      QueryBuilder<T> query()
      Returns a builder to create queries for Object matching supplied criteria.
      boolean remove​(long id)
      Removes (deletes) the Object by its ID.
      void remove​(long... ids)
      Removes (deletes) Objects by their ID in a single transaction.
      void remove​(java.util.Collection<T> objects)
      Removes (deletes) the given Objects in a single transaction.
      boolean remove​(T object)
      Removes (deletes) the given Object.
      void remove​(T... objects)
      Removes (deletes) the given Objects in a single transaction.
      void removeAll()
      Removes (deletes) ALL Objects in a single transaction.
      void removeByIds​(java.util.Collection<java.lang.Long> ids)
      Due to type erasure collision, we cannot simply use "remove" as a method name here.
      void removeByKeys​(java.util.Collection<java.lang.Long> ids)
      Deprecated.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • 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 java.util.List<T> get​(java.lang.Iterable<java.lang.Long> ids)
        Get the stored objects for the given IDs.
        Returns:
        null if not found
      • get

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

        public java.util.Map<java.lang.Long,​T> getMap​(java.lang.Iterable<java.lang.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 java.util.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)
      • 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

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

        public void put​(@Nullable
                        java.util.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
                               java.util.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
                                 java.util.Collection<java.lang.Long> ids)
        Deprecated.
      • removeByIds

        public void removeByIds​(@Nullable
                                java.util.Collection<java.lang.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

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

        public void remove​(@Nullable
                           java.util.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.
      • getEntityInfo

        public EntityInfo getEntityInfo()
      • attach

        @Beta
        public void attach​(T entity)
      • getEntityClass

        public java.lang.Class<T> getEntityClass()
      • internalGetBacklinkEntities

        @Internal
        public java.util.List<T> internalGetBacklinkEntities​(int entityId,
                                                             Property relationIdProperty,
                                                             long key)
      • internalGetRelationEntities

        @Internal
        public java.util.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 java.util.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 java.util.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()).
      • 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 java.lang.String getReaderDebugInfo()