io.realm

Class RealmResults<E extends RealmModel>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

io.realm.RealmResults<E>

Type Parameters:

E - The class of objects in this list.

All Implemented Interfaces:

OrderedRealmCollection<E>, RealmCollection<E>, java.lang.Iterable<E>, java.util.Collection<E>, java.util.List<E>

public final class RealmResults<E extends RealmModel>
extends java.util.AbstractList<E>
implements OrderedRealmCollection<E>

This class holds all the matches of a RealmQuery for a given Realm. The objects are not copied from the Realm to the RealmResults list, but are just referenced from the RealmResult instead. This saves memory and increases speed.

RealmResults are live views, which means that if it is on an Looper thread, it will automatically update its query results after a transaction has been committed. If on a non-looper thread, BaseRealm.waitForChange() must be called to update the results.

Updates to RealmObjects from a RealmResults list must be done from within a transaction and the modified objects are persisted to the Realm file during the commit of the transaction.

A RealmResults object cannot be passed between different threads.

Notice that a RealmResults is never null not even in the case where it contains no objects. You should always use the size() method to check if a RealmResults is empty or not.

If a RealmResults is built on RealmList through RealmList.where(), it will become empty when the source RealmList gets deleted.

RealmResults can contain more elements than Integer.MAX_VALUE. In that case, you can access only first Integer.MAX_VALUE elements in it.

See Also:

RealmQuery.findAll(), Realm.executeTransaction(Realm.Transaction)

Method Summary

