Docs Menu

Class RealmObject

On this page

  • io.realm
  • Constructors
  • Method Summary
  • Inherited Methods
  • Constructor Detail
  • Method Detail
  • addChangeListener
  • asChangesetObservable
  • asFlowable
  • deleteFromRealm
  • freeze
  • getRealm
  • isFrozen
  • isLoaded
  • isManaged
  • isValid
  • load
  • removeAllChangeListeners
  • removeChangeListener
java.lang.Object
io.realm.RealmObject

Implemented interfaces:

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
  • org.bson.types.Decimal128
  • org.bson.types.ObjectId
  • 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 io.realm.annotations.Ignore don't have these restrictions and don't require either a getter or setter.

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

A RealmObject cannot be passed between different threads.

Tip
See also:
Constructor and Description
Modifier and Type
Method and Description
public static void

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.

public static void

Adds a change listener to a RealmObject to get detailed information about the changes.

public final void

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.

public final void

Adds a change listener to this RealmObject to get detailed information about changes.

public static <any>
E object
)

Returns an Rx Observable that monitors changes to this RealmObject.

public final <any>

Returns an Rx Observable that monitors changes to this RealmObject.

public static <any>
E object
)

Returns an RxJava Flowable that monitors changes to this RealmObject.

public final <any>
asFlowable <E >()

Returns an RxJava Flowable that monitors changes to this RealmObject.

public static void
E object
)

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

public final void

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

public static E
freeze <E >(
E object
)

Returns a frozen snapshot of this object.

public final E
freeze <E >()

Returns a frozen snapshot of this object.

public static Realm

returns Realm instance where the model belongs.

public Realm

Returns Realm instance where this RealmObject belongs.

public static boolean
isFrozen <E >(
E object
)

Returns whether or not this RealmObject is frozen.

public final boolean

Returns whether or not this RealmObject is frozen.

public static boolean
isLoaded <E >(
E object
)

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

public final boolean

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

public static boolean
isManaged <E >(
E object
)

Checks if this object is managed by Realm.

public boolean

Checks if this object is managed by Realm.

public static boolean
isValid <E >(
E object
)

Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the io.realm.Realm been closed.

public final boolean

Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the io.realm.Realm been closed.

public static boolean
load <E >(
E object
)

Makes an asynchronous query blocking.

public final boolean
load ()

Makes an asynchronous query blocking.

public static void

Removes all registered listeners from the given RealmObject.

public final void

Removes all registered listeners.

public static void

Removes a previously registered listener on the given RealmObject.

public static void

Removes a previously registered listener on the given RealmObject.

public final void

Removes a previously registered listener.

public final void

Removes a previously registered listener.

  • Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize
public RealmObject ()

public static void addChangeListener <E >(
)

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

public static void addChangeListener <E >(
)

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

public final void addChangeListener <E >(
)

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

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

public static <any> asChangesetObservable <E >(
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.

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:

obj.asChangesetObservable()
.observeOn(Schedulers.computation())
.map((rxObj, changes) -> doExpensiveWork(rxObj, changeså))
.observeOn(AndroidSchedulers.mainThread())
.subscribe( ... );

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

Tip
public final <any> asChangesetObservable <E >()

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.

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:

obj.asChangesetObservable()
.observeOn(Schedulers.computation())
.map((rxObj, changes) -> doExpensiveWork(rxObj, changeså))
.observeOn(AndroidSchedulers.mainThread())
.subscribe( ... );

Returns

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

Throws

Tip
public static <any> asFlowable <E >(
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 .

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 Realm. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:

obj.asFlowable()
.observeOn(Schedulers.computation())
.map((rxObj) -> doExpensiveWork(rxObj))
.observeOn(AndroidSchedulers.mainThread())
.subscribe( ... );

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

Tip
public final <any> asFlowable <E >()

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 .

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 Realm. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:

obj.asFlowable()
.observeOn(Schedulers.computation())
.map((rxObj) -> doExpensiveWork(rxObj))
.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:

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

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

Tip
public static void deleteFromRealm <E >(
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

Tip
See also:
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

Tip
See also:
public static E freeze <E >(
E object
)

Returns a frozen snapshot of this object. The frozen copy can be read and queried from any thread without throwing an IllegalStateException .

Freezing a RealmObject also creates a frozen Realm which has its own lifecycle, but if the live Realm that spawned the original collection is fully closed (i.e. all instances across all threads are closed), the frozen Realm and object will be closed as well.

Frozen objects can be queried as normal, but trying to mutate it in any way or attempting to register a listener will throw an IllegalStateException .

Note: Keeping a large number of frozen objects with different versions alive can have a negative impact on the filesize of the Realm. In order to avoid such a situation it is possible to set RealmConfiguration.Builder.maxNumberOfActiveVersions(long) .

Returns

a frozen copy of this object.

Throws

public final E freeze <E >()

Returns a frozen snapshot of this object. The frozen copy can be read and queried from any thread without throwing an IllegalStateException .

Freezing a RealmObject also creates a frozen Realm which has its own lifecycle, but if the live Realm that spawned the original collection is fully closed (i.e. all instances across all threads are closed), the frozen Realm and object will be closed as well.

Frozen objects can be queried as normal, but trying to mutate it in any way or attempting to register a listener will throw an IllegalStateException .

Note: Keeping a large number of frozen objects with different versions alive can have a negative impact on the filesize of the Realm. In order to avoid such a situation it is possible to set RealmConfiguration.Builder.maxNumberOfActiveVersions(long) .

Returns

a frozen copy of this object.

Throws

public static Realm getRealm (
)

returns Realm instance where the model belongs.

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

Parameters

Returns

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

Throws

public Realm getRealm ()

Returns Realm instance where this RealmObject belongs.

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

Returns

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

Throws

public static boolean isFrozen <E >(
E object
)

Returns whether or not this RealmObject is frozen.

Returns

true if the RealmObject is frozen, false if it is not.

Tip
See also:
public final boolean isFrozen ()

Returns whether or not this RealmObject is frozen.

Returns

true if the RealmObject is frozen, false if it is not.

Tip
See also:
public static boolean isLoaded <E >(
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 java.util.concurrent.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.

Tip
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 java.util.concurrent.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.

Tip
See also:
public static boolean isManaged <E >(
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.

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.

public static boolean isValid <E >(
E object
)

Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the io.realm.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.

public final boolean isValid ()

Checks if the RealmObject is still valid to use i.e., the RealmObject hasn't been deleted nor has the io.realm.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.

public static boolean load <E >(
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.

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.

public static void removeAllChangeListeners <E >(
E object
)

Removes all registered listeners from the given RealmObject.

Parameters

  • object - RealmObject to remove all listeners from.

Throws

public final void removeAllChangeListeners ()

Removes all registered listeners.
public static void removeChangeListener <E >(
)

Removes a previously registered listener on the given RealmObject.

Parameters

  • object - RealmObject to remove listener from.
  • listener - the instance to be removed.

Throws

public static void removeChangeListener <E >(
)

Removes a previously registered listener on the given RealmObject.

Parameters

  • object - RealmObject to remove listener from.
  • listener - the instance to be removed.

Throws

Removes a previously registered listener.

Parameters

  • listener - the instance to be removed.

Throws

Removes a previously registered listener.

Parameters

  • listener - the instance to be removed.

Throws

←  Interface RealmModelInterface RealmObjectChangeListener →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.