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

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 while inside a transaction. See beginTransaction()

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

It is important to remember to call the close() method when done with a Realm instance. Failing to do so can lead to OutOfMemoryError as the native resources cannot be freed.

Realm instances cannot be used across different threads. This means that you have to open an instance on each thread you want to use Realm. Realm instances are cached automatically per thread using reference counting, so as long as the reference count doesn't reach zero, calling getInstance(RealmConfiguration) will just return the cached Realm and should be considered a lightweight operation.

For the UI thread this means that opening and closing Realms should occur in either onCreate/onDestroy or onStart/onStop.

Realm instances coordinate their state across threads using the Handler mechanism. This also means that Realm instances on threads without a Looper cannot receive updates unless refresh() is manually called.

A standard pattern for working with Realm in Android activities can be seen below:

 public class RealmActivity extends Activity {

   private Realm realm;

   \@Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.layout_main);
     realm = Realm.getInstance(this);
   }

   \@Override
   protected void onDestroy() {
     super.onDestroy();
     realm.close();
   }
 }
 

Realm supports String and byte fields containing up to 16 MB.

See Also:

ACID, Examples using Realm

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Realm.Transaction Encapsulates a Realm transaction.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_REALM_NAME

Method Summary

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>	allObjectsSorted(java.lang.Class<E> clazz, java.lang.String[] fieldNames, boolean[] sortAscending) Get all objects of a specific Class sorted by multiple fields.
<E extends RealmObject> RealmResults<E>	allObjectsSorted(java.lang.Class<E> clazz, java.lang.String fieldName, boolean sortAscending) Get all objects of a specific Class sorted by a field.
<E extends RealmObject> RealmResults<E>	allObjectsSorted(java.lang.Class<E> clazz, java.lang.String fieldName1, boolean sortAscending1, java.lang.String fieldName2, boolean sortAscending2) Get all objects of a specific class sorted by two specific field names.
<E extends RealmObject> RealmResults<E>	allObjectsSorted(java.lang.Class<E> clazz, java.lang.String fieldName1, boolean sortAscending1, java.lang.String fieldName2, boolean sortAscending2, java.lang.String fieldName3, boolean sortAscending3) Get all objects of a specific class sorted by two specific field names.
void	beginTransaction() Starts a transaction, this must be closed with BaseRealm.commitTransaction() or aborted by BaseRealm.cancelTransaction().
void	cancelTransaction() Revert all writes (created, updated, or deleted objects) made in the current write transaction and end the transaction.
void	clear(java.lang.Class<? extends RealmObject> clazz) Remove all objects of the specified class.
void	close() Closes the Realm instance and all its resources.
void	commitTransaction() All changes since BaseRealm.beginTransaction() are persisted to disk and the Realm reverts back to being read-only.
static boolean	compactRealm(RealmConfiguration configuration) Compact a Realm file.
<E extends RealmObject> E	copyToRealm(E object) Copies a RealmObject to the Realm instance and returns the copy.
<E extends RealmObject> java.util.List<E>	copyToRealm(java.lang.Iterable<E> objects) Copies a collection of RealmObjects to the Realm instance and returns their copy.
<E extends RealmObject> E	copyToRealmOrUpdate(E object) Updates an existing RealmObject that is identified by the same PrimaryKey or create a new copy if no existing object could be found.
<E extends RealmObject> java.util.List<E>	copyToRealmOrUpdate(java.lang.Iterable<E> objects) Updates a list of existing RealmObjects that is identified by their PrimaryKey or create a new copy if no existing object could be found.
<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 pre-filled with data from a JSON object.
<E extends RealmObject> E	createObjectFromJson(java.lang.Class<E> clazz, org.json.JSONObject json) Create a Realm object pre-filled with data from a JSON object.
<E extends RealmObject> E	createObjectFromJson(java.lang.Class<E> clazz, java.lang.String json) Create a Realm object pre-filled with data from a JSON object.
<E extends RealmObject> void	createOrUpdateAllFromJson(java.lang.Class<E> clazz, java.io.InputStream in) Tries to update a list of existing objects identified by their primary key with new JSON data.
<E extends RealmObject> void	createOrUpdateAllFromJson(java.lang.Class<E> clazz, org.json.JSONArray json) Tries to update a list of existing objects identified by their primary key with new JSON data.
<E extends RealmObject> void	createOrUpdateAllFromJson(java.lang.Class<E> clazz, java.lang.String json) Tries to update a list of existing objects identified by their primary key with new JSON data.
<E extends RealmObject> E	createOrUpdateObjectFromJson(java.lang.Class<E> clazz, java.io.InputStream in) Tries to update an existing object defined by its primary key with new JSON data.
<E extends RealmObject> E	createOrUpdateObjectFromJson(java.lang.Class<E> clazz, org.json.JSONObject json) Tries to update an existing object defined by its primary key with new JSON data.
<E extends RealmObject> E	createOrUpdateObjectFromJson(java.lang.Class<E> clazz, java.lang.String json) Tries to update an existing object defined by its primary key with new JSON data.
static boolean	deleteRealm(RealmConfiguration configuration) Delete the Realm file specified by the given RealmConfiguration from the filesystem.
<E extends RealmObject> RealmResults<E>	distinct(java.lang.Class<E> clazz, java.lang.String fieldName) Return a distinct set of objects of a specific class.
<E extends RealmObject> RealmResults<E>	distinctAsync(java.lang.Class<E> clazz, java.lang.String fieldName) Return a distinct set of objects of a specific class.
void	executeTransaction(Realm.Transaction transaction) Executes a given transaction on the Realm.
RealmAsyncTask	executeTransaction(Realm.Transaction transaction, Realm.Transaction.Callback callback) Similar to executeTransaction(Transaction) but runs asynchronously from a worker thread
RealmConfiguration	getConfiguration() Returns the RealmConfiguration for this Realm.
static Realm	getDefaultInstance() Realm static constructor that returns the Realm instance defined by the RealmConfiguration set by setDefaultConfiguration(RealmConfiguration)
static java.lang.Object	getDefaultModule() Returns the default Realm module.
static Realm	getInstance(android.content.Context context) Realm static constructor for the default Realm file "default.realm".
static Realm	getInstance(RealmConfiguration configuration) Realm static constructor that returns the Realm instance defined by provided RealmConfiguration
java.lang.String	getPath() Returns the canonical path to where this Realm is persisted on disk.
Table	getTable(java.lang.Class<? extends RealmObject> clazz)
long	getVersion() Returns the schema version for this Realm.
boolean	isAutoRefresh() Retrieve the auto-refresh status of the Realm instance.
boolean	isClosed() Check if the Realm instance has already been closed.
boolean	isInTransaction() Checks if the Realm is currently in a transaction.
static void	migrateRealm(RealmConfiguration configuration) Manually trigger the migration associated with a given RealmConfiguration.
static void	migrateRealm(RealmConfiguration configuration, RealmMigration migration) Manually trigger a migration on a RealmMigration.
static void	migrateRealm(RealmConfiguration configuration, RealmMigration migration, io.realm.BaseRealm.MigrationCallback callback) Migrates the Realm file defined by the given configuration using the provided migration block.
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
static void	removeDefaultConfiguration() Removes the current default configuration (if any).
void	setAutoRefresh(boolean autoRefresh) Set the auto-refresh status of the Realm instance.
static void	setDefaultConfiguration(RealmConfiguration configuration) Sets the RealmConfiguration used when calling getDefaultInstance().
<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.
void	writeEncryptedCopyTo(java.io.File destination, byte[] key) Write a compacted and encrypted copy of the Realm to the given destination File.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

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

