io.realm

Class RealmObject

java.lang.Object

io.realm.RealmObject

All Implemented Interfaces:

RealmModel

Direct Known Subclasses:

ClassPermissions, DynamicRealmObject, Permission, Permission, PermissionUser, RealmPermissions, Role, Subscription

public abstract class RealmObject
extends Object
implements RealmModel

In Realm you define your RealmObject classes by sub-classing RealmObject and adding fields to be persisted. You then create your objects within a Realm, and use your custom subclasses instead of using the RealmObject class directly.

An annotation processor will create a proxy class for your RealmObject subclass.

The following field data types are supported:

• boolean/Boolean
• short/Short
• int/Integer
• long/Long
• float/Float
• double/Double
• byte[]
• String
• Date
• Any RealmObject subclass
• RealmList

The types short, int, and long are mapped to long when storing within a Realm.

The only restriction a RealmObject has is that fields are not allowed to be final or volatile. Any method as well as public fields are allowed. When providing custom constructors, a public constructor with no arguments must be declared.

Fields annotated with Ignore don't have these restrictions and don't require either a getter or setter.

Realm will create indexes for fields annotated with Index. This will speedup queries but will have a negative impact on inserts and updates.

A RealmObject cannot be passed between different threads.

See Also:

Realm.createObject(Class), Realm.copyToRealm(RealmModel, ImportFlag...)

Constructor Summary

Constructors

Constructor and Description
RealmObject()

Method Summary

Modifier and Type	Method and Description
static <E extends RealmModel> void	addChangeListener(E object, RealmChangeListener<E> listener) Adds a change listener to a RealmObject that will be triggered if any value field or referenced RealmObject field is changed, or the RealmList field itself is changed.
static <E extends RealmModel> void	addChangeListener(E object, RealmObjectChangeListener<E> listener) Adds a change listener to a RealmObject to get detailed information about the changes.
<E extends RealmModel> void	addChangeListener(RealmChangeListener<E> listener) Adds a change listener to this RealmObject that will be triggered if any value field or referenced RealmObject field is changed, or the RealmList field itself is changed.
<E extends RealmModel> void	addChangeListener(RealmObjectChangeListener<E> listener) Adds a change listener to this RealmObject to get detailed information about changes.
<E extends RealmObject> <any>	asChangesetObservable() Returns an Rx Observable that monitors changes to this RealmObject.
static <E extends RealmModel> <any>	asChangesetObservable(E object) Returns an Rx Observable that monitors changes to this RealmObject.
<E extends RealmObject> <any>	asFlowable() Returns an RxJava Flowable that monitors changes to this RealmObject.
static <E extends RealmModel> <any>	asFlowable(E object) Returns an RxJava Flowable that monitors changes to this RealmObject.
void	deleteFromRealm() Deletes the object from the Realm it is currently associated to.
static <E extends RealmModel> void	deleteFromRealm(E object) Deletes the object from the Realm it is currently associated with.
Realm	getRealm() Returns Realm instance where this RealmObject belongs.
static Realm	getRealm(RealmModel model) returns Realm instance where the model belongs.
boolean	isLoaded() Checks if the query used to find this RealmObject has completed.
static <E extends RealmModel> boolean	isLoaded(E object) Checks if the query used to find this RealmObject has completed.
boolean	isManaged() Checks if this object is managed by Realm.
static <E extends RealmModel> boolean	isManaged(E object) Checks if this object is managed by Realm.
boolean	isValid() Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the Realm been closed.
static <E extends RealmModel> boolean	isValid(E object) Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the Realm been closed.
boolean	load() Makes an asynchronous query blocking.
static <E extends RealmModel> boolean	load(E object) Makes an asynchronous query blocking.
void	removeAllChangeListeners() Removes all registered listeners.
static <E extends RealmModel> void	removeAllChangeListeners(E object) Removes all registered listeners from the given RealmObject.
static <E extends RealmModel> void	removeChangeListener(E object, RealmChangeListener<E> listener) Removes a previously registered listener on the given RealmObject.
static <E extends RealmModel> void	removeChangeListener(E object, RealmObjectChangeListener listener) Removes a previously registered listener on the given RealmObject.
void	removeChangeListener(RealmChangeListener listener) Removes a previously registered listener.
void	removeChangeListener(RealmObjectChangeListener listener) Removes a previously registered listener.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RealmObject

public RealmObject()

Method Detail

deleteFromRealm

public final void deleteFromRealm()

Deletes the object from the Realm it is currently associated to.

