Package io.objectbox.relation

Class ToMany<TARGET>

  • Type Parameters:
    TARGET - target object type (@Entity class).
    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 to-many relation of an entity that references multiple objects of a ToMany entity.

    Example: 

    {@code
 // Java
    See Also:
    Serialized Form

    • Field Detail

      • ONE

        private static final java.lang.Integer ONE

      • entity

        private final java.lang.Object entity

      • listFactory

        private volatile ListFactory listFactory

      • entities

        private java.util.List<TARGET> entities

      • entityCounts

        private java.util.Map<TARGET,​java.lang.Integer> entityCounts
        Counts of all entities in the list (entities).

      • entitiesAdded

        private volatile java.util.Map<TARGET,​java.lang.Boolean> entitiesAdded
        Entities added since last put/sync. Map is used as a set (value is always Boolean.TRUE).

      • entitiesRemoved

        private java.util.Map<TARGET,​java.lang.Boolean> entitiesRemoved
        Entities removed since last put/sync. Map is used as a set (value is always Boolean.TRUE).

      • entitiesToPut

        java.util.List<TARGET> entitiesToPut

      • entitiesToRemoveFromDb

        java.util.List<TARGET> entitiesToRemoveFromDb

      • boxStore

        private transient BoxStore boxStore

      • entityBox

        private transient Box<java.lang.Object> entityBox

      • targetBox

        private transient volatile Box<TARGET> targetBox

      • removeFromTargetBox

        private transient boolean removeFromTargetBox

      • comparator

        private transient java.util.Comparator<TARGET> comparator

    • 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.

      • ensureBoxes

        private void ensureBoxes()

      • ensureEntitiesWithTrackingLists

        private void ensureEntitiesWithTrackingLists()

      • ensureEntities

        private void ensureEntities()

      • add

        public boolean add​(TARGET object)
        Prepares to add the given target object to this relation.

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

        Specified by:
        add in interface java.util.Collection<TARGET>
        Specified by:
        add in interface java.util.List<TARGET>

      • trackAdd

        private void trackAdd​(TARGET object)
        Must be called from a synchronized method

      • trackAdd

        private void trackAdd​(java.util.Collection<? extends TARGET> objects)
        Must be called from a synchronized method

      • trackRemove

        private void trackRemove​(TARGET object)
        Must be called from a synchronized method

      • 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)
        Gets the target object at the given index.

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

        Specified by:
        get in interface java.util.List<TARGET>

      • 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)
        Like remove(Object), but using the location of the target object.
        Specified by:
        remove in interface java.util.List<TARGET>

      • remove

        public boolean remove​(java.lang.Object object)
        Prepares to remove the target object from this relation.

        To apply changes, call applyChangesToDb() or put the object with the ToMany. For important details, see the notes about relations of Box.put(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)
        Like remove(Object), but using just the ID of the target object.

      • 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 object ID). This will be the order when you get the objects fresh (e.g. initially or after calling reset()). Note that non persisted objects (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 objects) 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 ID.

      • indexOfId

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

      • hasPendingDbChanges

        public boolean hasPendingDbChanges()
        Returns true if there are pending changes for the DB. Changes will be automatically persisted once the object with the ToMany 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 object is put (so we have its ID). Prepares data for internalApplyToDb(Cursor, Cursor)

      • prepareToManyBacklinkEntitiesForDb

        private boolean prepareToManyBacklinkEntitiesForDb​(long entityId,
                                                   IdGetter<TARGET> idGetter,
                                                   @Nullable
                                                   java.util.Map<TARGET,​java.lang.Boolean> setAdded,
                                                   @Nullable
                                                   java.util.Map<TARGET,​java.lang.Boolean> setRemoved)
        Modifies the linked ToMany relation of added or removed target objects and schedules put by internalApplyToDb(io.objectbox.Cursor<?>, io.objectbox.Cursor<TARGET>) for them.

        If setRemoveFromTargetBox(boolean) is true, removed target objects are scheduled for removal instead of just updating their ToMany relation.

        If target objects are new, schedules a put if they were added, but never if they were removed from this relation.

        Returns:
        Whether there are any target objects to put or remove.

      • removeStandaloneRelations

        private void removeStandaloneRelations​(Cursor<?> cursor,
                                       long sourceEntityId,
                                       java.util.List<TARGET> removed,
                                       IdGetter<TARGET> targetIdGetter)
        The list of removed entities may contain non-persisted entities, which will be ignored (removed from the list).

      • addStandaloneRelations

        private void addStandaloneRelations​(Cursor<?> cursor,
                                    long sourceEntityId,
                                    TARGET[] added,
                                    IdGetter<TARGET> targetIdGetter)
        The target array may not contain non-persisted entities.

      • getEntity

        java.lang.Object getEntity()
        For tests