Realm static constructor for the default Realm file "default.realm". This is equivalent to calling Realm.getInstance(new RealmConfiguration(getContext()).build()) . This constructor is only provided for convenience. It is recommended to use getInstance(RealmConfiguration) or getDefaultInstance().

Parameters:

context - a non-null Android Context

Returns:

an instance of the Realm class.

Throws:

java.lang.IllegalArgumentException - if no Context is provided.

RealmMigrationNeededException - if the model classes no longer match the underlying Realm and it must be migrated.

RealmIOException - if an error happened when accessing the underlying Realm file.

getDefaultInstance

public static Realm getDefaultInstance()

Realm static constructor that returns the Realm instance defined by the RealmConfiguration set by setDefaultConfiguration(RealmConfiguration)

Returns:

an instance of the Realm class.

Throws:

java.lang.NullPointerException - If no default configuration has been defined.

RealmMigrationNeededException - If no migration has been provided by the default configuration and the model classes or version has has changed so a migration is required.

getInstance

public static Realm getInstance(RealmConfiguration configuration)

Realm static constructor that returns the Realm instance defined by provided RealmConfiguration

Parameters:

configuration - RealmConfiguration used to open the Realm

Returns:

an instance of the Realm class

Throws:

RealmMigrationNeededException - If no migration has been provided by the configuration and the model classes or version has has changed so a migration is required.