After this method is called the object will be invalid and any operation (read or write) performed on it will fail with an IllegalStateException.

Throws:

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

See Also:

isValid()

deleteFromRealm

public static <E extends RealmModel> void deleteFromRealm(E object)

Deletes the object from the Realm it is currently associated with.

After this method is called the object will be invalid and any operation (read or write) performed on it will fail with an IllegalStateException.

Throws:

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

See Also:

isValid()

isValid

public final boolean isValid()

Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the Realm been closed. It will always return true for unmanaged objects.

Note that this can be used to check the validity of certain conditions such as being null when observed.

 
 realm.where(BannerRealm.class).equalTo("type", type).findFirstAsync().asFlowable()
      .filter(result.isLoaded() && result.isValid())
      .first()
 
 

Returns:

true if the object is still accessible or an unmanaged object, false otherwise.

See Also:

Examples using Realm with RxJava

isValid

public static <E extends RealmModel> boolean isValid(E object)

Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the Realm been closed. It will always return true for unmanaged objects.

Parameters:

object - RealmObject to check validity for.

Returns:

true if the object is still accessible or an unmanaged object, false otherwise.

isLoaded

public final boolean isLoaded()

Checks if the query used to find this RealmObject has completed.

Async methods like RealmQuery.findFirstAsync() return an RealmObject that represents the future result of the RealmQuery. It can be considered similar to a Future in this regard.

Once isLoaded() returns true, the object represents the query result even if the query didn't find any object matching the query parameters. In this case the RealmObject will become a "null" object.

"Null" objects represents null. An exception is throw if any accessor is called, so it is important to also check isValid() before calling any methods. A common pattern is:

 
 Person person = realm.where(Person.class).findFirstAsync();
 person.isLoaded(); // == false
 person.addChangeListener(new RealmChangeListener() {
      \@Override
      public void onChange(Person person) {
          person.isLoaded(); // Always true here
          if (person.isValid()) {
              // It is safe to access the person.
          }
      }
 });
 
 

Synchronous RealmObjects are by definition blocking hence this method will always return true for them. This method will return true if called on an unmanaged object (created outside of Realm).

Returns:

true if the query has completed, false if the query is in progress.

See Also:

isValid()

isLoaded

public static <E extends RealmModel> boolean isLoaded(E object)

Checks if the query used to find this RealmObject has completed.

Async methods like RealmQuery.findFirstAsync() return an RealmObject that represents the future result of the RealmQuery. It can be considered similar to a Future in this regard.

Once isLoaded() returns true, the object represents the query result even if the query didn't find any object matching the query parameters. In this case the RealmObject will become a "null" object.

"Null" objects represents null. An exception is throw if any accessor is called, so it is important to also check isValid() before calling any methods. A common pattern is:

 
 Person person = realm.where(Person.class).findFirstAsync();
 RealmObject.isLoaded(person); // == false
 RealmObject.addChangeListener(person, new RealmChangeListener() {
      \@Override
      public void onChange(Person person) {
          RealmObject.isLoaded(person); // always true here
          if (RealmObject.isValid(person)) {
              // It is safe to access the person.
          }
      }
 });
 
 

Synchronous RealmObjects are by definition blocking hence this method will always return true for them. This method will return true if called on an unmanaged object (created outside of Realm).

Parameters:

object - RealmObject to check.

Returns:

true if the query has completed, false if the query is in progress.

See Also:

isValid(RealmModel)

isManaged

public boolean isManaged()

Checks if this object is managed by Realm. A managed object is just a wrapper around the data in the underlying Realm file. On Looper threads, a managed object will be live-updated so it always points to the latest data. It is possible to register a change listener using addChangeListener(RealmChangeListener) to be notified when changes happen. Managed objects are thread confined so that they cannot be accessed from other threads than the one that created them.

If this method returns false, the object is unmanaged. An unmanaged object is just a normal Java object, so it can be parsed freely across threads, but the data in the object is not connected to the underlying Realm, so it will not be live updated.

It is possible to create a managed object from an unmanaged object by using Realm.copyToRealm(RealmModel, ImportFlag...). An unmanaged object can be created from a managed object by using Realm.copyFromRealm(RealmModel).

Returns:

true if the object is managed, false if it is unmanaged.

isManaged

public static <E extends RealmModel> boolean isManaged(E object)

Checks if this object is managed by Realm. A managed object is just a wrapper around the data in the underlying Realm file. On Looper threads, a managed object will be live-updated so it always points to the latest data. It is possible to register a change listener using addChangeListener(RealmModel, RealmChangeListener) to be notified when changes happen. Managed objects are thread confined so that they cannot be accessed from other threads than the one that created them.

