io.realm

Interface RealmCollection<E>

Type Parameters:

E - type of RealmObject stored in the collection.

All Superinterfaces:

Collection<E>, Iterable<E>

All Known Subinterfaces:

OrderedRealmCollection<E>

All Known Implementing Classes:

OrderedRealmCollectionSnapshot, RealmList, RealmResults

public interface RealmCollection<E>
extends Collection<E>

RealmCollection is the root of the collection hierarchy that Realm supports. It defines operations on data collections and the behavior that they will have in all implementations of RealmCollections.

Realm collections are "live" views to the underlying data. This means that they automatically will be kept up to date. As a consequence, using methods like Collections.unmodifiableCollection(Collection) will not prevent a collection from being modified.

Method Summary

Modifier and Type	Method and Description
double	average(String fieldName) Returns the average of a given field.
boolean	contains(Object object) Tests whether this Collection contains the specified object.
boolean	deleteAllFromRealm() This deletes all objects in the collection from the underlying Realm as well as from the collection.
boolean	isLoaded() Checks if a collection has finished loading its data yet.
boolean	isManaged() Checks if the collection is managed by Realm.
boolean	isValid() Checks if the collection is still valid to use, i.e., the Realm instance hasn't been closed.
boolean	load() Blocks the collection until all data are available.
Number	max(String fieldName) Finds the maximum value of a field.
Date	maxDate(String fieldName) Finds the maximum date.
Number	min(String fieldName) Finds the minimum value of a field.
Date	minDate(String fieldName) Finds the minimum date.
Number	sum(String fieldName) Calculates the sum of a given field.
RealmQuery<E>	where() Returns a RealmQuery, which can be used to query for specific objects from this collection.

Methods inherited from interface java.util.Collection

add, addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, remove, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

where

RealmQuery<E> where()

Returns a RealmQuery, which can be used to query for specific objects from this collection.

Returns:

a RealmQuery object.

Throws:

IllegalStateException - if the Realm instance has been closed or queries are not otherwise available.

See Also:

RealmQuery

min

Number min(String fieldName)

Finds the minimum value of a field.

Parameters:

fieldName - the field to look for a minimum on. Only number fields are supported.

Returns:

if no objects exist or they all have null as the value for the given field, null will be returned. Otherwise the minimum value is returned. When determining the minimum value, objects with null values are ignored.

Throws:

IllegalArgumentException - if the field is not a number type.

IllegalStateException - if the Realm has been closed or called from an incorrect thread.

max

Number max(String fieldName)

Finds the maximum value of a field.

Parameters:

fieldName - the field to look for a maximum on. Only number fields are supported.

Returns:

if no objects exist or they all have null as the value for the given field, null will be returned. Otherwise the maximum value is returned. When determining the maximum value, objects with null values are ignored.

Throws:

IllegalArgumentException - if the field is not a number type.

IllegalStateException - if the Realm has been closed or called from an incorrect thread.

sum

Number sum(String fieldName)

Calculates the sum of a given field.

Parameters:

fieldName - the field to sum. Only number fields are supported.

Returns:

the sum. If no objects exist or they all have null as the value for the given field, 0 will be returned. When computing the sum, objects with null values are ignored.

Throws:

IllegalArgumentException - if the field is not a number type.

IllegalStateException - if the Realm has been closed or called from an incorrect thread.

average

double average(String fieldName)

Returns the average of a given field.

Parameters:

fieldName - the field to calculate average on. Only number fields are supported.

Returns:

the average for the given field amongst objects in query results. This will be of type double for all types of number fields. If no objects exist or they all have null as the value for the given field, 0 will be returned. When computing the average, objects with null values are ignored.

Throws:

IllegalArgumentException - if the field is not a number type.

IllegalStateException - if the Realm has been closed or called from an incorrect thread.

maxDate

Date maxDate(String fieldName)

Finds the maximum date.

Parameters:

fieldName - the field to look for the maximum date. If fieldName is not of Date type, an exception is thrown.

Returns:

if no objects exist or they all have null as the value for the given date field, null will be returned. Otherwise the maximum date is returned. When determining the maximum date, objects with null values are ignored.

Throws:

IllegalArgumentException - if fieldName is not a Date field.

IllegalStateException - if the Realm has been closed or called from an incorrect thread.

minDate

Date minDate(String fieldName)

Finds the minimum date.

Parameters:

fieldName - the field to look for the minimum date. If fieldName is not of Date type, an exception is thrown.

Returns:

if no objects exist or they all have null as the value for the given date field, null will be returned. Otherwise the minimum date is returned. When determining the minimum date, objects with null values are ignored.

Throws:

IllegalArgumentException - if fieldName is not a Date field.

IllegalStateException - if the Realm has been closed or called from an incorrect thread.

deleteAllFromRealm

boolean deleteAllFromRealm()

This deletes all objects in the collection from the underlying Realm as well as from the collection.

Returns:

true if objects was deleted, false otherwise.

Throws:

IllegalStateException - if the corresponding Realm is closed or in an incorrect thread.

IllegalStateException - if the Realm has been closed or called from an incorrect thread.

isLoaded

boolean isLoaded()

Checks if a collection has finished loading its data yet.

Returns:

true if data has been loaded and is available, false if data is still being loaded.

load

boolean load()

Blocks the collection until all data are available.

Returns:

true if the data could be successfully loaded, false otherwise.

isValid

boolean isValid()

Checks if the collection is still valid to use, i.e., the Realm instance hasn't been closed. It will always return true for an unmanaged collection.

Returns:

true if it is still valid to use or an unmanaged collection, false otherwise.

isManaged

boolean isManaged()

Checks if the collection is managed by Realm. A managed collection is just a wrapper around the data in the underlying Realm file. On Looper threads, a managed collection will be live-updated so it always points to the latest data. Managed collections are thread confined so that they cannot be accessed from other threads than the one that created them.

If this method returns false, the collection is unmanaged. An unmanaged collection is just a normal java collection, so it will not be live updated.

Returns:

true if this is a managed RealmCollection, false otherwise.

contains

boolean contains(Object object)

Tests whether this Collection contains the specified object. Returns true if and only if at least one element elem in this Collection meets following requirement: (object==null ? elem==null : object.equals(elem)).

Specified by:

contains in interface Collection<E>

Parameters:

object - the object to search for.

Returns:

true if object is an element of this Collection, false otherwise.

Throws:

NullPointerException - if the object to look for is null and this Collection doesn't support null elements.