public abstract class RealmObject extends Object implements RealmModel
An annotation processor will create a proxy class for your RealmObject subclass.
The following field data types are supported:
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.
| Constructor and Description |
|---|
RealmObject() |
| Modifier and Type | Method and Description |
|---|---|
static <E extends RealmModel> |
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> |
addChangeListener(E object,
RealmObjectChangeListener<E> listener)
Adds a change listener to a RealmObject to get detailed information about the changes.
|
<E extends RealmModel> |
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> |
addChangeListener(RealmObjectChangeListener<E> listener)
Adds a change listener to this RealmObject to get detailed information about changes.
|
<E extends RealmObject> |
asObservable()
Returns an RxJava Observable that monitors changes to this RealmObject.
|
static <E extends RealmModel> |
asObservable(E object)
Returns an RxJava Observable that monitors changes to this RealmObject.
|
void |
deleteFromRealm()
Deletes the object from the Realm it is currently associated to.
|
static <E extends RealmModel> |
deleteFromRealm(E object)
Deletes the object from the Realm it is currently associated with.
|
boolean |
isLoaded()
Checks if the query used to find this RealmObject has completed.
|
static <E extends RealmModel> |
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> |
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> |
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> |
load(E object)
Makes an asynchronous query blocking.
|
void |
removeAllChangeListeners()
Removes all registered listeners.
|
static <E extends RealmModel> |
removeAllChangeListeners(E object)
Removes all registered listeners from the given RealmObject.
|
static <E extends RealmModel> |
removeChangeListener(E object,
RealmChangeListener<E> listener)
Removes a previously registered listener on the given RealmObject.
|
static <E extends RealmModel> |
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.
|
void |
removeChangeListeners()
Deprecated.
Use
removeAllChangeListeners() instead. |
static <E extends RealmModel> |
removeChangeListeners(E object)
Deprecated.
Use
removeAllChangeListeners(RealmModel) instead. |
public final void deleteFromRealm()
After this method is called the object will be invalid and any operation (read or write) performed on it will fail with an IllegalStateException.
IllegalStateException - if the corresponding Realm is closed or in an incorrect thread.isValid()public static <E extends RealmModel> void deleteFromRealm(E object)
After this method is called the object will be invalid and any operation (read or write) performed on it will fail with an IllegalStateException.
IllegalStateException - if the corresponding Realm is closed or in an incorrect thread.isValid()public final boolean isValid()
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().asObservable()
.filter(result.isLoaded() && result.isValid())
.first()
true if the object is still accessible or an unmanaged object, false otherwise.public static <E extends RealmModel> boolean isValid(E object)
Realm been closed. It will always return true for unmanaged objects.object - RealmObject to check validity for.true if the object is still accessible or an unmanaged object, false otherwise.public final boolean isLoaded()
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).
true if the query has completed, false if the query is in
progress.isValid()public static <E extends RealmModel> boolean isLoaded(E object)
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).
object - RealmObject to check.true if the query has completed, false if the query is in
progress.isValid(RealmModel)public boolean isManaged()
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). An unmanaged object can be created from a managed object by using
Realm.copyFromRealm(RealmModel).
true if the object is managed, false if it is unmanaged.public static <E extends RealmModel> boolean isManaged(E object)
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). An unmanaged object can be created from a managed object by using
Realm.copyFromRealm(RealmModel).
true if the object is managed, false if it is unmanaged.public final boolean load()
Note: This will return true if called for an unmanaged object (created outside of Realm).
true if it successfully completed the query, false otherwise.public static <E extends RealmModel> boolean load(E object)
Note: This will return true if called for an unmanaged object (created outside of Realm).
object - RealmObject to force load.true if it successfully completed the query, false otherwise.public final <E extends RealmModel> void addChangeListener(RealmObjectChangeListener<E> listener)
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
}
});
}
}
listener - the change listener to be notified.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.public final <E extends RealmModel> void addChangeListener(RealmChangeListener<E> listener)
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
}
});
}
}
listener - the change listener to be notified.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.public static <E extends RealmModel> void addChangeListener(E object, RealmObjectChangeListener<E> listener)
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
}
});
}
}
object - RealmObject to add listener to.listener - the change listener to be notified.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.public static <E extends RealmModel> void addChangeListener(E object, RealmChangeListener<E> listener)
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
}
});
}
}
object - RealmObject to add listener to.listener - the change listener to be notified.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.public final void removeChangeListener(RealmObjectChangeListener listener)
listener - the instance to be removed.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.public final void removeChangeListener(RealmChangeListener listener)
listener - the instance to be removed.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.public static <E extends RealmModel> void removeChangeListener(E object, RealmObjectChangeListener listener)
object - RealmObject to remove listener from.listener - the instance to be removed.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.public static <E extends RealmModel> void removeChangeListener(E object, RealmChangeListener<E> listener)
object - RealmObject to remove listener from.listener - the instance to be removed.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.@Deprecated public final void removeChangeListeners()
removeAllChangeListeners() instead.public final void removeAllChangeListeners()
@Deprecated public static <E extends RealmModel> void removeChangeListeners(E object)
removeAllChangeListeners(RealmModel) instead.object - RealmObject to remove all listeners from.IllegalArgumentException - if object is null or isn't managed by Realm.public static <E extends RealmModel> void removeAllChangeListeners(E object)
object - RealmObject to remove all listeners from.IllegalArgumentException - if object is null or isn't managed by Realm.public final <E extends RealmObject> <any> asObservable()
onComplete will never be called.
When chaining a RealmObject observable use obj.<MyRealmObjectClass>asObservable() to pass on
type information, otherwise the type of the following observables will be RealmObject.
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:
obj.asObservable()
.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.
E - RealmObject class that is being observed. Must be this class or its super types.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.public static <E extends RealmModel> <any> asObservable(E object)
onComplete will never be called.
When chaining a RealmObject observable use obj.<MyRealmObjectClass>asObservable() to pass on
type information, otherwise the type of the following observables will be RealmObject.
If you would like the asObservable() to stop emitting items you can instruct RxJava to
emit only the first item by using the first() operator:
obj.asObservable()
.filter(obj -> obj.isLoaded())
.first()
.subscribe( ... ) // You only get the object once
object - RealmObject class that is being observed. Must be this class or its super types.onNext. It will never call onComplete or OnError.UnsupportedOperationException - if the required RxJava framework is not on the classpath.