io.realm

Class DynamicRealm

java.lang.Object

io.realm.BaseRealm

io.realm.DynamicRealm

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public final class DynamicRealm
extends BaseRealm

DynamicRealm is a dynamic variant of Realm. This means that all access to data and/or queries are done using string based class names instead of class type references. This is useful during migrations or when working with string-based data like CSV or XML files. The same RealmConfiguration can be used to open a Realm file in both dynamic and typed mode, but modifying the schema while having both a typed and dynamic version open is highly discouraged and will most likely crash the typed Realm. During migrations only a DynamicRealm will be open. Dynamic Realms do not enforce schemas or schema versions and RealmMigration code is not used even if it has been defined in the RealmConfiguration. This means that the schema is not created or validated until a Realm has been opened in typed mode, so if a Realm file is opened in dynamic mode first it will not contain any information about classes and fields, and any queries for classes defined by the schema will fail.

See Also:

Realm, RealmSchema

Nested Class Summary

Nested Classes

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

Method Summary

Modifier and Type	Method and Description
RealmResults<DynamicRealmObject>	allObjects(java.lang.String className) Gets all objects of a specific class name.
RealmResults<DynamicRealmObject>	allObjectsSorted(java.lang.String className, java.lang.String[] fieldNames, Sort[] sortOrders) Gets all objects of a specific class name sorted by multiple fields.
RealmResults<DynamicRealmObject>	allObjectsSorted(java.lang.String className, java.lang.String fieldName, Sort sortOrder) Gets all objects of a specific class name sorted by a field.
RealmResults<DynamicRealmObject>	allObjectsSorted(java.lang.String className, java.lang.String fieldName1, Sort sortOrder1, java.lang.String fieldName2, Sort sortOrder2) Gets all objects of a specific class name sorted by two specific field names.
<any>	asObservable() Returns an RxJava Observable that monitors changes to this Realm.
void	clear(java.lang.String className) Deprecated.
DynamicRealmObject	createObject(java.lang.String className) Instantiates and adds a new object to the Realm.
DynamicRealmObject	createObject(java.lang.String className, java.lang.Object primaryKeyValue) Creates an object with a given primary key.
void	delete(java.lang.String className) Deletes all objects of the specified class from the Realm.
RealmResults<DynamicRealmObject>	distinct(java.lang.String className, java.lang.String fieldName) Returns a distinct set of objects of a specific class.
RealmResults<DynamicRealmObject>	distinct(java.lang.String className, java.lang.String firstFieldName, java.lang.String... remainingFieldNames) Returns a distinct set of objects from a specific class.
RealmResults<DynamicRealmObject>	distinctAsync(java.lang.String className, java.lang.String fieldName) Returns a distinct set of objects of a specific class.
void	executeTransaction(DynamicRealm.Transaction transaction) Executes a given transaction on the DynamicRealm.
static DynamicRealm	getInstance(RealmConfiguration configuration) Realm static constructor that returns a dynamic variant of the Realm instance defined by provided RealmConfiguration.
RealmQuery<DynamicRealmObject>	where(java.lang.String className) Returns a RealmQuery, which can be used to query for the provided class.

Methods inherited from class io.realm.BaseRealm

addChangeListener, beginTransaction, cancelTransaction, close, commitTransaction, deleteAll, getConfiguration, getPath, getSchema, getVersion, isAutoRefresh, isClosed, isEmpty, isInTransaction, refresh, removeAllChangeListeners, removeChangeListener, setAutoRefresh, writeCopyTo, writeEncryptedCopyTo

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static DynamicRealm getInstance(RealmConfiguration configuration)

Realm static constructor that returns a dynamic variant of the Realm instance defined by provided RealmConfiguration. Dynamic Realms do not care about schemaVersion and schemas, so opening a DynamicRealm will never trigger a migration.

Returns:

the DynamicRealm defined by the configuration.

Throws:

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

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

See Also:

for details on how to configure a Realm.

createObject

public DynamicRealmObject createObject(java.lang.String className)

Instantiates and adds a new object to the Realm.

Parameters:

className - the class name of the object to create.

Returns:

the new object.

Throws:

RealmException - if the object could not be created.

createObject

public DynamicRealmObject createObject(java.lang.String className,
                                       java.lang.Object primaryKeyValue)

Creates an object with a given primary key. Classes without a primary key defined must use createObject(String)} instead.

Returns:

the new object. All fields will have default values for their type, except for the primary key field which will have the provided value.

Throws:

java.lang.IllegalArgumentException - if the primary key value is of the wrong type.

java.lang.IllegalStateException - if the class doesn't have a primary key defined.

where

public RealmQuery<DynamicRealmObject> where(java.lang.String className)

Returns a RealmQuery, which can be used to query for the provided class.

Parameters:

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

Returns:

a RealmQuery, which can be used to query for specific objects of provided type.

Throws:

java.lang.IllegalArgumentException - if the class doesn't exist.

See Also:

RealmQuery

clear

@Deprecated
public void clear(java.lang.String className)

Deprecated.

Removes all objects of the specified class. DEPRECATED: Use delete(String) instead.

Parameters:

className - the class for which all objects should be removed.

delete

public void delete(java.lang.String className)

Deletes all objects of the specified class from the Realm.

Parameters:

className - the class for which all objects should be removed.

executeTransaction

public void executeTransaction(DynamicRealm.Transaction transaction)

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

Parameters:

transaction - DynamicRealm.Transaction to execute.

Throws:

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

allObjects

public RealmResults<DynamicRealmObject> allObjects(java.lang.String className)

Gets all objects of a specific class name.

Parameters:

className - the Class to get objects of.

Returns:

a RealmResults list containing the objects. If no results where found, an empty list will be returned.

See Also:

RealmResults

allObjectsSorted

public RealmResults<DynamicRealmObject> allObjectsSorted(java.lang.String className,
                                                         java.lang.String fieldName,
                                                         Sort sortOrder)

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

Parameters:

className - the class to get all objects from.

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 RealmResults<DynamicRealmObject> allObjectsSorted(java.lang.String className,
                                                         java.lang.String fieldName1,
                                                         Sort sortOrder1,
                                                         java.lang.String fieldName2,
                                                         Sort sortOrder2)

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

Parameters:

className - the class to get all objects from.

fieldName1 - the first field name to sort by.

sortOrder1 - how to sort the first field.

fieldName2 - the second field name to sort by.

sortOrder2 - how to sort the second field.

Returns:

a sorted RealmResults containing the objects. If no results where found an empty list is returned.

Throws:

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

allObjectsSorted

public RealmResults<DynamicRealmObject> allObjectsSorted(java.lang.String className,
                                                         java.lang.String[] fieldNames,
                                                         Sort[] sortOrders)

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

Parameters:

className - the class to get all objects from.

sortOrders - sort ascending if Sort.ASCENDING, sort descending if Sort.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 RealmResults<DynamicRealmObject> distinct(java.lang.String className,
                                                 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:

className - 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 RealmResults<DynamicRealmObject> distinctAsync(java.lang.String className,
                                                      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:

className - the Class to get objects of.

fieldName - the field name.

Returns:

immediately a 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 RealmResults<DynamicRealmObject> distinct(java.lang.String className,
                                                 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:

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

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
 
 

Specified by:

asObservable in class BaseRealm

Returns:

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

See Also:

RxJava and Realm