RealmEncryptionNotSupportedException - if the device doesn't support Realm encryption.

See Also:

for details on how to configure a Realm.

setDefaultConfiguration

public static void setDefaultConfiguration(RealmConfiguration configuration)

Sets the RealmConfiguration used when calling getDefaultInstance().

Parameters:

configuration - RealmConfiguration to use as the default configuration.

See Also:

for details on how to configure a Realm.

removeDefaultConfiguration

public static void removeDefaultConfiguration()

Removes the current default configuration (if any). Any further calls to getDefaultInstance() will fail until a new default configuration has been set using setDefaultConfiguration(RealmConfiguration).

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 within 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.

createOrUpdateAllFromJson

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

Tries to update a list of existing objects identified by their primary key with new JSON data. If an existing object could not be found in the Realm, a new object will be created. This must happen within a transaction.

Parameters:

clazz - Type of RealmObject to create or update. It must have a primary key defined.

json - Array with object data.

Throws:

java.lang.IllegalArgumentException - if trying to update a class without a PrimaryKey.

See Also:

createAllFromJson(Class, org.json.JSONArray)

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 within 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.

createOrUpdateAllFromJson

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

Tries to update a list of existing objects identified by their primary key with new JSON data. If an existing object could not be found in the Realm, a new object will be created. This must happen within a transaction.

Parameters:

clazz - Type of RealmObject to create or update. It must have a primary key defined.

json - String with an array of JSON objects.

Throws:

java.lang.IllegalArgumentException - if trying to update a class without a PrimaryKey.

See Also:

createAllFromJson(Class, String)

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 within 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.

createOrUpdateAllFromJson

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

Tries to update a list of existing objects identified by their primary key with new JSON data. If an existing object could not be found in the Realm, a new object will be created. This must happen within a transaction.

Parameters:

clazz - Type of RealmObject to create or update. It must have a primary key defined.

in - InputStream with a list of object data in JSON format.

Throws:

java.lang.IllegalArgumentException - if trying to update a class without a PrimaryKey.

java.io.IOException

See Also:

createOrUpdateAllFromJson(Class, java.io.InputStream)

createObjectFromJson

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

Create a Realm object pre-filled 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.

See Also:

createOrUpdateObjectFromJson(Class, org.json.JSONObject)

createOrUpdateObjectFromJson

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

Tries to update an existing object defined by its primary key with new JSON data. If no existing object could be found a new object will be saved in the Realm. This must happen within a transaction.

Parameters:

clazz - Type of RealmObject to create or update. It must have a primary key defined.

json - JSONObject with object data.

Returns:

Created or updated RealmObject.

Throws:

java.lang.IllegalArgumentException - if trying to update a class without a PrimaryKey.

See Also:

createObjectFromJson(Class, org.json.JSONObject)

createObjectFromJson

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

Create a Realm object pre-filled 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.

createOrUpdateObjectFromJson

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

Tries to update an existing object defined by its primary key with new JSON data. If no existing object could be found a new object will be saved in the Realm. This must happen within a transaction.

Parameters:

clazz - Type of RealmObject to create or update. It must have a primary key defined.

json - String with object data in JSON format.

Returns:

Created or updated RealmObject.

Throws:

java.lang.IllegalArgumentException - if trying to update a class without a PrimaryKey.

See Also:

createObjectFromJson(Class, String)

createObjectFromJson

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

Create a Realm object pre-filled 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.

createOrUpdateObjectFromJson

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

Tries to update an existing object defined by its primary key with new JSON data. If no existing object could be found a new object will be saved in the Realm. This must happen within a transaction.

Parameters:

clazz - Type of RealmObject to create or update. It must have a primary key defined.

in - InputStream with object data in JSON format.

Returns:

Created or updated RealmObject.

Throws:

java.lang.IllegalArgumentException - if trying to update a class without a PrimaryKey.

java.io.IOException

See Also:

createObjectFromJson(Class, java.io.InputStream)

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

copyToRealm

public <E extends RealmObject> E copyToRealm(E object)

Copies a RealmObject to the Realm instance and returns the copy. Any further changes to the original RealmObject will not be reflected in the Realm copy. This is a deep copy, so all referenced objects will be copied. Objects already in this Realm will be ignored.

Parameters:

object - RealmObject to copy to the Realm.

Returns:

A managed RealmObject with its properties backed by the Realm.

Throws:

java.lang.IllegalArgumentException - if RealmObject is null.

copyToRealmOrUpdate

public <E extends RealmObject> E copyToRealmOrUpdate(E object)

Updates an existing RealmObject that is identified by the same PrimaryKey or create a new copy if no existing object could be found. This is a deep copy or update, so all referenced objects will be either copied or updated.

Parameters:

object - RealmObject to copy or update.

Returns:

The new or updated RealmObject with all its properties backed by the Realm.

Throws:

java.lang.IllegalArgumentException - if RealmObject is null or doesn't have a Primary key defined.

See Also:

copyToRealm(RealmObject)

copyToRealm

public <E extends RealmObject> java.util.List<E> copyToRealm(java.lang.Iterable<E> objects)

Copies a collection of RealmObjects to the Realm instance and returns their copy. Any further changes to the original RealmObjects will not be reflected in the Realm copies. This is a deep copy, so all referenced objects will be copied. Objects already in this Realm will be ignored.

Parameters:

objects - RealmObjects to copy to the Realm.

Returns:

A list of the the converted RealmObjects that all has their properties managed by the Realm.

Throws:

RealmException - if any of the objects has already been added to Realm.

java.lang.IllegalArgumentException - if any of the elements in the input collection is null.

copyToRealmOrUpdate

public <E extends RealmObject> java.util.List<E> copyToRealmOrUpdate(java.lang.Iterable<E> objects)

Updates a list of existing RealmObjects that is identified by their PrimaryKey or create a new copy if no existing object could be found. This is a deep copy or update, so all referenced objects will be either copied or updated.

Parameters:

objects - List of objects to update or copy into Realm.

Returns:

A list of all the new or updated RealmObjects.

Throws:

java.lang.IllegalArgumentException - if RealmObject is null or doesn't have a Primary key defined.

See Also:

copyToRealm(Iterable)

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. If no objects exist, the returned RealmResults will not be null. The RealmResults.size() to check the number of objects instead.

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

allObjectsSorted

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

Get all objects of a specific Class sorted by a field. If no objects exist, the returned RealmResults will not be null. The RealmResults.size() to check the number of objects instead.

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.

allObjectsSorted

