Docs Home → Develop Applications → Atlas Device SDKs

Class RealmResults

Realm is now Atlas Device SDK – Learn More

io.realm

java.lang.Object

java.util.AbstractCollection

java.util.AbstractList

io.realm.OrderedRealmCollectionImpl

io.realm.RealmResults

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, Realm.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 RealmResults.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.

Tip

Method Summary

Modifier and Type	Method and Description
public void	addChangeListener ( io.realm.OrderedRealmCollectionChangeListener<io.realm.RealmResults<E>> listener ) Adds a change listener to this RealmResults .
public void	addChangeListener ( io.realm.RealmChangeListener<io.realm.RealmResults<E>> listener ) Adds a change listener to this RealmResults .
public <any>	asChangesetObservable () Returns an Rx Observable that monitors changes to this RealmResults.
public <any>	asFlowable () Returns an Rx Flowable that monitors changes to this RealmResults.
public String	asJSON () Returns a JSON representation of the matches of a RealmQuery .
public RealmResults	freeze ()
public boolean	isFrozen ()
public boolean	isLoaded () Returns `false` if the results are not yet loaded, `true` if they are loaded.
public boolean	load () Makes an asynchronous query blocking.
public void	removeAllChangeListeners () Removes all user-defined change listeners.
public void	removeChangeListener ( io.realm.OrderedRealmCollectionChangeListener<io.realm.RealmResults<E>> listener ) Removes the specified change listener.
public void	removeChangeListener ( io.realm.RealmChangeListener<io.realm.RealmResults<E>> listener ) Removes the specified change listener.
public void	setBlob ( String fieldName, byte[] value ) Sets the binary value of the given field in all of the objects in the collection.
public void	setBoolean ( String fieldName, boolean value ) Sets the `boolean` value of the given field in all of the objects in the collection.
public void	setByte ( String fieldName, byte value ) Sets the `byte` value of the given field in all of the objects in the collection.
public void	setDate ( String fieldName, Date value ) Sets the `Date` value of the given field in all of the objects in the collection.
public void	setDecimal128 ( String fieldName, Decimal128 value ) Sets the `Decimal128` value of the given field in all of the objects in the collection.
public void	setDouble ( String fieldName, double value ) Sets the `double` value of the given field in all of the objects in the collection.
public void	setFloat ( String fieldName, float value ) Sets the `float` value of the given field in all of the objects in the collection.
public void	setInt ( String fieldName, int value ) Sets the `int` value of the given field in all of the objects in the collection.
public void	setList <T >( String fieldName, io.realm.RealmList<T> list ) Replaces the RealmList at the given field on all objects in this collection.
public void	setLong ( String fieldName, long value ) Sets the `long` value of the given field in all of the objects in the collection.
public void	setNull ( String fieldName ) Sets the value to `null` for the given field in all of the objects in the collection.
public void	setObject ( String fieldName, RealmModel value ) Sets a reference to another object on the given field in all of the objects in the collection.
public void	setObjectId ( String fieldName, ObjectId value ) Sets the `ObjectId` value of the given field in all of the objects in the collection.
public void	setShort ( String fieldName, short value ) Sets the `short` value of the given field in all of the objects in the collection.
public void	setString ( String fieldName, String value ) Sets the `String` value of the given field in all of the objects in the collection.
public void	setUUID ( String fieldName, UUID value ) Sets the `UUID` value of the given field in all of the objects in the collection.
public void	setValue ( String fieldName, Object value ) Updates the field given by `fieldName` in all objects inside the query result.
public RealmResults	sort ( String fieldName1, Sort sortOrder1, String fieldName2, Sort sortOrder2 ) Sorts a collection based on the provided fields and sort orders.
public RealmQuery	where () Returns a RealmQuery , which can be used to query for specific objects from this collection.

Inherited Methods

Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize
Methods inherited from class java.util.AbstractCollection : iterator , size , isEmpty , contains , toArray , toArray , add , remove , containsAll , addAll , removeAll , retainAll , clear , toString
Methods inherited from class java.util.AbstractList : add , get , set , add , remove , indexOf , lastIndexOf , clear , addAll , iterator , listIterator , listIterator , subList , equals , hashCode , removeRange
Methods inherited from class io.realm.OrderedRealmCollectionImpl: isValid , isManaged , contains , get , first , first , last , last , deleteFromRealm , deleteAllFromRealm , iterator , listIterator , listIterator , sort , sort , sort , sort , size , min , minDate , max , maxDate , sum , average , remove , remove , removeAll , set , retainAll , deleteLastFromRealm , deleteFirstFromRealm , clear , add , add , addAll , addAll , createSnapshot , getRealm , getCollectionOperator

Method Detail

addChangeListener

public void addChangeListener (

io.realm.OrderedRealmCollectionChangeListener<io.realm.RealmResults<E>> listener

)

