io.realm

Class Realm

java.lang.Object

io.realm.Realm

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public final class Realm
extends java.lang.Object
implements java.io.Closeable

The Realm class is the storage and transactional manager of your object persistent store. It is in charge of creating instances of your RealmObjects. Objects within a Realm can be queried and read at any time. Creating, modifying, and deleting objects must be done through transactions.

The transactions ensure that multiple instances (on multiple threads) can access the objects in a consistent state with full ACID guaranties.

If auto-refresh is set the instance of the Realm will be automatically updated when another instance commits a change (create, modify or delete an object). This feature requires the Realm instance to be residing in a thread attached to a Looper (the main thread has a Looper by default)

For normal threads Android provides a utility class that can be used like this:

 HandlerThread thread = new HandlerThread("MyThread") {
    \@Override
    protected void onLooperPrepared() {
       Realm realm = Realm.getInstance(getContext());
       // This realm will be updated by the event loop
       // on every commit performed by other realm instances
    }
 };
 thread.start();
 

It is important to remember to call the close() method when done with the Realm instance.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_REALM_NAME
protected static java.util.Map<android.os.Handler,java.lang.Integer>	handlers
protected static java.lang.ThreadLocal<java.util.Map<java.lang.Integer,Realm>>	realmsCache

Method Summary

Methods

