io.objectbox.relation

Class ToMany<TARGET>

java.lang.Object

io.objectbox.relation.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 List representing a to-many relation. It tracks changes (adds and removes) that can be later applied (persisted) to the database. This happens either on Box.put(Object) of the source entity of this relation or using applyChangesToDb().

If this relation is a backlink from a ToOne relation, a DB sync will also update ToOne objects (but not vice versa).

ToMany is thread-safe by default (only if the default CopyOnWriteArrayList is used).

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ToMany(java.lang.Object sourceEntity, RelationInfo<?,TARGET> relationInfo)

Method Summary

Modifier and Type	Method and 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(java.util.Collection<? extends TARGET> objects) See add(Object) for general comments.
boolean	addAll(int index, java.util.Collection<? extends TARGET> objects) See add(Object) for general comments.
void	applyChangesToDb() Applies (persists) tracked changes (added and removed entities) to the target box and/or updates standalone relations.
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 entities so they will be re-loaded on their next access.
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.List

equals, hashCode, replaceAll, sort, spliterator

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

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.

getListFactory

public ListFactory getListFactory()

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.lang.Iterable<TARGET>

Specified by:

iterator in interface java.util.Collection<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 entities so they will be re-loaded on their next access. This allows to sync with non-tracked changes (outside of this ToMany object).

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

Applies (persists) tracked changes (added and removed entities) to the target box and/or updates standalone relations. Note that this is done automatically when you put the source entity of this to-many relation. However, if only this to-many relation has changed, it is more efficient to call this method.

Throws:

java.lang.IllegalStateException - If the source entity of this to-many relation was not previously persisted

hasA

@Beta
public boolean hasA(QueryFilter<TARGET> filter)

Returns true if at least one of the entities matches the given filter.

For use with QueryBuilder.filter(QueryFilter) inside a QueryFilter to check to-many relation entities.

hasAll

@Beta
public boolean hasAll(QueryFilter<TARGET> filter)

Returns true if all of the entities match the given filter. Returns false if the list is empty.

For use with QueryBuilder.filter(QueryFilter) inside a QueryFilter to check to-many relation entities.

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 .