Adds a change listener to this RealmResults .

Registering a change listener will not prevent the underlying RealmResults from being garbage collected. If the RealmResults is garbage collected, the change listener will stop being triggered. To avoid this, keep a strong reference for as long as appropriate e.g. in a class variable.

public class MyActivity extends Activity {
    private RealmResults<Person> results; // Strong reference to keep listeners alive
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      results = realm.where(Person.class).findAllAsync();
      results.addChangeListener(new OrderedRealmCollectionChangeListener<RealmResults<Person>>() {
          @Override
          public void onChange(RealmResults<Person> persons, OrderedCollectionChangeSet changeSet) {
              // React to change
          }
      });
    }
}

Parameters

listener - the change listener to be notified.

Throws

IllegalArgumentException - if the change listener is null .
IllegalStateException - if you try to add a listener from a non-Looper or android.app.IntentService thread.

public void addChangeListener (

io.realm.RealmChangeListener<io.realm.RealmResults<E>> listener

)

Adds a change listener to this RealmResults .

public class MyActivity extends Activity {
    private RealmResults<Person> results; // Strong reference to keep listeners alive
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      results = realm.where(Person.class).findAllAsync();
      results.addChangeListener(new RealmChangeListener<RealmResults<Person>>() {
          @Override
          public void onChange(RealmResults<Person> persons) {
              // React to change
          }
      });
    }
}

Parameters

listener - the change listener to be notified.

Throws

IllegalArgumentException - if the change listener is null .
IllegalStateException - if you try to add a listener from a non-Looper or android.app.IntentService thread.

asChangesetObservable

public <any> asChangesetObservable ()

Returns an Rx Observable that monitors changes to this RealmResults. It will emit the current RealmResults when subscribed. For each update to the RealmResult a pair consisting of the RealmResults and the OrderedCollectionChangeSet will be sent. The changeset will be null the first time an RealmResults is emitted.

RealmResults will continually be emitted as the RealmResults are updated - onComplete will never be called.

