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 RealmApplication extends Application {

     \@Override
     public void onCreate() {
         super.onCreate();

         // The Realm file will be located in package's "files" directory.
         RealmConfiguration realmConfig = new RealmConfiguration.Builder(this).build();
         Realm.setDefaultConfiguration(realmConfig);
     }
 }

 public class RealmActivity extends Activity {

   private Realm realm;

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

   \@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) Adds a change listener to the Realm.
<E extends RealmObject> RealmResults<E>	allObjects(java.lang.Class<E> clazz) Gets all objects of a specific Class.
<E extends RealmObject> RealmResults<E>	allObjectsSorted(java.lang.Class<E> clazz, java.lang.String[] fieldNames, Sort[] sortOrders) Gets 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, Sort sortOrder) 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, Sort sortOrder1, java.lang.String fieldName2, Sort sortOrder2) Gets 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, Sort sortOrder1, java.lang.String fieldName2, Sort sortOrder2, java.lang.String fieldName3, Sort sortOrder3) Gets all objects of a specific class sorted by two specific field names.
<any>	asObservable() Returns an RxJava Observable that monitors changes to this Realm.
void	beginTransaction() Starts a transaction, this must be closed with BaseRealm.commitTransaction() or aborted by BaseRealm.cancelTransaction().
void	cancelTransaction() Reverts 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) Removes 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) Compacts a Realm file.
<E extends RealmObject> E	copyFromRealm(E realmObject) Makes a standalone in-memory copy of an already persisted RealmObject.
<E extends RealmObject> E	copyFromRealm(E realmObject, int maxDepth) Makes a standalone in-memory copy of an already persisted RealmObject.
<E extends RealmObject> java.util.List<E>	copyFromRealm(java.lang.Iterable<E> realmObjects) Makes a standalone in-memory copy of already persisted RealmObjects.
<E extends RealmObject> java.util.List<E>	copyFromRealm(java.lang.Iterable<E> realmObjects, int maxDepth) Makes a standalone in-memory copy of already persisted RealmObjects.
<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 creates 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 creates a new copy if no existing object could be found.
<E extends RealmObject> void	createAllFromJson(java.lang.Class<E> clazz, java.io.InputStream inputStream) Creates a Realm object for each object in a JSON array.
<E extends RealmObject> void	createAllFromJson(java.lang.Class<E> clazz, org.json.JSONArray json) Creates a Realm object for each object in a JSON array.
<E extends RealmObject> void	createAllFromJson(java.lang.Class<E> clazz, java.lang.String json) Creates 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) Creates 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) Creates 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) Creates 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.
void	deleteAll() Removes all objects from this Realm.
static boolean	deleteRealm(RealmConfiguration configuration) Deletes 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) Returns a distinct set of objects of a specific class.
<E extends RealmObject> RealmResults<E>	distinct(java.lang.Class<E> clazz, java.lang.String firstFieldName, java.lang.String... remainingFieldNames) Returns a distinct set of objects from a specific class.
<E extends RealmObject> RealmResults<E>	distinctAsync(java.lang.Class<E> clazz, java.lang.String fieldName) Returns 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) Deprecated. replaced by executeTransactionAsync(Transaction), executeTransactionAsync(Transaction, Transaction.OnSuccess), executeTransactionAsync(Transaction, io.realm.Realm.Transaction.OnError) and executeTransactionAsync(Transaction, Transaction.OnSuccess, Transaction.OnError).
RealmAsyncTask	executeTransactionAsync(Realm.Transaction transaction) Similar to executeTransaction(Transaction) but runs asynchronously on a worker thread.
RealmAsyncTask	executeTransactionAsync(Realm.Transaction transaction, Realm.Transaction.OnError onError) Similar to executeTransactionAsync(Transaction), but also accepts an OnError callback.
RealmAsyncTask	executeTransactionAsync(Realm.Transaction transaction, Realm.Transaction.OnSuccess onSuccess) Similar to executeTransactionAsync(Transaction), but also accepts an OnSuccess callback.
RealmAsyncTask	executeTransactionAsync(Realm.Transaction transaction, Realm.Transaction.OnSuccess onSuccess, Realm.Transaction.OnError onError) Similar to executeTransactionAsync(Transaction), but also accepts an OnSuccess and OnError callbacks.
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) Deprecated. use getDefaultInstance() or getInstance(RealmConfiguration) instead.
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.
RealmSchema	getSchema() Returns the schema for this Realm.
Table	getTable(java.lang.Class<? extends RealmObject> clazz) Deprecated.
long	getVersion() Returns the schema version for this Realm.
boolean	isAutoRefresh() Retrieves the auto-refresh status of the Realm instance.
boolean	isClosed() Checks if the Realm instance has already been closed.
boolean	isEmpty() Checks if this Realm contains any objects.
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.
void	refresh() Refreshes the Realm instance and all the RealmResults and RealmObjects instances coming from it.
void	removeAllChangeListeners() Removes all user-defined change listeners.
void	removeChangeListener(RealmChangeListener listener) Removes the specified change listener.
static void	removeDefaultConfiguration() Removes the current default configuration (if any).
void	setAutoRefresh(boolean autoRefresh) Sets 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) Writes a compacted copy of the Realm to the given destination File.
void	writeEncryptedCopyTo(java.io.File destination, byte[] key) Writes 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

