io.realm

Class RealmResults<E extends RealmObject>

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:

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

public final class RealmResults<E extends RealmObject>
extends java.util.AbstractList<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.refresh() 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.

See Also:

RealmQuery.findAll(), Realm.allObjects(Class), BaseRealm.beginTransaction()

Method Summary

Modifier and Type	Method and Description
boolean	add(E element) Deprecated.
void	add(int index, E element) Deprecated.
void	addChangeListener(RealmChangeListener listener) Adds a change listener to this RealmResults.
double	average(java.lang.String fieldName) Returns the average of a given field.
void	clear() Removes all objects from the list.
E	first() Gets the first object from the list.
E	get(int location) Returns the element at the specified location in this list.
int	indexOf(java.lang.Object o) This method is not supported.
boolean	isLoaded() Returns true if the results are not yet loaded, false if they are still loading.
boolean	isValid() Checks if RealmResults is still valid to use i.e.
java.util.Iterator<E>	iterator() Returns an iterator for the results of a query.
E	last() Gets the last object from the list.
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) Removes an object at a given index.
void	removeChangeListener(RealmChangeListener listener) Removes a previously registered listener.
void	removeChangeListeners() Removes all registered listeners.
void	removeLast() Removes and returns the last object in the list.
int	size() Returns the number of elements in this query result.
void	sort(java.lang.String fieldName) Sorts (ascending) an existing RealmResults.
void	sort(java.lang.String[] fieldNames, Sort[] sortOrders) Sorts existing RealmResults.
void	sort(java.lang.String fieldName, Sort sortOrder) Sorts existing RealmResults.
void	sort(java.lang.String fieldName1, Sort sortOrder1, java.lang.String fieldName2, Sort sortOrder2) Sorts existing RealmResults using two fields.
void	sort(java.lang.String fieldName1, Sort sortOrder1, java.lang.String fieldName2, Sort sortOrder2, java.lang.String fieldName3, Sort sortOrder3) Sorts existing RealmResults using three fields.
java.lang.Number	sum(java.lang.String fieldName) Calculates the sum of a given field.
RealmQuery<E>	where() Returns a typed RealmQuery, which can be used to query for specific objects of this type.

Methods inherited from class java.util.AbstractList

addAll, equals, hashCode, lastIndexOf, set, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

addAll, contains, containsAll, isEmpty, remove, removeAll, replaceAll, retainAll, sort, spliterator, 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 RealmResults is still valid to use i.e. the Realm instance hasn't been closed.

Returns:

true if still valid to use, false otherwise.

where

public RealmQuery<E> where()

Returns a typed RealmQuery, which can be used to query for specific objects of this type.

Returns:

a typed RealmQuery.

See Also:

RealmQuery

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 RealmObject>

Specified by:

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

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

indexOf

public int indexOf(java.lang.Object o)

This method is not supported.

Specified by:

indexOf in interface java.util.List<E extends RealmObject>

Overrides:

indexOf in class java.util.AbstractList<E extends RealmObject>

Throws:

java.lang.NoSuchMethodError - always.

first

public E first()

Gets the first object from the list.

Returns:

the first object.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if RealmResults is empty.

last

public E last()

Gets the last object from the list.

Returns:

the last object.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if RealmResults is empty.

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 RealmObject>

Specified by:

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

Specified by:

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

Overrides:

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

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 RealmObject>

Overrides:

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

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 RealmObject>

Overrides:

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

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 void sort(java.lang.String fieldName)

Sorts (ascending) an existing RealmResults.

Parameters:

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

Throws:

java.lang.IllegalArgumentException - if field name does not exist.

sort

public void sort(java.lang.String fieldName,
                 Sort sortOrder)

Sorts existing RealmResults.

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.

Throws:

java.lang.IllegalArgumentException - if field name does not exist.

sort

public void sort(java.lang.String[] fieldNames,
                 Sort[] sortOrders)

Sorts existing RealmResults.

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.

Throws:

java.lang.IllegalArgumentException - if a field name does not exist.

sort

public void sort(java.lang.String fieldName1,
                 Sort sortOrder1,
                 java.lang.String fieldName2,
                 Sort sortOrder2)

Sorts existing RealmResults using two fields.

Parameters:

fieldName1 - first field name.

sortOrder1 - sort order for first field.

fieldName2 - second field name.

sortOrder2 - sort order for second field.

Throws:

java.lang.IllegalArgumentException - if a field name does not exist.

sort

public void sort(java.lang.String fieldName1,
                 Sort sortOrder1,
                 java.lang.String fieldName2,
                 Sort sortOrder2,
                 java.lang.String fieldName3,
                 Sort sortOrder3)

Sorts existing RealmResults using three fields.

Parameters:

fieldName1 - first field name.

sortOrder1 - sort order for first field.

fieldName2 - second field name.

sortOrder2 - sort order for second field.

fieldName3 - third field name.

sortOrder3 - sort order for third field.

Throws:

java.lang.IllegalArgumentException - if a field name does not exist.

size

public int size()

Returns the number of elements in this query result.

Specified by:

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

Specified by:

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

Specified by:

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

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.

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:

java.lang.IllegalArgumentException - if the field is not a number type.

minDate

public java.util.Date minDate(java.lang.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:

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

max

public java.lang.Number max(java.lang.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:

java.lang.IllegalArgumentException - if the field is not a number type.

maxDate

public java.util.Date maxDate(java.lang.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:

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.

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:

java.lang.IllegalArgumentException - if the field is not a number type.

average

public double average(java.lang.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:

java.lang.IllegalArgumentException - if the field is not a number type.

remove

public E remove(int index)

Removes an object at a given index. This also deletes the object from the underlying Realm. Using this method while iterating the list can result in a undefined behavior. Use RealmResults.RealmResultsIterator.remove() instead.

Specified by:

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

Overrides:

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

Parameters:

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

Returns:

always return null.

Throws:

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

removeLast

public void removeLast()

Removes and returns the last object in the list. This also deletes the object from the underlying Realm. Using this method while iterating the list can result in a undefined behavior. Use removeLast() instead.

Throws:

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

clear

public void clear()

Removes all objects from the list. This also deletes the objects from the underlying Realm.

Specified by:

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

Specified by:

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

Overrides:

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

Throws:

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

add

@Deprecated
public boolean add(E element)

Deprecated.

Specified by:

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

Specified by:

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

Overrides:

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

add

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

Deprecated.

Specified by:

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

Overrides:

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

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 a standalone object (created outside of Realm).

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 listeners. This will return true for standalone object (created outside of Realm). RealmChangeListener when the query completes.

Returns:

true if it successfully completed the query, false otherwise.

addChangeListener

public void addChangeListener(RealmChangeListener listener)

Adds a change listener to this RealmResults.

Parameters:

listener - the change listener to be notified.

removeChangeListener

public void removeChangeListener(RealmChangeListener listener)

Removes a previously registered listener.

Parameters:

listener - the instance to be removed.

removeChangeListeners

public void removeChangeListeners()

Removes all registered listeners.