public <E extends RealmObject> RealmResults<E> allObjectsSorted(java.lang.Class<E> clazz,
                                                                java.lang.String fieldName1,
                                                                boolean sortAscending1,
                                                                java.lang.String fieldName2,
                                                                boolean sortAscending2)

Get all objects of a specific class sorted by two specific field names. If no objects exist, the returned RealmResults will not be null. The RealmResults.size() to check the number of objects instead.

Parameters:

clazz - the class ti get objects of.

fieldName1 - first field name to sort by.

sortAscending1 - sort order for first field.

fieldName2 - second field name to sort by.

sortAscending2 - sort order for second field.

Returns:

A sorted RealmResults containing the objects.

Throws:

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

allObjectsSorted

public <E extends RealmObject> RealmResults<E> allObjectsSorted(java.lang.Class<E> clazz,
                                                                java.lang.String fieldName1,
                                                                boolean sortAscending1,
                                                                java.lang.String fieldName2,
                                                                boolean sortAscending2,
                                                                java.lang.String fieldName3,
                                                                boolean sortAscending3)

Get all objects of a specific class sorted by two specific field names. If no objects exist, the returned RealmResults will not be null. The RealmResults.size() to check the number of objects instead.

Parameters:

clazz - the class ti get objects of.

fieldName1 - first field name to sort by.

sortAscending1 - sort order for first field.

fieldName2 - second field name to sort by.

sortAscending2 - sort order for second field.

fieldName3 - third field name to sort by.

sortAscending3 - sort order for third field.

Returns:

A sorted RealmResults containing the objects.

Throws:

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

allObjectsSorted

public <E extends RealmObject> RealmResults<E> allObjectsSorted(java.lang.Class<E> clazz,
                                                                java.lang.String[] fieldNames,
                                                                boolean[] sortAscending)

Get all objects of a specific Class sorted by multiple fields. If no objects exist, the returned RealmResults will not be null. The RealmResults.size() to check the number of objects instead.

Parameters:

clazz - the Class to get objects of.

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

fieldNames - an array of field names to sort objects by. The objects are first sorted by fieldNames[0], then by fieldNames[1] and so forth.

Returns:

A sorted RealmResults containing the objects.

Throws:

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

distinct

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

Return a distinct set of objects of a specific class. As a Realm is unordered, it is undefined which objects are returned in case of multiple occurrences.

Parameters:

clazz - the Class to get objects of.

fieldName - the field name.

Returns:

A non-null RealmResults containing the distinct objects.

Throws:

java.lang.IllegalArgumentException - if a field name does not exist or the field is not indexed.

distinctAsync

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

Return a distinct set of objects of a specific class. As a Realm is unordered, it is undefined which objects are returned in case of multiple occurrences. This method is only available from a Looper thread.

Parameters:

clazz - the Class to get objects of.

fieldName - the field name.

Returns:

immediately an empty RealmResults. Users need to register a listener RealmResults.addChangeListener(RealmChangeListener) to be notified when the query completes.

Throws:

java.lang.IllegalArgumentException - if a field name does not exist or the field is not indexed.

executeTransaction

public void executeTransaction(Realm.Transaction transaction)

Executes a given transaction on the Realm. beginTransaction() and commitTransaction() will be called automatically. If any exception is thrown during the transaction cancelTransaction() will be called instead of commitTransaction().

Parameters:

transaction - Realm.Transaction to execute.

Throws:

RealmException - if any error happened during the transaction.

executeTransaction

public RealmAsyncTask executeTransaction(Realm.Transaction transaction,
                                         Realm.Transaction.Callback callback)

Similar to executeTransaction(Transaction) but runs asynchronously from a worker thread

Parameters:

transaction - Realm.Transaction to execute.

callback - optional, to receive the result of this query

Returns:

A RealmAsyncTask representing a cancellable task

clear

public void clear(java.lang.Class<? extends RealmObject> clazz)