asObservable

public <any> asObservable()

Returns an RxJava Observable that monitors changes to this Realm. It will emit the current state when subscribed to. Items will continually be emitted as the Realm is updated - onComplete will never be called. 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:

 
 realm.asObservable().first().subscribe( ... ) // You only get the results once
 
 

Returns:

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

See Also:

RxJava and Realm

getInstance

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

Deprecated. use getDefaultInstance() or getInstance(RealmConfiguration) instead.

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 RealmObject 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 RealmObject classes or version has has changed so a migration is required.

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

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 RealmObject classes or version has has changed so a migration is required.

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

java.lang.IllegalArgumentException - if a null RealmConfiguration is provided.

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 - the RealmConfiguration to use as the default configuration.

Throws:

java.lang.IllegalArgumentException - if a null RealmConfiguration is provided.

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)

Creates 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. If a RealmObject field is not present in the JSON object the RealmObject field will be set to the default value for that type.

Parameters:

clazz - type of Realm objects to create.

json - an 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. If updating a RealmObject and a field is not found in the JSON object, that field will not be updated. If a new RealmObject is created and a field is not found in the JSON object, that field will be assigned the default value for the field type.

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.

RealmException - if unable to map JSON.

See Also:

createAllFromJson(Class, org.json.JSONArray)

createAllFromJson

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

Creates 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. If a RealmObject field is not present in the JSON object the RealmObject field will be set to the default value for that type.

Parameters:

clazz - type of Realm objects to create.

json - the 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. If updating a RealmObject and a field is not found in the JSON object, that field will not be updated. If a new RealmObject is created and a field is not found in the JSON object, that field will be assigned the default value for the field type.

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.

RealmException - if unable to create a JSON array from the json string.

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

Creates 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. If a RealmObject field is not present in the JSON object the RealmObject field will be set to the default value for that type.

Parameters:

clazz - type of Realm objects created.

inputStream - the 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. If updating a RealmObject and a field is not found in the JSON object, that field will not be updated. If a new RealmObject is created and a field is not found in the JSON object, that field will be assigned the default value for the field type.

Parameters:

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

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

Throws:

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

RealmException - if unable to read JSON.

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)

Creates 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. If a RealmObject field is not present in the JSON object the RealmObject field will be set to the default value for that type.

Parameters:

clazz - type of Realm object to create.

json - the 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. If updating a RealmObject and a field is not found in the JSON object, that field will not be updated. If a new RealmObject is created and a field is not found in the JSON object, that field will be assigned the default value for the field type.

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.

RealmException - if JSON data cannot be mapped.

See Also:

createObjectFromJson(Class, org.json.JSONObject)

createObjectFromJson

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

Creates 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. If a RealmObject field is not present in the JSON object the RealmObject field will be set to the default value for that type.

Parameters:

clazz - type of Realm object to create.

json - the 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. If updating a RealmObject and a field is not found in the JSON object, that field will not be updated. If a new RealmObject is created and a field is not found in the JSON object, that field will be assigned the default value for the field type.

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.

