Class ToMany<TARGET>

  • Type Parameters:
    TARGET - Object type (entity).
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<TARGET>, java.util.Collection<TARGET>, java.util.List<TARGET>

    public class ToMany<TARGET>
    extends java.lang.Object
    implements java.util.List<TARGET>, java.io.Serializable
    A lazily loaded List of target objects representing a to-many relation, a unidirectional link from a "source" entity to multiple objects of a "target" entity.

    It tracks changes (adds and removes) that can be later applied (persisted) to the database. This happens either when the object that contains this relation is put or using applyChangesToDb(). For some important details about applying changes, see the notes about relations of Box.put(Object).

    The objects are loaded lazily on first access of this list, and then cached. The database query runs on the calling thread, so avoid accessing this from a UI or main thread. Subsequent calls to any method, like size(), do not query the database, even if the relation was changed elsewhere. To get the latest data Box.get(long) the source object again or use reset() before accessing the list again.

    It is possible to preload the list when running a query using QueryBuilder.eager(io.objectbox.relation.RelationInfo, io.objectbox.relation.RelationInfo...).

    ToMany is thread-safe by default (may not be the case if setListFactory(ListFactory) is used).

    See Also:
    Serialized Form
    • Constructor Summary

      Constructors 
      Constructor Description
      ToMany​(java.lang.Object sourceEntity, RelationInfo<?,​TARGET> relationInfo)  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(int location, TARGET object)
      See add(Object) for general comments.
      boolean add​(TARGET object)
      Adds the given entity to the list and tracks the addition so it can be later applied to the database (e.g.
      boolean addAll​(int index, java.util.Collection<? extends TARGET> objects)
      See add(Object) for general comments.
      boolean addAll​(java.util.Collection<? extends TARGET> objects)
      See add(Object) for general comments.
      void applyChangesToDb()
      Saves changes (added and removed entities) made to this relation to the database.
      void clear()  
      boolean contains​(java.lang.Object object)  
      boolean containsAll​(java.util.Collection<?> collection)  
      TARGET get​(int location)  
      int getAddCount()  
      TARGET getById​(long id)
      Gets an object by its entity ID.
      ListFactory getListFactory()  
      int getRemoveCount()  
      boolean hasA​(QueryFilter<TARGET> filter)
      Returns true if at least one of the entities matches the given filter.
      boolean hasAll​(QueryFilter<TARGET> filter)
      Returns true if all of the entities match the given filter.
      boolean hasPendingDbChanges()
      Returns true if there are pending changes for the DB.
      int indexOf​(java.lang.Object object)  
      int indexOfId​(long id)
      Gets the index of the object with the given entity ID.
      void internalApplyToDb​(io.objectbox.Cursor<?> sourceCursor, io.objectbox.Cursor<TARGET> targetCursor)
      For internal use only; do not use in your app.
      boolean internalCheckApplyToDbRequired()
      For internal use only; do not use in your app.
      boolean isEmpty()  
      boolean isResolved()  
      java.util.Iterator<TARGET> iterator()  
      int lastIndexOf​(java.lang.Object object)  
      java.util.ListIterator<TARGET> listIterator()  
      java.util.ListIterator<TARGET> listIterator​(int location)
      The returned iterator does not track any potential calls to Iterator.remove().
      TARGET remove​(int location)  
      boolean remove​(java.lang.Object object)  
      boolean removeAll​(java.util.Collection<?> objects)  
      TARGET removeById​(long id)
      Removes an object by its entity ID.
      void reset()
      Resets the already loaded (cached) objects of this list, so they will be re-loaded when accessing this list again.
      boolean retainAll​(java.util.Collection<?> objects)  
      TARGET set​(int location, TARGET object)  
      void setComparator​(java.util.Comparator<TARGET> comparator)
      Set an comparator to define the order of entities.
      void setListFactory​(ListFactory listFactory)
      Currently only used for non-persisted entities (id == 0).
      void setRemoveFromTargetBox​(boolean removeFromTargetBox)
      On put, this also deletes removed entities from the target Box.
      int size()  
      void sortById()
      Sorts the list by the "natural" ObjectBox order for to-many list (by entity ID).
      java.util.List<TARGET> subList​(int start, int end)
      The returned sub list does not do any change tracking.
      java.lang.Object[] toArray()  
      <T> T[] toArray​(T[] array)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface java.util.Collection

        parallelStream, removeIf, stream, toArray
      • Methods inherited from interface java.lang.Iterable

        forEach
      • Methods inherited from interface java.util.List

        equals, hashCode, replaceAll, sort, spliterator
    • Constructor Detail

      • ToMany

        public ToMany​(java.lang.Object sourceEntity,
                      RelationInfo<?,​TARGET> relationInfo)
    • Method Detail

      • setListFactory

        @Experimental
        public void setListFactory​(ListFactory listFactory)
        Currently only used for non-persisted entities (id == 0).
      • setComparator

        @Experimental
        public void setComparator​(java.util.Comparator<TARGET> comparator)
        Set an comparator to define the order of entities.
      • setRemoveFromTargetBox

        @Experimental
        public void setRemoveFromTargetBox​(boolean removeFromTargetBox)
        On put, this also deletes removed entities from the target Box. Note: removed target entities won't cascade the delete.
      • add

        public boolean add​(TARGET object)
        Adds the given entity to the list and tracks the addition so it can be later applied to the database (e.g. via Box.put(Object) of the entity owning the ToMany, or via applyChangesToDb()). Note that the given entity will remain unchanged at this point (e.g. to-ones are not updated).
        Specified by:
        add in interface java.util.Collection<TARGET>
        Specified by:
        add in interface java.util.List<TARGET>
      • add

        public void add​(int location,
                        TARGET object)
        See add(Object) for general comments.
        Specified by:
        add in interface java.util.List<TARGET>
      • addAll

        public boolean addAll​(java.util.Collection<? extends TARGET> objects)
        See add(Object) for general comments.
        Specified by:
        addAll in interface java.util.Collection<TARGET>
        Specified by:
        addAll in interface java.util.List<TARGET>
      • addAll

        public boolean addAll​(int index,
                              java.util.Collection<? extends TARGET> objects)
        See add(Object) for general comments.
        Specified by:
        addAll in interface java.util.List<TARGET>
      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Collection<TARGET>
        Specified by:
        clear in interface java.util.List<TARGET>
      • contains

        public boolean contains​(java.lang.Object object)
        Specified by:
        contains in interface java.util.Collection<TARGET>
        Specified by:
        contains in interface java.util.List<TARGET>
      • containsAll

        public boolean containsAll​(java.util.Collection<?> collection)
        Specified by:
        containsAll in interface java.util.Collection<TARGET>
        Specified by:
        containsAll in interface java.util.List<TARGET>
      • get

        public TARGET get​(int location)
        Specified by:
        get in interface java.util.List<TARGET>
        Returns:
        An object for the given ID, or null if the object was already removed from its box (and was not cached before).
      • indexOf

        public int indexOf​(java.lang.Object object)
        Specified by:
        indexOf in interface java.util.List<TARGET>
      • isEmpty

        public boolean isEmpty()
        Specified by:
        isEmpty in interface java.util.Collection<TARGET>
        Specified by:
        isEmpty in interface java.util.List<TARGET>
      • iterator

        @Nonnull
        public java.util.Iterator<TARGET> iterator()
        Specified by:
        iterator in interface java.util.Collection<TARGET>
        Specified by:
        iterator in interface java.lang.Iterable<TARGET>
        Specified by:
        iterator in interface java.util.List<TARGET>
      • lastIndexOf

        public int lastIndexOf​(java.lang.Object object)
        Specified by:
        lastIndexOf in interface java.util.List<TARGET>
      • listIterator

        @Nonnull
        public java.util.ListIterator<TARGET> listIterator()
        Specified by:
        listIterator in interface java.util.List<TARGET>
      • listIterator

        @Nonnull
        public java.util.ListIterator<TARGET> listIterator​(int location)
        The returned iterator does not track any potential calls to Iterator.remove(). Thus these removes will NOT be synced to the target Box.
        Specified by:
        listIterator in interface java.util.List<TARGET>
      • remove

        public TARGET remove​(int location)
        Specified by:
        remove in interface java.util.List<TARGET>
      • remove

        public boolean remove​(java.lang.Object object)
        Specified by:
        remove in interface java.util.Collection<TARGET>
        Specified by:
        remove in interface java.util.List<TARGET>
      • removeById

        public TARGET removeById​(long id)
        Removes an object by its entity ID.
      • removeAll

        public boolean removeAll​(java.util.Collection<?> objects)
        Specified by:
        removeAll in interface java.util.Collection<TARGET>
        Specified by:
        removeAll in interface java.util.List<TARGET>
      • retainAll

        public boolean retainAll​(java.util.Collection<?> objects)
        Specified by:
        retainAll in interface java.util.Collection<TARGET>
        Specified by:
        retainAll in interface java.util.List<TARGET>
      • set

        public TARGET set​(int location,
                          TARGET object)
        Specified by:
        set in interface java.util.List<TARGET>
      • size

        public int size()
        Specified by:
        size in interface java.util.Collection<TARGET>
        Specified by:
        size in interface java.util.List<TARGET>
      • subList

        @Nonnull
        public java.util.List<TARGET> subList​(int start,
                                              int end)
        The returned sub list does not do any change tracking. Thus any modifications to the sublist won't be synced to the target Box.
        Specified by:
        subList in interface java.util.List<TARGET>
      • toArray

        @Nonnull
        public java.lang.Object[] toArray()
        Specified by:
        toArray in interface java.util.Collection<TARGET>
        Specified by:
        toArray in interface java.util.List<TARGET>
      • toArray

        @Nonnull
        public <T> T[] toArray​(T[] array)
        Specified by:
        toArray in interface java.util.Collection<TARGET>
        Specified by:
        toArray in interface java.util.List<TARGET>
      • reset

        public void reset()
        Resets the already loaded (cached) objects of this list, so they will be re-loaded when accessing this list again.

        Use this to sync with changes to this relation or target objects made outside of this ToMany.

      • isResolved

        public boolean isResolved()
      • getAddCount

        public int getAddCount()
      • getRemoveCount

        public int getRemoveCount()
      • sortById

        public void sortById()
        Sorts the list by the "natural" ObjectBox order for to-many list (by entity ID). This will be the order when you get the entities fresh (e.g. initially or after calling reset()). Note that non persisted entities (ID is zero) will be put to the end as they are still to get an ID.
      • applyChangesToDb

        public void applyChangesToDb()
        Saves changes (added and removed entities) made to this relation to the database. For some important details, see the notes about relations of Box.put(Object).

        Note that this is called already when the object that contains this ToMany is put. However, if only this ToMany has changed, it is more efficient to just use this method.

        Throws:
        java.lang.IllegalStateException - If the object that contains this ToMany has no ID assigned (it must have been put before).
      • getById

        @Beta
        public TARGET getById​(long id)
        Gets an object by its entity ID.
      • indexOfId

        @Beta
        public int indexOfId​(long id)
        Gets the index of the object with the given entity ID.
      • hasPendingDbChanges

        public boolean hasPendingDbChanges()
        Returns true if there are pending changes for the DB. Changes will be automatically persisted once the owning entity is put, or an explicit call to applyChangesToDb() is made.
      • internalCheckApplyToDbRequired

        @Internal
        public boolean internalCheckApplyToDbRequired()
        For internal use only; do not use in your app. Called after relation source entity is put (so we have its ID). Prepares data for internalApplyToDb(Cursor, Cursor)
      • internalApplyToDb

        @Internal
        public void internalApplyToDb​(io.objectbox.Cursor<?> sourceCursor,
                                      io.objectbox.Cursor<TARGET> targetCursor)
        For internal use only; do not use in your app. Convention: internalCheckApplyToDbRequired() must be called before this call as it prepares .