E
- The class of objects in this list.public final class RealmResults<E extends RealmModel> extends AbstractList<E> implements OrderedRealmCollection<E>
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.
Modifier and Type | Method and Description |
---|---|
boolean |
add(E element)
Deprecated.
|
void |
add(int index,
E element)
Deprecated.
|
boolean |
addAll(Collection<? extends E> collection)
Deprecated.
|
boolean |
addAll(int location,
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(String fieldName)
Returns the average of a given field.
|
void |
clear()
Deprecated.
|
boolean |
contains(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(String fieldName)
Returns a distinct set of objects of a specific class.
|
RealmResults<E> |
distinct(String firstFieldName,
String... remainingFieldNames)
Returns a distinct set of objects from a specific class.
|
RealmResults<E> |
distinctAsync(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
false if the results are not yet loaded, true if they are loaded. |
boolean |
isValid()
Checks if the collection is still valid to use e.g.
|
Iterator<E> |
iterator()
Returns an iterator for the results of a query.
|
E |
last()
Gets the last object from the collection.
|
ListIterator<E> |
listIterator()
Returns a list iterator for the results of a query.
|
ListIterator<E> |
listIterator(int location)
Returns a list iterator on the results of a query.
|
boolean |
load()
Makes an asynchronous query blocking.
|
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.
|
E |
remove(int index)
Deprecated.
|
boolean |
remove(Object object)
Deprecated.
|
boolean |
removeAll(Collection<?> collection)
Deprecated.
|
void |
removeChangeListener(RealmChangeListener listener)
Removes a previously registered listener.
|
void |
removeChangeListeners()
Removes all registered listeners.
|
boolean |
retainAll(Collection<?> collection)
Deprecated.
|
E |
set(int location,
E object)
Deprecated.
|
int |
size()
Returns the number of elements in this query result.
|
RealmResults<E> |
sort(String fieldName)
Sorts a collection based on the provided field in ascending order.
|
RealmResults<E> |
sort(String[] fieldNames,
Sort[] sortOrders)
Sorts a collection based on the provided fields and sort orders.
|
RealmResults<E> |
sort(String fieldName,
Sort sortOrder)
Sorts a collection based on the provided field and sort order.
|
RealmResults<E> |
sort(String fieldName1,
Sort sortOrder1,
String fieldName2,
Sort sortOrder2)
Sorts a collection based on the provided fields and sort orders.
|
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. |
equals, hashCode, indexOf, lastIndexOf, subList
containsAll, isEmpty, toArray, toArray, toString
containsAll, equals, hashCode, indexOf, isEmpty, lastIndexOf, replaceAll, sort, spliterator, subList, toArray, toArray
parallelStream, removeIf, stream
public boolean isValid()
Realm
instance hasn't
been closed.isValid
in interface RealmCollection<E extends RealmModel>
true
if still valid to use, false
otherwise.public RealmQuery<E> where()
RealmQuery
, which can be used to query for specific objects from this collection.where
in interface RealmCollection<E extends RealmModel>
RealmQuery
public boolean contains(Object object)
RealmResults
for the specified object.contains
in interface RealmCollection<E extends RealmModel>
contains
in interface Collection<E extends RealmModel>
contains
in interface List<E extends RealmModel>
contains
in class AbstractCollection<E extends RealmModel>
object
- the object to search for.true
if object
is an element of this RealmResults
,
false
otherwisepublic E get(int location)
get
in interface List<E extends RealmModel>
get
in class AbstractList<E extends RealmModel>
location
- the index of the element to return.IndexOutOfBoundsException
- if location < 0 || location >= size()
.public E first()
first
in interface OrderedRealmCollection<E extends RealmModel>
public E last()
last
in interface OrderedRealmCollection<E extends RealmModel>
public void deleteFromRealm(int location)
deleteFromRealm
in interface OrderedRealmCollection<E extends RealmModel>
location
- the array index identifying the object to be removed.public boolean deleteAllFromRealm()
deleteAllFromRealm
in interface RealmCollection<E extends RealmModel>
true
if objects was deleted, false
otherwise.public Iterator<E> iterator()
ConcurrentModificationException
if accessed.iterator
in interface Iterable<E extends RealmModel>
iterator
in interface Collection<E extends RealmModel>
iterator
in interface List<E extends RealmModel>
iterator
in class AbstractList<E extends RealmModel>
Iterator
public ListIterator<E> listIterator()
ConcurrentModificationException
if accessed.listIterator
in interface List<E extends RealmModel>
listIterator
in class AbstractList<E extends RealmModel>
ListIterator
public ListIterator<E> listIterator(int location)
ConcurrentModificationException
if accessed.listIterator
in interface List<E extends RealmModel>
listIterator
in class AbstractList<E extends RealmModel>
location
- the index at which to start the iteration.IndexOutOfBoundsException
- if location < 0 || location > size()
.ListIterator
public RealmResults<E> sort(String fieldName)
sort
in interface OrderedRealmCollection<E extends RealmModel>
fieldName
- the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date,
and String are supported.RealmResults
will be created and returned. The original collection stays unchanged.public RealmResults<E> sort(String fieldName, Sort sortOrder)
sort
in interface OrderedRealmCollection<E extends RealmModel>
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.RealmResults
will be created and returned. The original collection stays unchanged.public RealmResults<E> sort(String[] fieldNames, Sort[] sortOrders)
sort
in interface OrderedRealmCollection<E extends RealmModel>
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.RealmResults
will be created and returned. The original collection stays unchanged.public RealmResults<E> sort(String fieldName1, Sort sortOrder1, String fieldName2, Sort sortOrder2)
sort
in interface OrderedRealmCollection<E extends RealmModel>
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.RealmResults
will be created and returned. The original collection stays unchanged.public int size()
size
in interface Collection<E extends RealmModel>
size
in interface List<E extends RealmModel>
size
in class AbstractCollection<E extends RealmModel>
public Number min(String fieldName)
min
in interface RealmCollection<E extends RealmModel>
fieldName
- the field to look for a minimum on. Only number fields are supported.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.public Date minDate(String fieldName)
minDate
in interface RealmCollection<E extends RealmModel>
fieldName
- the field to look for the minimum date. If fieldName is not of Date type, an exception is
thrown.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.public Number max(String fieldName)
max
in interface RealmCollection<E extends RealmModel>
fieldName
- the field to look for a maximum on. Only number fields are supported.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.public Date maxDate(String fieldName)
maxDate
in interface RealmCollection<E extends RealmModel>
fieldName
- the field to look for the maximum date. If fieldName is not of Date type, an exception is
thrown.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.IllegalArgumentException
- if fieldName is not a Date field.public Number sum(String fieldName)
sum
in interface RealmCollection<E extends RealmModel>
fieldName
- the field to sum. Only number fields are supported.null
as the value for the given field, 0
will be returned. When computing the sum, objects with null
values are ignored.public double average(String fieldName)
average
in interface RealmCollection<E extends RealmModel>
fieldName
- the field to calculate average on. Only number fields are supported.null
as the value for the given field,
0
will be returned. When computing the average, objects with null
values are ignored.public RealmResults<E> distinct(String fieldName)
fieldName
- the field name.RealmResults
containing the distinct objects.IllegalArgumentException
- if a field is null, does not exist, is an unsupported type,
is not indexed, or points to linked fields.public RealmResults<E> distinctAsync(String fieldName)
fieldName
- the field name.RealmResults
. Users need to register a listener
addChangeListener(RealmChangeListener)
to be notified when the
query completes.IllegalArgumentException
- if a field is null, does not exist, is an unsupported type,
is not indexed, or points to linked fields.public RealmResults<E> distinct(String firstFieldName, String... remainingFieldNames)
firstFieldName
- first field name to use when finding distinct objects.remainingFieldNames
- remaining field names when determining all unique combinations of field values.RealmResults
containing the distinct objects.IllegalArgumentException
- if field names is empty or null
, does not exist,
is an unsupported type, or points to a linked field.@Deprecated public E remove(int index)
remove
in interface List<E extends RealmModel>
remove
in class AbstractList<E extends RealmModel>
UnsupportedOperationException
@Deprecated public boolean remove(Object object)
remove
in interface Collection<E extends RealmModel>
remove
in interface List<E extends RealmModel>
remove
in class AbstractCollection<E extends RealmModel>
UnsupportedOperationException
@Deprecated public boolean removeAll(Collection<?> collection)
removeAll
in interface Collection<E extends RealmModel>
removeAll
in interface List<E extends RealmModel>
removeAll
in class AbstractCollection<E extends RealmModel>
UnsupportedOperationException
@Deprecated public E set(int location, E object)
set
in interface List<E extends RealmModel>
set
in class AbstractList<E extends RealmModel>
UnsupportedOperationException
@Deprecated public boolean retainAll(Collection<?> collection)
retainAll
in interface Collection<E extends RealmModel>
retainAll
in interface List<E extends RealmModel>
retainAll
in class AbstractCollection<E extends RealmModel>
UnsupportedOperationException
public boolean deleteLastFromRealm()
deleteLastFromRealm
in interface OrderedRealmCollection<E extends RealmModel>
true
if an object was deleted, false
otherwise.IllegalStateException
- if the corresponding Realm is closed or in an incorrect thread.public boolean deleteFirstFromRealm()
deleteFirstFromRealm
in interface OrderedRealmCollection<E extends RealmModel>
true
if an object was deleted, false
otherwise.IllegalStateException
- if the corresponding Realm is closed or in an incorrect thread.@Deprecated public void clear()
clear
in interface Collection<E extends RealmModel>
clear
in interface List<E extends RealmModel>
clear
in class AbstractList<E extends RealmModel>
UnsupportedOperationException
- always.@Deprecated public boolean add(E element)
add
in interface Collection<E extends RealmModel>
add
in interface List<E extends RealmModel>
add
in class AbstractList<E extends RealmModel>
UnsupportedOperationException
- always.@Deprecated public void add(int index, E element)
add
in interface List<E extends RealmModel>
add
in class AbstractList<E extends RealmModel>
UnsupportedOperationException
- always.@Deprecated public boolean addAll(int location, Collection<? extends E> collection)
addAll
in interface List<E extends RealmModel>
addAll
in class AbstractList<E extends RealmModel>
UnsupportedOperationException
- always.@Deprecated public boolean addAll(Collection<? extends E> collection)
addAll
in interface Collection<E extends RealmModel>
addAll
in interface List<E extends RealmModel>
addAll
in class AbstractCollection<E extends RealmModel>
UnsupportedOperationException
- always.public boolean isLoaded()
false
if the results are not yet loaded, true
if they are loaded. Synchronous
query methods like findAll() will always return true
, while asynchronous query methods like
findAllAsync() will return false
until the results are available.isLoaded
in interface RealmCollection<E extends RealmModel>
true
if the query has completed and the data is available, false
if the query is still
running.public boolean load()
RealmChangeListener
when
the query completes.load
in interface RealmCollection<E extends RealmModel>
true
if it successfully completed the query, false
otherwise. true
will always
be returned for unmanaged objects.public void addChangeListener(RealmChangeListener<RealmResults<E>> listener)
listener
- the change listener to be notified.IllegalArgumentException
- if the change listener is null
.IllegalStateException
- if you try to add a listener from a non-Looper or IntentService
thread.public void removeChangeListener(RealmChangeListener listener)
listener
- the instance to be removed.IllegalArgumentException
- if the change listener is null
.IllegalStateException
- if you try to remove a listener from a non-Looper Thread.public void removeChangeListeners()
public <any> asObservable()
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.
onNext
. It will never call onComplete
or OnError
.UnsupportedOperationException
- if the required RxJava framework is not on the classpath or the
corresponding Realm instance doesn't support RxJava.