RealmException - if JSON object cannot be mapped from the string parameter.

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

Creates 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. If a RealmObject field is not present in the JSON object the RealmObject field will be set to the default value for that type.

Parameters:

clazz - type of Realm object to create.

inputStream - the 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. If updating a RealmObject and a field is not found in the JSON object, that field will not be updated. If a new RealmObject is created and a field is not found in the JSON object, that field will be assigned the default value for the field type.

Parameters:

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

in - the 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.

RealmException - if failure to read JSON.

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 - if 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. Please note, copying an object will copy all field values. All unset fields in this and child objects will be set to their default value if not provided.

Parameters:

object - the 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 creates 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. Please note, copying an object will copy all field values. All unset fields in this and child objects will be set to their default value if not provided.

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. Please note, copying an object will copy all field values. All unset fields in this and child objects will be set to their default value if not provided.

Parameters:

objects - the 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 creates 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. Please note, copying an object will copy all field values. All unset fields in this and child objects will be set to their default value if not provided.

Parameters:

objects - a 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)

copyFromRealm

public <E extends RealmObject> java.util.List<E> copyFromRealm(java.lang.Iterable<E> realmObjects)

Makes a standalone in-memory copy of already persisted RealmObjects. This is a deep copy that will copy all referenced objects. The copied objects are all detached from Realm so they will no longer be automatically updated. This means that the copied objects might contain data that are no longer consistent with other managed Realm objects. *WARNING*: Any changes to copied objects can be merged back into Realm using copyToRealmOrUpdate(RealmObject), but all fields will be overridden, not just those that were changed. This includes references to other objects, and can potentially override changes made by other threads.

Type Parameters:

E - type of object.

Parameters:

realmObjects - RealmObjects to copy

Returns:

an in-memory detached copy of managed RealmObjects.

Throws:

java.lang.IllegalArgumentException - if the RealmObject is no longer accessible or it is a DynamicRealmObject.

See Also:

copyToRealmOrUpdate(Iterable)

copyFromRealm

public <E extends RealmObject> java.util.List<E> copyFromRealm(java.lang.Iterable<E> realmObjects,
                                                               int maxDepth)

Makes a standalone in-memory copy of already persisted RealmObjects. This is a deep copy that will copy all referenced objects up to the defined depth. The copied objects are all detached from Realm so they will no longer be automatically updated. This means that the copied objects might contain data that are no longer consistent with other managed Realm objects. *WARNING*: Any changes to copied objects can be merged back into Realm using copyToRealmOrUpdate(Iterable), but all fields will be overridden, not just those that were changed. This includes references to other objects even though they might be null due to maxDepth being reached. This can also potentially override changes made by other threads.

Type Parameters:

E - type of object.

Parameters:

realmObjects - RealmObjects to copy.

maxDepth - limit of the deep copy. All references after this depth will be null. Starting depth is 0.

Returns:

an in-memory detached copy of the RealmObjects.

Throws:

java.lang.IllegalArgumentException - if maxDepth < 0, the RealmObject is no longer accessible or it is a DynamicRealmObject.

See Also:

copyToRealmOrUpdate(Iterable)

copyFromRealm

public <E extends RealmObject> E copyFromRealm(E realmObject)

Makes a standalone in-memory copy of an already persisted RealmObject. This is a deep copy that will copy all referenced objects. The copied object(s) are all detached from Realm so they will no longer be automatically updated. This means that the copied objects might contain data that are no longer consistent with other managed Realm objects. *WARNING*: Any changes to copied objects can be merged back into Realm using copyToRealmOrUpdate(RealmObject), but all fields will be overridden, not just those that were changed. This includes references to other objects, and can potentially override changes made by other threads.

Type Parameters:

E - type of object.

Parameters:

realmObject - RealmObject to copy

Returns:

an in-memory detached copy of the managed RealmObject.

Throws:

java.lang.IllegalArgumentException - if the RealmObject is no longer accessible or it is a DynamicRealmObject.

See Also:

copyToRealmOrUpdate(RealmObject)

copyFromRealm

public <E extends RealmObject> E copyFromRealm(E realmObject,
                                               int maxDepth)