Modifier and Type	Method and Description
void	addChangeListener(RealmChangeListener listener) Add a change listener to the Realm
<E extends RealmObject> RealmResults<E>	allObjects(java.lang.Class<E> clazz) Get all objects of a specific Class
<E extends RealmObject> RealmResults<E>	allObjects(java.lang.Class<E> clazz, java.lang.String fieldName, boolean sortAscending) Get all objects of a specific Class sorted by specific field name.
void	beginTransaction() Starts a write transaction, this must be closed with commitTransaction() or aborted by @{link io.realm.Realm#cancelTransaction()}.
void	cancelTransaction() Revert all writes (created, updated, or deleted objects) made in the current write transaction and end the transaction.
protected void	checkIfValid()
void	clear(java.lang.Class<?> classSpec) Remove all objects of the specified class.
void	close() Closes the Realm instance and all its resources.
void	commitTransaction() All changes since @{link io.realm.Realm#beginTransaction()} are persisted to disk and the realm reverts back to being read-only.
static boolean	compactRealmFile(android.content.Context context) Compact a realm file.
static boolean	compactRealmFile(android.content.Context context, java.lang.String fileName) Compact a realm file.
static Realm	create(java.io.File writableFolder, java.lang.String filename, byte[] key, boolean autoRefresh) Deprecated.
<E extends RealmObject> void	createAllFromJson(java.lang.Class<E> clazz, java.io.InputStream inputStream) Create a Realm object for each object in a JSON array.
<E extends RealmObject> void	createAllFromJson(java.lang.Class<E> clazz, org.json.JSONArray json) Create a Realm object for each object in a JSON array.
<E extends RealmObject> void	createAllFromJson(java.lang.Class<E> clazz, java.lang.String json) Create a Realm object for each object in a JSON array.
<E extends RealmObject> E	createObject(java.lang.Class<E> clazz) Instantiates and adds a new object to the realm
<E extends RealmObject> E	createObjectFromJson(java.lang.Class<E> clazz, java.io.InputStream inputStream) Create a Realm object prefilled with data from a JSON object.
<E extends RealmObject> E	createObjectFromJson(java.lang.Class<E> clazz, org.json.JSONObject json) Create a Realm object prefilled with data from a JSON object.
<E extends RealmObject> E	createObjectFromJson(java.lang.Class<E> clazz, java.lang.String json) Create a Realm object prefilled with data from a JSON object.
static boolean	deleteRealmFile(android.content.Context context) Delete the Realm file from the filesystem for the default Realm (named "default.realm").
static boolean	deleteRealmFile(android.content.Context context, java.lang.String fileName) Delete the Realm file from the filesystem for a custom named Realm.
protected void	finalize()
static Realm	getInstance(android.content.Context context) Realm static constructor for the default realm "default.realm".
static Realm	getInstance(android.content.Context context, boolean autoRefresh) Deprecated.
static Realm	getInstance(android.content.Context context, byte[] key) Realm static constructor.
static Realm	getInstance(android.content.Context context, byte[] key, boolean autoRefresh) Deprecated.
static Realm	getInstance(android.content.Context context, java.lang.String fileName) Realm static constructor.
static Realm	getInstance(android.content.Context context, java.lang.String fileName, boolean autoRefresh) Deprecated.
static Realm	getInstance(android.content.Context context, java.lang.String fileName, byte[] key, boolean autoRefresh) Deprecated.
static Realm	getInstance(java.io.File writableFolder, byte[] key, boolean autoRefresh) Deprecated.
java.lang.String	getPath() Returns the absolute path to where this Realm is persisted on disk.
Table	getTable(java.lang.Class<?> clazz)
boolean	isAutoRefresh() Retrieve the auto-refresh status of the Realm instance.
static void	migrateRealmAtPath(java.lang.String realmPath, byte[] key, RealmMigration migration)
static void	migrateRealmAtPath(java.lang.String realmPath, byte[] key, RealmMigration migration, boolean autoUpdate)
static void	migrateRealmAtPath(java.lang.String realmPath, RealmMigration migration)
static void	migrateRealmAtPath(java.lang.String realmPath, RealmMigration migration, boolean autoRefresh)
void	refresh() Refresh the Realm instance and all the RealmResults and RealmObjects instances coming from it
void	removeAllChangeListeners() Remove all user-defined change listeners
void	removeChangeListener(RealmChangeListener listener) Remove the specified change listener
void	setAutoRefresh(boolean autoRefresh) Set the auto-refresh status of the Realm instance.
<E extends RealmObject> RealmQuery<E>	where(java.lang.Class<E> clazz) Returns a typed RealmQuery, which can be used to query for specific objects of this type
void	writeCopyTo(java.io.File destination) Write a compacted copy of the Realm to the given destination File.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_REALM_NAME

public static final java.lang.String DEFAULT_REALM_NAME

See Also:

Constant Field Values

realmsCache

protected static final java.lang.ThreadLocal<java.util.Map<java.lang.Integer,Realm>> realmsCache

handlers

protected static final java.util.Map<android.os.Handler,java.lang.Integer> handlers

Method Detail

checkIfValid

protected void checkIfValid()

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

close

public void close()

Closes the Realm instance and all its resources. It's important to always remember to close Realm instances when you're done with it in order not to leak memory, file descriptors or grow the size of Realm file out of measure.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

isAutoRefresh

public boolean isAutoRefresh()

Retrieve the auto-refresh status of the Realm instance.

Returns:

the auto-refresh status

setAutoRefresh

public void setAutoRefresh(boolean autoRefresh)

Set the auto-refresh status of the Realm instance. Auto-refresh is a feature that enables automatic update of the current realm instance and all its derived objects (RealmResults and RealmObjects instances) when a commit is performed on a Realm acting on the same file in another thread. This feature is only available if the realm instance lives is a Looper enabled thread.

Parameters:

autoRefresh - true will turn auto-refresh on, false will turn it off.

Throws:

java.lang.IllegalStateException - if trying to enable auto-refresh in a thread without Looper.

getTable

public Table getTable(java.lang.Class<?> clazz)

getInstance

public static Realm getInstance(android.content.Context context)

Realm static constructor for the default realm "default.realm". {link io.realm.close} must be called when you are done using the Realm instance. It sets auto-refresh on if the current thread has a Looper, off otherwise.

Parameters:

context - an Android Context

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated in a Thread without a Looper

RealmException - Other errors

getInstance

@Deprecated
public static Realm getInstance(android.content.Context context,
                           boolean autoRefresh)

Deprecated.

Realm static constructor for the default realm "default.realm". {link io.realm.close} must be called when you are done using the Realm instance. This constructor is now deprecated and will be removed in version 0.76.0.

Parameters:

context - an Android context

autoRefresh - whether the Realm object and its derived objects (RealmResults and RealmObjects) should be automatically refreshed with the event loop (requires to be in a thread with a Looper)

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated with auto-refresh in a Thread without a Looper

RealmException - Other errors

getInstance

public static Realm getInstance(android.content.Context context,
                java.lang.String fileName)

Realm static constructor. {link io.realm.close} must be called when you are done using the Realm instance. It sets auto-refresh on if the current thread has a Looper, off otherwise.

Parameters:

context - an Android Context

fileName - the name of the file to save the Realm to

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated in a Thread without a Looper

RealmException - Other errors

getInstance

@Deprecated
public static Realm getInstance(android.content.Context context,
                           java.lang.String fileName,
                           boolean autoRefresh)

Deprecated.

Realm static constructor. {link io.realm.close} must be called when you are done using the Realm instance. This constructor is now deprecated and will be removed in version 0.76.0.

Parameters:

context - an Android context

fileName - the name of the file to save the Realm to

autoRefresh - whether the Realm object and its derived objects (RealmResults and RealmObjects) should be automatically refreshed with the event loop (requires to be in a thread with a Looper)

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated with auto-refresh in a Thread without a Looper

RealmException - Other errors

getInstance

@Deprecated
public static Realm getInstance(android.content.Context context,
                           byte[] key,
                           boolean autoRefresh)

Deprecated.

Realm static constructor. {link io.realm.close} must be called when you are done using the Realm instance. This constructor is now deprecated and will be removed in version 0.76.0.

Parameters:

context - an Android context

key - a 32-byte encryption key

autoRefresh - whether the Realm object and its derived objects (RealmResults and RealmObjects) should be automatically refreshed with the event loop (requires to be in a thread with a Looper)

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated with auto-refresh in a Thread without a Looper

RealmException - Other errors

getInstance

public static Realm getInstance(android.content.Context context,
                byte[] key)

Realm static constructor. {link io.realm.close} must be called when you are done using the Realm instance. It sets auto-refresh on if the current thread has a Looper, off otherwise.

Parameters:

context - an Android Context

key - a 32-byte encryption key

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated in a Thread without a Looper

RealmException - Other errors

getInstance

@Deprecated
public static Realm getInstance(android.content.Context context,
                           java.lang.String fileName,
                           byte[] key,
                           boolean autoRefresh)

Deprecated.

Realm static constructor. {link io.realm.close} must be called when you are done using the Realm instance. This constructor is now deprecated and will be removed in version 0.76.0.

Parameters:

context - an Android Context

fileName - the name of the file to save the Realm to

key - a 32-byte encryption key

autoRefresh - whether the Realm object and its derived objects (RealmResults and RealmObjects) should be automatically refreshed with the event loop (requires to be in a thread with a Looper)

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated in a Thread without a Looper

RealmException - Other errors

getInstance

@Deprecated
public static Realm getInstance(java.io.File writableFolder,
                           byte[] key,
                           boolean autoRefresh)

Deprecated.

Realm static constructor. {link io.realm.close} must be called when you are done using the Realm instance. This constructor is now deprecated and will be removed in version 0.76.0.

Parameters:

writableFolder - absolute path to a writable directory

key - a 32-byte encryption key

autoRefresh - whether the Realm object and its derived objects (RealmResults and RealmObjects) should be automatically refreshed with the event loop (requires to be in a thread with a Looper)

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated in a Thread without a Looper

RealmException - Other errors

create

@Deprecated
public static Realm create(java.io.File writableFolder,
                      java.lang.String filename,
                      byte[] key,
                      boolean autoRefresh)

Deprecated.

Realm static constructor. {link io.realm.close} must be called when you are done using the Realm instance. This constructor is now deprecated and will be removed in version 0.76.0.

Parameters:

writableFolder - absolute path to a writable directory

filename - the name of the file to save the Realm to

key - a 32-byte encryption key

autoRefresh - whether the Realm object and its derived objects (RealmResults and RealmObjects) should be automatically refreshed with the event loop (requires to be in a thread with a Looper)

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - The model classes have been changed and the Realm must be migrated

RealmIOException - Error when accessing underlying file

java.lang.IllegalStateException - The Realm is being instantiated in a Thread without a Looper

RealmException - Other errors

createAllFromJson

public <E extends RealmObject> void createAllFromJson(java.lang.Class<E> clazz,
                                             org.json.JSONArray json)

Create a Realm object for each object in a JSON array. This must be done inside a transaction. JSON properties with a null value will map to the default value for the data type in Realm and unknown properties will be ignored.

Parameters:

clazz - Type of Realm objects to create.

json - Array where each JSONObject must map to the specified class.

Throws:

RealmException - if mapping from JSON fails.

createAllFromJson

public <E extends RealmObject> void createAllFromJson(java.lang.Class<E> clazz,
                                             java.lang.String json)

Create a Realm object for each object in a JSON array. This must be done inside a transaction. JSON properties with a null value will map to the default value for the data type in Realm and unknown properties will be ignored.

Parameters:

clazz - Type of Realm objects to create.

json - JSON array as a String where each object can map to the specified class.

Throws:

RealmException - if mapping from JSON fails.

createAllFromJson

public <E extends RealmObject> void createAllFromJson(java.lang.Class<E> clazz,
                                             java.io.InputStream inputStream)
                       throws java.io.IOException

Create a Realm object for each object in a JSON array. This must be done inside a transaction. JSON properties with a null value will map to the default value for the data type in Realm and unknown properties will be ignored.

Parameters:

clazz - Type of Realm objects created.

inputStream - JSON array as a InputStream. All objects in the array must be of the specified class.

Throws:

RealmException - if mapping from JSON fails.

java.io.IOException - if something was wrong with the input stream.

createObjectFromJson

public <E extends RealmObject> E createObjectFromJson(java.lang.Class<E> clazz,
                                             org.json.JSONObject json)

Create a Realm object prefilled with data from a JSON object. This must be done inside a transaction. JSON properties with a null value will map to the default value for the data type in Realm and unknown properties will be ignored.

Parameters:

clazz - Type of Realm object to create.

json - JSONObject with object data.

Returns:

Created object or null if no json data was provided.

Throws:

RealmException - if the mapping from JSON fails.

createObjectFromJson

public <E extends RealmObject> E createObjectFromJson(java.lang.Class<E> clazz,
                                             java.lang.String json)

Create a Realm object prefilled with data from a JSON object. This must be done inside a transaction. JSON properties with a null value will map to the default value for the data type in Realm and unknown properties will be ignored.

Parameters:

clazz - Type of Realm object to create.

json - JSON string with object data.

Returns:

Created object or null if json string was empty or null.

Throws:

RealmException - if mapping to json failed.

createObjectFromJson

public <E extends RealmObject> E createObjectFromJson(java.lang.Class<E> clazz,
                                             java.io.InputStream inputStream)
                                           throws java.io.IOException

Create a Realm object prefilled with data from a JSON object. This must be done inside a transaction. JSON properties with a null value will map to the default value for the data type in Realm and unknown properties will be ignored.

Parameters:

clazz - Type of Realm object to create.

inputStream - JSON object data as a InputStream.

Returns:

Created object or null if json string was empty or null.

Throws:

RealmException - if the mapping from JSON failed.

java.io.IOException - if something was wrong with the input stream.

writeCopyTo

public void writeCopyTo(java.io.File destination)
                 throws java.io.IOException

Write a compacted copy of the Realm to the given destination File. The destination file cannot already exist. Note that if this is called from within a write transaction it writes the current data, and not the data as it was when the last write transaction was committed.

Parameters:

destination - File to save the Realm to

Throws:

java.io.IOException - if any write operation fails

createObject

public <E extends RealmObject> E createObject(java.lang.Class<E> clazz)

Instantiates and adds a new object to the realm

Parameters:

clazz - The Class of the object to create

Returns:

The new object

Throws:

RealmException - An object could not be created

where

public <E extends RealmObject> RealmQuery<E> where(java.lang.Class<E> clazz)

Returns a typed RealmQuery, which can be used to query for specific objects of this type

Parameters:

clazz - The class of the object which is to be queried for

Returns:

A typed RealmQuery, which can be used to query for specific objects of this type

Throws:

java.lang.RuntimeException - Any other error

See Also:

RealmQuery

allObjects

public <E extends RealmObject> RealmResults<E> allObjects(java.lang.Class<E> clazz)

Get all objects of a specific Class

Parameters:

clazz - the Class to get objects of

Returns:

A RealmResult list containing the objects

Throws:

java.lang.RuntimeException - Any other error

See Also:

RealmResults

allObjects

public <E extends RealmObject> RealmResults<E> allObjects(java.lang.Class<E> clazz,
                                                 java.lang.String fieldName,
                                                 boolean sortAscending)

Get all objects of a specific Class sorted by specific field name.

Parameters:

clazz - the Class to get objects of.

fieldName - the field name to sort by.

sortAscending - sort ascending if SORT_ORDER_ASCENDING, sort descending if SORT_ORDER_DESCENDING.

Returns:

A sorted RealmResults containing the objects.

Throws:

java.lang.IllegalArgumentException - if field name does not exist.

addChangeListener

public void addChangeListener(RealmChangeListener listener)

Add a change listener to the Realm

Parameters:

listener - the change listener

See Also:

RealmChangeListener

removeChangeListener

public void removeChangeListener(RealmChangeListener listener)

Remove the specified change listener

Parameters:

listener - the change listener to be removed

See Also:

RealmChangeListener

removeAllChangeListeners

public void removeAllChangeListeners()

Remove all user-defined change listeners

See Also:

RealmChangeListener

refresh

public void refresh()

Refresh the Realm instance and all the RealmResults and RealmObjects instances coming from it

beginTransaction

public void beginTransaction()

Starts a write transaction, this must be closed with commitTransaction() or aborted by @{link io.realm.Realm#cancelTransaction()}. Write transactions are used to atomically create, update and delete objects within a realm.
Before beginning the write transaction, @{link io.realm.Realm#beginTransaction()} updates the realm in the case of pending updates from other threads.
Notice: it is not possible to nest write transactions. If you start a write transaction within a write transaction an exception is thrown.

Throws:

java.lang.IllegalStateException - If already in a write transaction or incorrect thread.

commitTransaction

public void commitTransaction()

All changes since @{link io.realm.Realm#beginTransaction()} are persisted to disk and the realm reverts back to being read-only. An event is sent to notify all other realm instances that a change has occurred. When the event is received, the other realms will get their objects and @{link io.realm.RealmResults} updated to reflect the changes from this commit.

Throws:

java.lang.IllegalStateException - If the write transaction is in an invalid state or incorrect thread.

cancelTransaction

public void cancelTransaction()

Revert all writes (created, updated, or deleted objects) made in the current write transaction and end the transaction.
The realm reverts back to read-only.
Calling this when not in a write transaction will throw an exception.

Throws:

java.lang.IllegalStateException - If the write transaction is an invalid state, not in a write transaction or incorrect thread.

clear

public void clear(java.lang.Class<?> classSpec)

Remove all objects of the specified class.

Parameters:

classSpec - The class which objects should be removed

Throws:

java.lang.RuntimeException - Any other error

migrateRealmAtPath

public static void migrateRealmAtPath(java.lang.String realmPath,
                      RealmMigration migration)

migrateRealmAtPath

public static void migrateRealmAtPath(java.lang.String realmPath,
                      byte[] key,
                      RealmMigration migration)

migrateRealmAtPath

public static void migrateRealmAtPath(java.lang.String realmPath,
                      RealmMigration migration,
                      boolean autoRefresh)

migrateRealmAtPath

public static void migrateRealmAtPath(java.lang.String realmPath,
                      byte[] key,
                      RealmMigration migration,
                      boolean autoUpdate)

deleteRealmFile

public static boolean deleteRealmFile(android.content.Context context)

Delete the Realm file from the filesystem for the default Realm (named "default.realm"). The realm must be unused and closed before calling this method. WARNING: Your Realm must not be open (typically when your app launch).

Parameters:

context - an Android context.

Returns:

false if a file could not be deleted. The failing file will be logged.

See Also:

clear(Class)

deleteRealmFile

public static boolean deleteRealmFile(android.content.Context context,
                      java.lang.String fileName)

Delete the Realm file from the filesystem for a custom named Realm. The realm must be unused and closed before calling this method.

Parameters:

context - an Android @{Context.

fileName - the name of the custom Realm (i.e. "myCustomRealm.realm").

Returns:

false if a file could not be deleted. The failing file will be logged.

compactRealmFile

public static boolean compactRealmFile(android.content.Context context,
                       java.lang.String fileName)

Compact a realm file. A realm file usually contain free/unused space. This method removes this free space and the file size is thereby reduced. Objects within the realm files are untouched. The file must be closed before this method is called. The file system should have free space for at least a copy of the realm file. The realm file is left untouched if any file operation fails.

Parameters:

context - an Android Context

fileName - the name of the file to compact

Returns:

true if successful, false if any file operation failed

compactRealmFile

public static boolean compactRealmFile(android.content.Context context)

Compact a realm file. A realm file usually contain free/unused space. This method removes this free space and the file size is thereby reduced. Objects within the realm files are untouched. The file must be closed before this method is called. The file system should have free space for at least a copy of the realm file. The realm file is left untouched if any file operation fails.

Parameters:

context - an Android Context

Returns:

true if successful, false if any file operation failed

getPath

public java.lang.String getPath()

Returns the absolute path to where this Realm is persisted on disk.

Returns:

The absolute path to the realm file.