Items emitted from Realm Observables are frozen (See freeze() . This means that they are immutable and can be read on any thread.

Realm Observables always emit items from the thread holding the live Realm. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:

realm.where(Foo.class).findAllAsync().asChangesetObservable()
 .observeOn(Schedulers.computation())
 .map((rxResults, changes) -> doExpensiveWork(rxResults, changes))
 .observeOn(AndroidSchedulers.mainThread())
 .subscribe( ... );

Returns

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

Throws

UnsupportedOperationException - if the required RxJava framework is not on the classpath or the corresponding Realm instance doesn't support RxJava.
IllegalStateException - if the Realm wasn't opened on a Looper thread.

Tip

asFlowable

public <any> asFlowable ()

Returns an Rx Flowable 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.

Items emitted from Realm Flowables are frozen (See freeze() . This means that they are immutable and can be read on any thread.

Realm Flowables always emit items from the thread holding the live RealmResults. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:

realm.where(Foo.class).findAllAsync().asFlowable()
 .observeOn(Schedulers.computation())
 .map(rxResults -> doExpensiveWork(rxResults))
 .observeOn(AndroidSchedulers.mainThread())
 .subscribe( ... );

If you would like the asFlowable() 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().asFlowable()
     .filter(results -> results.isLoaded())
     .first()
     .subscribe( ... ) // You only get the results once

Returns

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

Throws

UnsupportedOperationException - if the required RxJava framework is not on the classpath or the corresponding Realm instance doesn't support RxJava.
IllegalStateException - if the Realm wasn't opened on a Looper thread.

Tip

asJSON

public String asJSON ()
Returns a JSON representation of the matches of a RealmQuery . Cycles will be returned as row indices. This is a helper method used to inspect data, or for debugging purpose, this method could pull a large string which could cause an OutOfMemory error. Returns string representation of a JSON array containing entries of the resulting RealmQuery .

freeze

public RealmResults freeze ()

isFrozen

public boolean isFrozen ()

isLoaded

public boolean isLoaded ()
Returns `false` if the results are not yet loaded, `true` if they are loaded. Returns `true` if the query has completed and the data is available, `false` if the query is still running in the background.

load

public boolean load ()
Makes an asynchronous query blocking. This will also trigger any registered RealmChangeListener when the query completes. Returns `true` if it successfully completed the query, `false` otherwise.

removeAllChangeListeners

public void removeAllChangeListeners ()
Removes all user-defined change listeners. Throws IllegalStateException - if you try to remove listeners from a non-Looper Thread. Tip See also: io.realm.RealmChangeListener

removeChangeListener

public void removeChangeListener ( io.realm.OrderedRealmCollectionChangeListener<io.realm.RealmResults<E>> listener )
Removes the specified change listener. Parameters `listener` - the change listener to be removed. Throws IllegalArgumentException - if the change listener is `null` . IllegalStateException - if you try to remove a listener from a non-Looper Thread. Tip See also: io.realm.RealmChangeListener

public void removeChangeListener ( io.realm.RealmChangeListener<io.realm.RealmResults<E>> listener )
Removes the specified change listener. Parameters `listener` - the change listener to be removed. Throws IllegalArgumentException - if the change listener is `null` . IllegalStateException - if you try to remove a listener from a non-Looper Thread. Tip See also: io.realm.RealmChangeListener

setBlob

public void setBlob ( String fieldName, byte[] value )
Sets the binary value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a binary field.

setBoolean

public void setBoolean ( String fieldName, boolean value )
Sets the `boolean` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a boolean field.

setByte

public void setByte ( String fieldName, byte value )
Sets the `byte` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a byte field.

setDate

public void setDate ( String fieldName, Date value )
Sets the `Date` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a `Date` field.

setDecimal128

public void setDecimal128 ( String fieldName, Decimal128 value )
Sets the `Decimal128` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a `Decimal128` field.

setDouble

public void setDouble ( String fieldName, double value )
Sets the `double` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a double field.

setFloat

public void setFloat ( String fieldName, float value )
Sets the `float` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a float field.

setInt

public void setInt ( String fieldName, int value )
Sets the `int` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't an integer field.

setList

public void setList <T >( String fieldName, io.realm.RealmList<T> list )
Replaces the RealmList at the given field on all objects in this collection. Parameters `fieldName` - name of the field to update. `list` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, isn't a RealmList field , if the objects in the list are not managed or the type of the objects in the list are wrong.

setLong

public void setLong ( String fieldName, long value )
Sets the `long` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a long field.

setNull

public void setNull ( String fieldName )
Sets the value to `null` for the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. Throws IllegalArgumentException - if field name doesn't exist or is a primary key property. IllegalStateException - if the field cannot hold `null` values.

setObject

public void setObject ( String fieldName, RealmModel value )
Sets a reference to another object on the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new object referenced by this field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't an Object reference field.

setObjectId

public void setObjectId ( String fieldName, ObjectId value )
Sets the `ObjectId` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a `ObjectId` field.

setShort

public void setShort ( String fieldName, short value )
Sets the `short` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a short field.

setString

public void setString ( String fieldName, String value )
Sets the `String` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a String field.

setUUID

public void setUUID ( String fieldName, UUID value )
Sets the `UUID` value of the given field in all of the objects in the collection. Parameters `fieldName` - name of the field to update. `value` - new value for the field. Throws IllegalArgumentException - if field name doesn't exist, is a primary key property or isn't a `UUID` field.

setValue

public void setValue ( String fieldName, Object value )
Updates the field given by `fieldName` in all objects inside the query result. This method will automatically try to convert numbers and booleans that are given as `String` to their appropriate type. For example `"10"` will be converted to `10` if the field type is RealmFieldType.INTEGER . Using the typed setters like setInt(String, int) will be faster than using this method. Parameters `fieldName` - field to update `value` - value to update with. Throws IllegalArgumentException - if the field could not be found, could not be updated or the argument didn't match the field type or could not be converted to match the underlying field type.

public void setValue (

String fieldName,

Object value

)

Updates the field given by fieldName in all objects inside the query result.

This method will automatically try to convert numbers and booleans that are given as String to their appropriate type. For example "10" will be converted to 10 if the field type is RealmFieldType.INTEGER .

Using the typed setters like setInt(String, int) will be faster than using this method.

Parameters

fieldName - field to update
value - value to update with.

Throws

IllegalArgumentException - if the field could not be found, could not be updated or the argument didn't match the field type or could not be converted to match the underlying field type.

sort

public RealmResults sort ( String fieldName1, Sort sortOrder1, String fieldName2, Sort sortOrder2 )
Sorts a collection based on the provided fields and sort orders. Returns a new sorted RealmResults will be created and returned. The original collection stays unchanged. Overrides `sort` in class OrderedRealmCollectionImpl

where

public RealmQuery where ()
Returns a RealmQuery , which can be used to query for specific objects from this collection. Returns a RealmQuery object.

← Class RealmQuery

Class RealmSchema →

Class RealmResults.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

io.realm

Tip

See also:

Method Summary

Inherited Methods

Method Detail

addChangeListener

asChangesetObservable

Tip

See also:

asFlowable

Tip

See also:

asJSON

freeze

isFrozen

isLoaded

load

removeAllChangeListeners

Tip

See also:

removeChangeListener

Tip

See also:

Tip

See also:

setBlob

setBoolean

setByte

setDate

setDecimal128

setDouble

setFloat

setInt

setList

setLong

setNull

setObject

setObjectId

setShort

setString

setUUID

setValue

sort

where

Class RealmResults