Modifier and Type	Method and Description
boolean	add(E element) Deprecated.
void	add(int index, E element) Deprecated.
boolean	addAll(java.util.Collection<? extends E> collection) Deprecated.
boolean	addAll(int location, java.util.Collection<? extends E> collection) Deprecated.
void	addChangeListener(RealmChangeListener<RealmResults<E>> listener) Adds a change listener to this RealmResults.
<any>	asObservable() Returns an Rx Observable that monitors changes to this RealmResults.
double	average(java.lang.String fieldName) Returns the average of a given field.
void	clear() Deprecated.
boolean	contains(java.lang.Object object) Searches this RealmResults for the specified object.
boolean	deleteAllFromRealm() This deletes all objects in the collection from the underlying Realm as well as from the collection.
boolean	deleteFirstFromRealm() Removes the first object in the list.
void	deleteFromRealm(int location) Deletes the object at the given index from the Realm.
boolean	deleteLastFromRealm() Removes the last object in the list.
RealmResults<E>	distinct(java.lang.String fieldName) Returns a distinct set of objects of a specific class.
RealmResults<E>	distinct(java.lang.String firstFieldName, java.lang.String... remainingFieldNames) Returns a distinct set of objects from a specific class.
RealmResults<E>	distinctAsync(java.lang.String fieldName) Asynchronously returns a distinct set of objects of a specific class.
E	first() Gets the first object from the collection.
E	get(int location) Returns the element at the specified location in this list.
boolean	isLoaded() Returns true if the results are not yet loaded, false if they are still loading.
boolean	isValid() Checks if the collection is still valid to use e.g.
java.util.Iterator<E>	iterator() Returns an iterator for the results of a query.
E	last() Gets the last object from the collection.
java.util.ListIterator<E>	listIterator() Returns a list iterator for the results of a query.
java.util.ListIterator<E>	listIterator(int location) Returns a list iterator on the results of a query.
boolean	load() Makes an asynchronous query blocking.
java.lang.Number	max(java.lang.String fieldName) Finds the maximum value of a field.
java.util.Date	maxDate(java.lang.String fieldName) Finds the maximum date.
java.lang.Number	min(java.lang.String fieldName) Finds the minimum value of a field.
java.util.Date	minDate(java.lang.String fieldName) Finds the minimum date.
E	remove(int index) Deprecated.
boolean	remove(java.lang.Object object) Deprecated.
boolean	removeAll(java.util.Collection<?> collection) Deprecated.
void	removeChangeListener(RealmChangeListener listener) Removes a previously registered listener.
void	removeChangeListeners() Removes all registered listeners.
boolean	retainAll(java.util.Collection<?> collection) Deprecated.
E	set(int location, E object) Deprecated.
int	size() Returns the number of elements in this query result.
RealmResults<E>	sort(java.lang.String fieldName) Sorts a collection based on the provided field in ascending order.
RealmResults<E>	sort(java.lang.String[] fieldNames, Sort[] sortOrders) Sorts a collection based on the provided fields and sort orders.
RealmResults<E>	sort(java.lang.String fieldName, Sort sortOrder) Sorts a collection based on the provided field and sort order.
RealmResults<E>	sort(java.lang.String fieldName1, Sort sortOrder1, java.lang.String fieldName2, Sort sortOrder2) Sorts a collection based on the provided fields and sort orders.
java.lang.Number	sum(java.lang.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 class java.util.AbstractList

equals, hashCode, indexOf, lastIndexOf, subList

Methods inherited from class java.util.AbstractCollection

containsAll, isEmpty, toArray, toArray, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

containsAll, equals, hashCode, indexOf, isEmpty, lastIndexOf, replaceAll, sort, spliterator, subList, toArray, toArray

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

isValid

public boolean isValid()

Checks if the collection is still valid to use e.g. the Realm instance hasn't been closed.

Specified by:

isValid in interface RealmCollection<E extends RealmModel>

Returns:

true if still valid to use, false otherwise.

where

public RealmQuery<E> where()

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

Specified by:

where in interface RealmCollection<E extends RealmModel>

Returns:

a RealmQuery object.

See Also:

RealmQuery

contains

public boolean contains(java.lang.Object object)

Searches this RealmResults for the specified object.

Specified by:

contains in interface RealmCollection<E extends RealmModel>

Specified by:

contains in interface java.util.Collection<E extends RealmModel>

Specified by:

contains in interface java.util.List<E extends RealmModel>

Overrides:

contains in class java.util.AbstractCollection<E extends RealmModel>

Parameters:

object - the object to search for.

Returns:

true if object is an element of this RealmResults, false otherwise

get

public E get(int location)

Returns the element at the specified location in this list.

Specified by:

get in interface java.util.List<E extends RealmModel>

Specified by:

get in class java.util.AbstractList<E extends RealmModel>

Parameters:

location - the index of the element to return.

Returns:

the element at the specified index.

Throws:

java.lang.IndexOutOfBoundsException - if location < 0 || location >= size().

first

public E first()

Gets the first object from the collection.

Specified by:

first in interface OrderedRealmCollection<E extends RealmModel>

Returns:

the first object.

last

public E last()

Gets the last object from the collection.

Specified by:

last in interface OrderedRealmCollection<E extends RealmModel>

Returns:

the last object.

deleteFromRealm

public void deleteFromRealm(int location)

Deletes the object at the given index from the Realm. This also removes it from the collection.

Specified by:

deleteFromRealm in interface OrderedRealmCollection<E extends RealmModel>

Parameters:

location - the array index identifying the object to be removed.

deleteAllFromRealm

public boolean deleteAllFromRealm()

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

Specified by:

deleteAllFromRealm in interface RealmCollection<E extends RealmModel>

Returns:

true if objects was deleted, false otherwise.

iterator

public java.util.Iterator<E> iterator()

Returns an iterator for the results of a query. Any change to Realm while iterating will cause this iterator to throw a ConcurrentModificationException if accessed.

Specified by:

iterator in interface java.lang.Iterable<E extends RealmModel>

Specified by:

iterator in interface java.util.Collection<E extends RealmModel>

Specified by:

iterator in interface java.util.List<E extends RealmModel>

Overrides:

iterator in class java.util.AbstractList<E extends RealmModel>

Returns:

an iterator on the elements of this list.

See Also:

Iterator

listIterator

public java.util.ListIterator<E> listIterator()

Returns a list iterator for the results of a query. Any change to Realm while iterating will cause the iterator to throw a ConcurrentModificationException if accessed.

Specified by:

listIterator in interface java.util.List<E extends RealmModel>

Overrides:

listIterator in class java.util.AbstractList<E extends RealmModel>

Returns:

a ListIterator on the elements of this list.

See Also:

ListIterator

listIterator

public java.util.ListIterator<E> listIterator(int location)

Returns a list iterator on the results of a query. Any change to Realm while iterating will cause the iterator to throw a ConcurrentModificationException if accessed.

Specified by:

listIterator in interface java.util.List<E extends RealmModel>

Overrides:

listIterator in class java.util.AbstractList<E extends RealmModel>

Parameters:

location - the index at which to start the iteration.

Returns:

a ListIterator on the elements of this list.

Throws:

java.lang.IndexOutOfBoundsException - if location < 0 || location > size().

See Also:

ListIterator

sort

public RealmResults<E> sort(java.lang.String fieldName)

Sorts a collection based on the provided field in ascending order.

Specified by:

sort in interface OrderedRealmCollection<E extends RealmModel>

Parameters:

fieldName - the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.

Returns:

a new sorted RealmResults will be created and returned. The original collection stays unchanged.

sort

public RealmResults<E> sort(java.lang.String fieldName,
                            Sort sortOrder)

Sorts a collection based on the provided field and sort order.

Specified by:

sort in interface OrderedRealmCollection<E extends RealmModel>

Parameters:

fieldName - the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.

sortOrder - the direction to sort by.

Returns:

a new sorted RealmResults will be created and returned. The original collection stays unchanged.

sort

public RealmResults<E> sort(java.lang.String[] fieldNames,
                            Sort[] sortOrders)

Sorts a collection based on the provided fields and sort orders.

Specified by:

sort in interface OrderedRealmCollection<E extends RealmModel>

Parameters:

fieldNames - an array of field names to sort by. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.

sortOrders - the directions to sort by.

Returns:

a new sorted RealmResults will be created and returned. The original collection stays unchanged.

sort

public RealmResults<E> sort(java.lang.String fieldName1,
                            Sort sortOrder1,
                            java.lang.String fieldName2,
                            Sort sortOrder2)

Sorts a collection based on the provided fields and sort orders.

Specified by:

sort in interface OrderedRealmCollection<E extends RealmModel>

Parameters:

fieldName1 - first field name. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.

sortOrder1 - sort order for first field.

fieldName2 - second field name. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.

sortOrder2 - sort order for second field.

Returns:

a new sorted RealmResults will be created and returned. The original collection stays unchanged.

size

public int size()

Returns the number of elements in this query result.

Specified by:

size in interface java.util.Collection<E extends RealmModel>

Specified by:

size in interface java.util.List<E extends RealmModel>

Specified by:

size in class java.util.AbstractCollection<E extends RealmModel>

Returns:

the number of elements in this query result.

min

public java.lang.Number min(java.lang.String fieldName)

Finds the minimum value of a field.

Specified by:

min in interface RealmCollection<E extends RealmModel>

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.

minDate

public java.util.Date minDate(java.lang.String fieldName)

Finds the minimum date.

Specified by:

minDate in interface RealmCollection<E extends RealmModel>

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.

max

public java.lang.Number max(java.lang.String fieldName)

Finds the maximum value of a field.

Specified by:

max in interface RealmCollection<E extends RealmModel>

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.

maxDate

public java.util.Date maxDate(java.lang.String fieldName)

Finds the maximum date.

Specified by:

maxDate in interface RealmCollection<E extends RealmModel>

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:

java.lang.IllegalArgumentException - if fieldName is not a Date field.

sum

public java.lang.Number sum(java.lang.String fieldName)

Calculates the sum of a given field.

Specified by:

sum in interface RealmCollection<E extends RealmModel>

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.

average

public double average(java.lang.String fieldName)

Returns the average of a given field.

Specified by:

average in interface RealmCollection<E extends RealmModel>

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.

distinct

public RealmResults<E> distinct(java.lang.String fieldName)

Returns a distinct set of objects of a specific class. If the result is sorted, the first object will be returned in case of multiple occurrences, otherwise it is undefined which object is returned.

Parameters:

fieldName - the field name.

Returns:

a non-null RealmResults containing the distinct objects.

Throws:

java.lang.IllegalArgumentException - if a field is null, does not exist, is an unsupported type, is not indexed, or points to linked fields.

distinctAsync

public RealmResults<E> distinctAsync(java.lang.String fieldName)

Asynchronously returns a distinct set of objects of a specific class. If the result is sorted, the first object will be returned in case of multiple occurrences, otherwise it is undefined which object is returned.

Parameters:

fieldName - the field name.

Returns:

immediately a RealmResults. Users need to register a listener addChangeListener(RealmChangeListener) to be notified when the query completes.

Throws:

java.lang.IllegalArgumentException - if a field is null, does not exist, is an unsupported type, is not indexed, or points to linked fields.

distinct

public RealmResults<E> distinct(java.lang.String firstFieldName,
                                java.lang.String... remainingFieldNames)

Returns a distinct set of objects from a specific class. When multiple distinct fields are given, all unique combinations of values in the fields will be returned. In case of multiple matches, it is undefined which object is returned. Unless the result is sorted, then the first object will be returned.

Parameters:

firstFieldName - first field name to use when finding distinct objects.

remainingFieldNames - remaining field names when determining all unique combinations of field values.

Returns:

a non-null RealmResults containing the distinct objects.

Throws:

java.lang.IllegalArgumentException - if field names is empty or null, does not exist, is an unsupported type, or points to a linked field.

remove

@Deprecated
public E remove(int index)

Deprecated.

Not supported by RealmResults.

Specified by:

remove in interface java.util.List<E extends RealmModel>

Overrides:

remove in class java.util.AbstractList<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException

remove

@Deprecated
public boolean remove(java.lang.Object object)

Deprecated.

Not supported by RealmResults.

Specified by:

remove in interface java.util.Collection<E extends RealmModel>

Specified by:

remove in interface java.util.List<E extends RealmModel>

Overrides:

remove in class java.util.AbstractCollection<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException

removeAll

@Deprecated
public boolean removeAll(java.util.Collection<?> collection)

Deprecated.

Not supported by RealmResults.

Specified by:

removeAll in interface java.util.Collection<E extends RealmModel>

Specified by:

removeAll in interface java.util.List<E extends RealmModel>

Overrides:

removeAll in class java.util.AbstractCollection<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException

set

@Deprecated
public E set(int location,
                         E object)

Deprecated.

Not supported by RealmResults.

Specified by:

set in interface java.util.List<E extends RealmModel>

Overrides:

set in class java.util.AbstractList<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException

retainAll

@Deprecated
public boolean retainAll(java.util.Collection<?> collection)

Deprecated.

Not supported by RealmResults.

Specified by:

retainAll in interface java.util.Collection<E extends RealmModel>

Specified by:

retainAll in interface java.util.List<E extends RealmModel>

Overrides:

retainAll in class java.util.AbstractCollection<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException

deleteLastFromRealm

public boolean deleteLastFromRealm()

Removes the last object in the list. This also deletes the object from the underlying Realm.

Specified by:

deleteLastFromRealm in interface OrderedRealmCollection<E extends RealmModel>

Returns:

true if an object was deleted, false otherwise.

Throws:

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

deleteFirstFromRealm

public boolean deleteFirstFromRealm()

Removes the first object in the list. This also deletes the object from the underlying Realm.

Specified by:

deleteFirstFromRealm in interface OrderedRealmCollection<E extends RealmModel>

Returns:

true if an object was deleted, false otherwise.

Throws:

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

clear

@Deprecated
public void clear()

Deprecated.

Not supported by RealmResults.

Specified by:

clear in interface java.util.Collection<E extends RealmModel>

Specified by:

clear in interface java.util.List<E extends RealmModel>

Overrides:

clear in class java.util.AbstractList<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException - always.

add

@Deprecated
public boolean add(E element)

Deprecated.

Not supported by RealmResults.

Specified by:

add in interface java.util.Collection<E extends RealmModel>

Specified by:

add in interface java.util.List<E extends RealmModel>

Overrides:

add in class java.util.AbstractList<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException - always.

add

@Deprecated
public void add(int index,
                            E element)

Deprecated.

Not supported by RealmResults.

Specified by:

add in interface java.util.List<E extends RealmModel>

Overrides:

add in class java.util.AbstractList<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException - always.

addAll

@Deprecated
public boolean addAll(int location,
                                  java.util.Collection<? extends E> collection)

Deprecated.

Not supported by RealmResults.

Specified by:

addAll in interface java.util.List<E extends RealmModel>

Overrides:

addAll in class java.util.AbstractList<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException - always.

addAll

@Deprecated
public boolean addAll(java.util.Collection<? extends E> collection)

Deprecated.

Not supported by RealmResults.

Specified by:

addAll in interface java.util.Collection<E extends RealmModel>

Specified by:

addAll in interface java.util.List<E extends RealmModel>

Overrides:

addAll in class java.util.AbstractCollection<E extends RealmModel>

Throws:

java.lang.UnsupportedOperationException - always.

isLoaded

public boolean isLoaded()

Returns true if the results are not yet loaded, false if they are still loading. Synchronous query methods like findAll() will always return true, while asynchronous query methods like findAllAsync() will return false until the results are available. This will return true if called for an unmanaged object (created outside of Realm).

Specified by:

isLoaded in interface RealmCollection<E extends RealmModel>

Returns:

true if the query has completed and the data is available false if the query is still running.

load

public boolean load()

Makes an asynchronous query blocking. This will also trigger any registered RealmChangeListener when the query completes.

Specified by:

load in interface RealmCollection<E extends RealmModel>

Returns:

true if it successfully completed the query, false otherwise. true will always be returned for unmanaged objects.

addChangeListener

public void addChangeListener(RealmChangeListener<RealmResults<E>> listener)

Adds a change listener to this RealmResults.

Parameters:

listener - the change listener to be notified.

Throws:

java.lang.IllegalArgumentException - if the change listener is null.

java.lang.IllegalStateException - if you try to add a listener from a non-Looper Thread.

removeChangeListener

public void removeChangeListener(RealmChangeListener listener)

Removes a previously registered listener.

Parameters:

listener - the instance to be removed.

Throws:

java.lang.IllegalArgumentException - if the change listener is null.

java.lang.IllegalStateException - if you try to remove a listener from a non-Looper Thread.

removeChangeListeners

public void removeChangeListeners()

Removes all registered listeners.

asObservable

public <any> asObservable()

Returns an Rx Observable that monitors changes to this RealmResults. It will emit the current RealmResults when subscribed to. RealmResults will continually be emitted as the RealmResults are updated - onComplete will never be called. If you would like the asObservable() to stop emitting items you can instruct RxJava to only emit only the first item by using the first() operator:

 
 realm.where(Foo.class).findAllAsync().asObservable()
      .filter(results -> results.isLoaded())
      .first()
      .subscribe( ... ) // You only get the results once
 
 

Note that when the Realm is accessed from threads other than where it was created, IllegalStateException will be thrown. Care should be taken when using different schedulers with subscribeOn() and observeOn(). Consider using Realm.where().find*Async() instead.

Returns:

RxJava Observable that only calls onNext. It will never call onComplete or OnError.

Throws:

java.lang.UnsupportedOperationException - if the required RxJava framework is not on the classpath or the corresponding Realm instance doesn't support RxJava.

See Also:

RxJava and Realm