If this method returns false, the object is unmanaged. An unmanaged object is just a normal Java object, so it can be parsed freely across threads, but the data in the object is not connected to the underlying Realm, so it will not be live updated.

It is possible to create a managed object from an unmanaged object by using Realm.copyToRealm(RealmModel, ImportFlag...). An unmanaged object can be created from a managed object by using Realm.copyFromRealm(RealmModel).

Returns:

true if the object is managed, false if it is unmanaged.

getRealm

public Realm getRealm()

Returns Realm instance where this RealmObject belongs.

You must not call BaseRealm.close() against returned instance.

Returns:

Realm instance where this object belongs to or null if this object is unmanaged.

Throws:

IllegalStateException - if this object is an instance of DynamicRealmObject or this object was already deleted or the corresponding Realm was already closed.

getRealm

public static Realm getRealm(RealmModel model)

returns Realm instance where the model belongs.

You must not call BaseRealm.close() against returned instance.

Parameters:

model - an RealmModel instance other than DynamicRealmObject.

Returns:

Realm instance where the model belongs or null if the model is unmanaged.

Throws:

IllegalArgumentException - if the model is null.

IllegalStateException - if the model is an instance of DynamicRealmObject or this object was already deleted or the corresponding Realm was already closed.

load

public final boolean load()

Makes an asynchronous query blocking. This will also trigger any registered listeners.

Note: This will return true if called for an unmanaged object (created outside of Realm).

Returns:

true if it successfully completed the query, false otherwise.

load

public static <E extends RealmModel> boolean load(E object)

Makes an asynchronous query blocking. This will also trigger any registered listeners.

Note: This will return true if called for an unmanaged object (created outside of Realm).

Parameters:

object - RealmObject to force load.

Returns:

true if it successfully completed the query, false otherwise.

addChangeListener

public final <E extends RealmModel> void addChangeListener(RealmObjectChangeListener<E> listener)

Adds a change listener to this RealmObject to get detailed information about changes. The listener will be triggered if any value field or referenced RealmObject field is changed, or the RealmList field itself is changed.

Registering a change listener will not prevent the underlying RealmObject from being garbage collected. If the RealmObject 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 Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmObjectChangeListener<Person>() {
           \@Override
           public void onChange(Person person, ObjectChangeSet changeSet) {
               // React to change
           }
       });
     }
 }
 
 

Parameters:

listener - the change listener to be notified.

Throws:

IllegalArgumentException - if the change listener is null or the object is an unmanaged object.

IllegalStateException - if you try to add a listener from a non-Looper or IntentService thread.

IllegalStateException - if you try to add a listener inside a transaction.

addChangeListener

public final <E extends RealmModel> void addChangeListener(RealmChangeListener<E> listener)

Adds a change listener to this RealmObject that will be triggered if any value field or referenced RealmObject field is changed, or the RealmList field itself is changed.

Registering a change listener will not prevent the underlying RealmObject from being garbage collected. If the RealmObject 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 Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmChangeListener<Person>() {
           \@Override
           public void onChange(Person person) {
               // React to change
           }
       });
     }
 }
 
 

Parameters:

listener - the change listener to be notified.

Throws:

IllegalArgumentException - if the change listener is null or the object is an unmanaged object.

IllegalStateException - if you try to add a listener from a non-Looper or IntentService thread.

IllegalStateException - if you try to add a listener inside a transaction.

addChangeListener

public static <E extends RealmModel> void addChangeListener(E object,
                                                            RealmObjectChangeListener<E> listener)

Adds a change listener to a RealmObject to get detailed information about the changes. The listener will be triggered if any value field or referenced RealmObject field is changed, or the RealmList field itself is changed.

Registering a change listener will not prevent the underlying RealmObject from being garbage collected. If the RealmObject 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 Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmObjectChangeListener<Person>() {
           \@Override
           public void onChange(Person person, ObjectChangeSet changeSet) {
               // React to change
           }
       });
     }
 }
 
 

Parameters:

object - RealmObject to add listener to.

listener - the change listener to be notified.

Throws:

IllegalArgumentException - if the object is null or an unmanaged object, or the change listener is null.

IllegalStateException - if you try to add a listener from a non-Looper or IntentService thread.

IllegalStateException - if you try to add a listener inside a transaction.

addChangeListener

public static <E extends RealmModel> void addChangeListener(E object,
                                                            RealmChangeListener<E> listener)