Remove all objects of the specified class.

Parameters:

clazz - The class which objects should be removed

Throws:

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

java.lang.RuntimeException - Any other error

migrateRealm

public static void migrateRealm(RealmConfiguration configuration)

Manually trigger the migration associated with a given RealmConfiguration. If Realm is already at the latest version, nothing will happen.

Parameters:

configuration - RealmConfiguration

migrateRealm

public static void migrateRealm(RealmConfiguration configuration,
                                RealmMigration migration)

Manually trigger a migration on a RealmMigration.

Parameters:

configuration - RealmConfiguration

migration - RealmMigration to run on the Realm. This will override any migration set on the configuration.

deleteRealm

public static boolean deleteRealm(RealmConfiguration configuration)

Delete the Realm file specified by the given RealmConfiguration from the filesystem. The Realm must be unused and closed before calling this method.

Parameters:

configuration - A RealmConfiguration

Returns:

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

compactRealm

public static boolean compactRealm(RealmConfiguration configuration)

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:

configuration - a RealmConfiguration pointing to a Realm file.

Returns:

true if successful, false if any file operation failed

getTable

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

getDefaultModule

public static java.lang.Object getDefaultModule()

Returns the default Realm module. This module contains all Realm classes in the current project, but not those from library or project dependencies. Realm classes in these should be exposed using their own module.

Returns:

The default Realm module or null if no default module exists.

See Also:

RealmConfiguration.Builder.setModules(Object, Object...)

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.

isAutoRefresh

public boolean isAutoRefresh()

Retrieve the auto-refresh status of the Realm instance.

Returns:

the auto-refresh status

isInTransaction

public boolean isInTransaction()

Checks if the Realm is currently in a transaction.

Returns:

true if inside a transaction, false otherwise.

addChangeListener

public void addChangeListener(RealmChangeListener listener)

Add a change listener to the Realm.

The listeners will be executed:

• Immediately if a change was committed by the local thread
• On every loop of a Handler thread if changes were committed by another thread
• On every call to BaseRealm.refresh()

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

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 transaction it writes the current data, and not the data as it was when the last transaction was committed.

Parameters:

destination - File to save the Realm to

Throws:

java.io.IOException - if any write operation fails

writeEncryptedCopyTo

public void writeEncryptedCopyTo(java.io.File destination,
                                 byte[] key)
                          throws java.io.IOException

Write a compacted and encrypted copy of the Realm to the given destination File.

The destination file cannot already exist.

Note that if this is called from within a transaction it writes the current data, and not the data as it was when the last transaction was committed.

Parameters:

destination - File to save the Realm to

key - a 64-byte encryption key

Throws:

java.io.IOException - if any write operation fails

RealmEncryptionNotSupportedException - if the device doesn't support Realm encryption.

refresh

public void refresh()

Refresh the Realm instance and all the RealmResults and RealmObjects instances coming from it. It also calls the listeners associated to the Realm instance.

beginTransaction

public void beginTransaction()

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

commitTransaction

public void commitTransaction()

All changes since BaseRealm.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 RealmResults updated to reflect the changes from this commit.

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 transaction will throw an exception.

getPath

public java.lang.String getPath()

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

Returns:

The canonical path to the Realm file.

See Also:

File.getCanonicalPath()

getConfiguration

public RealmConfiguration getConfiguration()

Returns the RealmConfiguration for this Realm.

Returns:

RealmConfiguration for this Realm.

getVersion

public long getVersion()

Returns the schema version for this Realm.

Returns:

The schema version for the Realm file backing this Realm.

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

isClosed

public boolean isClosed()

Check if the Realm instance has already been closed.

Returns:

true if closed, false otherwise.

migrateRealm

public static void migrateRealm(RealmConfiguration configuration,
                                RealmMigration migration,
                                io.realm.BaseRealm.MigrationCallback callback)

Migrates the Realm file defined by the given configuration using the provided migration block.