Makes a standalone in-memory copy of an already persisted RealmObject. This is a deep copy that will copy all referenced objects up to the defined depth. The copied object(s) are all detached from Realm so they will no longer be automatically updated. This means that the copied objects might contain data that are no longer consistent with other managed Realm objects. *WARNING*: Any changes to copied objects can be merged back into Realm using copyToRealmOrUpdate(RealmObject), but all fields will be overridden, not just those that were changed. This includes references to other objects even though they might be null due to maxDepth being reached. This can also potentially override changes made by other threads.

Type Parameters:

E - type of object.

Parameters:

realmObject - RealmObject to copy

maxDepth - limit of the deep copy. All references after this depth will be null. Starting depth is 0.

Returns:

an in-memory detached copy of the managed RealmObject.

Throws:

java.lang.IllegalArgumentException - if maxDepth < 0, the RealmObject is no longer accessible or it is a DynamicRealmObject.

See Also:

copyToRealmOrUpdate(RealmObject)

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.

See Also:

RealmQuery

allObjects

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

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

See Also:

RealmResults

allObjectsSorted

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

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.

sortOrder - how to sort the results.

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,
                                                                Sort sortOrder1,
                                                                java.lang.String fieldName2,
                                                                Sort sortOrder2)

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

sortOrder1 - sort order for first field.

fieldName2 - second field name to sort by.

sortOrder2 - 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,
                                                                Sort sortOrder1,
                                                                java.lang.String fieldName2,
                                                                Sort sortOrder2,
                                                                java.lang.String fieldName3,
                                                                Sort sortOrder3)

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

sortOrder1 - sort order for first field.

fieldName2 - second field name to sort by.

sortOrder2 - sort order for second field.

fieldName3 - third field name to sort by.

sortOrder3 - 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,
                                                                Sort[] sortOrders)

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

sortOrders - 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)

Returns 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 is null, does not exist, is an unsupported type, is not indexed, or points to linked fields.

distinctAsync

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

Returns 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 is null, does not exist, is an unsupported type, is not indexed, or points to linked fields.

distinct

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

Returns a distinct set of objects from a specific class. When multiple distinct fields are given, all unique combinations of values in the fields will be returned. In case of multiple matches, it is undefined which object is returned. Unless the result is sorted, then the first object will be returned.

Parameters:

clazz - the Class to get objects of.

firstFieldName - first field name to use when finding distinct objects.

remainingFieldNames - remaining field names when determining all unique combinations of field values.

Returns:

a non-null RealmResults containing the distinct objects.

Throws:

java.lang.IllegalArgumentException - if field names is empty or null, does not exist, is an unsupported type, or points to a linked field.

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 - the Realm.Transaction to execute.

Throws:

java.lang.IllegalArgumentException - if the transaction is null.

executeTransaction

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

Deprecated. replaced by executeTransactionAsync(Transaction), executeTransactionAsync(Transaction, Transaction.OnSuccess), executeTransactionAsync(Transaction, io.realm.Realm.Transaction.OnError) and executeTransactionAsync(Transaction, Transaction.OnSuccess, Transaction.OnError).

Similar to executeTransaction(Transaction) but runs asynchronously on 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.

Throws:

java.lang.IllegalArgumentException - if the transaction is null, or if the realm is opened from another thread.

executeTransactionAsync

public RealmAsyncTask executeTransactionAsync(Realm.Transaction transaction)

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

Parameters:

transaction - Realm.Transaction to execute.

Returns:

a RealmAsyncTask representing a cancellable task.

Throws:

java.lang.IllegalArgumentException - if the transaction is null, or if the realm is opened from another thread.

executeTransactionAsync

public RealmAsyncTask executeTransactionAsync(Realm.Transaction transaction,
                                              Realm.Transaction.OnSuccess onSuccess)

Similar to executeTransactionAsync(Transaction), but also accepts an OnSuccess callback.

Parameters:

transaction - Realm.Transaction to execute.

onSuccess - callback invoked when the transaction succeeds.

Returns:

a RealmAsyncTask representing a cancellable task.

Throws:

java.lang.IllegalArgumentException - if the transaction is null, or if the realm is opened from another thread.

executeTransactionAsync