Adds a change listener to a RealmObject that will be triggered if any value field or referenced RealmObject field is changed, or the RealmList field itself is changed.

Registering a change listener will not prevent the underlying RealmObject from being garbage collected. If the RealmObject 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 Person person; // Strong reference to keep listeners alive

     \@Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       person = realm.where(Person.class).findFirst();
       person.addChangeListener(new RealmChangeListener<Person>() {
           \@Override
           public void onChange(Person person) {
               // React to change
           }
       });
     }
 }
 
 

Parameters:

object - RealmObject to add listener to.

listener - the change listener to be notified.

Throws:

IllegalArgumentException - if the object is null or an unmanaged object, or the change listener is null.

IllegalStateException - if you try to add a listener from a non-Looper or IntentService thread.

IllegalStateException - if you try to add a listener inside a transaction.

removeChangeListener

public final void removeChangeListener(RealmObjectChangeListener listener)

Removes a previously registered listener.

Parameters:

listener - the instance to be removed.

Throws:

IllegalArgumentException - if the change listener is null or the object is an unmanaged object.

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

removeChangeListener

public final void removeChangeListener(RealmChangeListener listener)

Removes a previously registered listener.

Parameters:

listener - the instance to be removed.

Throws:

IllegalArgumentException - if the change listener is null or the object is an unmanaged object.

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

removeChangeListener

public static <E extends RealmModel> void removeChangeListener(E object,
                                                               RealmObjectChangeListener listener)

Removes a previously registered listener on the given RealmObject.

Parameters:

object - RealmObject to remove listener from.

listener - the instance to be removed.

Throws:

IllegalArgumentException - if the object or the change listener is null.

IllegalArgumentException - if object is an unmanaged RealmObject.

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

removeChangeListener

public static <E extends RealmModel> void removeChangeListener(E object,
                                                               RealmChangeListener<E> listener)

Removes a previously registered listener on the given RealmObject.

Parameters:

object - RealmObject to remove listener from.

listener - the instance to be removed.

Throws:

IllegalArgumentException - if the object or the change listener is null.

IllegalArgumentException - if object is an unmanaged RealmObject.

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

removeAllChangeListeners

public final void removeAllChangeListeners()

Removes all registered listeners.

removeAllChangeListeners

public static <E extends RealmModel> void removeAllChangeListeners(E object)

Removes all registered listeners from the given RealmObject.

Parameters:

object - RealmObject to remove all listeners from.

Throws:

IllegalArgumentException - if object is null or isn't managed by Realm.

asFlowable

public final <E extends RealmObject> <any> asFlowable()

Returns an RxJava Flowable that monitors changes to this RealmObject. It will emit the current object when subscribed to. Object updates will continually be emitted as the RealmObject is updated - onComplete will never be called.

When chaining a RealmObject flowable use obj.<MyRealmObjectClass>asFlowable() to pass on type information, otherwise the type of the following observables will be RealmObject.

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:

 
 obj.asFlowable()
      .filter(obj -> obj.isLoaded())
      .first()
      .subscribe( ... ) // You only get the object 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.

Type Parameters:

E - RealmObject class that is being observed. Must be this class or its super types.

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.

See Also:

RxJava and Realm

asChangesetObservable

public final <E extends RealmObject> <any> asChangesetObservable()

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

The RealmObject will continually be emitted as it is updated - onComplete will never be called.

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:

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

asFlowable

public static <E extends RealmModel> <any> asFlowable(E object)

Returns an RxJava Flowable that monitors changes to this RealmObject. It will emit the current object when subscribed to. Object updates will continuously be emitted as the RealmObject is updated - onComplete will never be called.

When chaining a RealmObject observable use obj.<MyRealmObjectClass>asFlowable() to pass on type information, otherwise the type of the following observables will be RealmObject.

If you would like the asFlowable() to stop emitting items you can instruct RxJava to emit only the first item by using the first() operator:

 
 obj.asFlowable()
      .filter(obj -> obj.isLoaded())
      .first()
      .subscribe( ... ) // You only get the object once
 
 

Parameters:

object - RealmObject class that is being observed. Must be this class or its super types.

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.

See Also:

RxJava and Realm

asChangesetObservable

public static <E extends RealmModel> <any> asChangesetObservable(E object)

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

The RealmObject will continually be emitted as it is updated - onComplete will never be called.

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.

Parameters:

object - RealmObject class that is being observed. Must be this class or its super types.

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.

See Also:

RxJava and Realm