public RealmAsyncTask executeTransactionAsync(Realm.Transaction transaction,
                                              Realm.Transaction.OnError onError)

Similar to executeTransactionAsync(Transaction), but also accepts an OnError callback.

Parameters:

transaction - Realm.Transaction to execute.

onError - callback invoked when the transaction failed.

Returns:

a RealmAsyncTask representing a cancellable task.

Throws:

java.lang.IllegalArgumentException - if the transaction is null, or if the realm is opened from another thread.

executeTransactionAsync

public RealmAsyncTask executeTransactionAsync(Realm.Transaction transaction,
                                              Realm.Transaction.OnSuccess onSuccess,
                                              Realm.Transaction.OnError onError)

Similar to executeTransactionAsync(Transaction), but also accepts an OnSuccess and OnError callbacks.

Parameters:

transaction - Realm.Transaction to execute.

onSuccess - callback invoked when the transaction succeeds.

onError - callback invoked when the transaction failed.

Returns:

a RealmAsyncTask representing a cancellable task.

Throws:

java.lang.IllegalArgumentException - if the transaction is null, or if the realm is opened from another thread.

clear

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

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

migrateRealm

public static void migrateRealm(RealmConfiguration configuration)
                         throws java.io.FileNotFoundException

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

Parameters:

configuration - RealmConfiguration

Throws:

java.io.FileNotFoundException - if the Realm file doesn't exist.

migrateRealm

public static void migrateRealm(RealmConfiguration configuration,
                                RealmMigration migration)
                         throws java.io.FileNotFoundException

Manually trigger a migration on a RealmMigration.

Parameters:

configuration - theRealmConfiguration.

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

Throws:

java.io.FileNotFoundException - if the Realm file doesn't exist.

deleteRealm

public static boolean deleteRealm(RealmConfiguration configuration)

Deletes 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)

Compacts 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, otherwise false will be returned.
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.

Throws:

java.lang.IllegalArgumentException - if the realm file is encrypted. Compacting an encrypted Realm file is not supported yet.

getTable

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

Deprecated.

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.

Throws:

RealmException - if unable to create an instance of the module.

See Also:

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

setAutoRefresh

public void setAutoRefresh(boolean autoRefresh)

Sets 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 called from a non-Looper thread.

isAutoRefresh

public boolean isAutoRefresh()

Retrieves 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)

Adds 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()

Listeners are stored as a strong reference, you need to remove the added listeners using removeChangeListener(RealmChangeListener) or removeAllChangeListeners() which removes all listeners including the ones added via anonymous classes.

Parameters:

listener - the change listener.

Throws:

java.lang.IllegalStateException - if you try to register a listener from a non-Looper Thread.

See Also:

RealmChangeListener, removeChangeListener(RealmChangeListener), removeAllChangeListeners()

removeChangeListener

public void removeChangeListener(RealmChangeListener listener)

Removes the specified change listener.

Parameters:

listener - the change listener to be removed.

Throws:

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

See Also:

RealmChangeListener, addChangeListener(RealmChangeListener)

removeAllChangeListeners

public void removeAllChangeListeners()

Removes all user-defined change listeners.

Throws:

java.lang.IllegalStateException - if you try to remove listeners from a non-Looper Thread.

See Also:

RealmChangeListener, addChangeListener(RealmChangeListener)

writeCopyTo

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

Writes 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

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

java.lang.IllegalArgumentException - if destination argument is null.

refresh

public void refresh()

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

Throws:

java.lang.IllegalStateException - if attempting to refresh from within a transaction.

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()

Reverts 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:

the 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

Throws:

java.lang.IllegalStateException - if attempting to close from another thread.

isClosed

public boolean isClosed()

Checks if the Realm instance has already been closed.

Returns:

true if closed, false otherwise.

Throws:

java.lang.IllegalStateException - if attempting to close from another thread.

isEmpty

public boolean isEmpty()

Checks if this Realm contains any objects.

Returns:

true if empty, @{code false} otherwise.

getSchema

public RealmSchema getSchema()

Returns the schema for this Realm.

Returns:

The RealmSchema for this Realm.

deleteAll

public void deleteAll()

Removes all objects from this Realm.

Throws:

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