Class DynamicRealm

Atlas Device SDKs are deprecated. Refer to the deprecation page for details.

io.realm

java.lang.Object

io.realm.BaseRealm

io.realm.DynamicRealm

DynamicRealm is a dynamic variant of io.realm.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 io.realm.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. 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.

Tip

Nested Class Summary

Modifier and Type	Class and Description
`public static interface`	DynamicRealm.Transaction
`public abstract static`	DynamicRealm.Callback

Method Summary

Modifier and Type	Method and Description
public void	addChangeListener ( io.realm.RealmChangeListener<io.realm.DynamicRealm> listener ) Adds a change listener to the Realm.
public <any>	asFlowable () Returns an RxJava Flowable that monitors changes to this Realm.
public DynamicRealmObject	createEmbeddedObject ( String className, DynamicRealmObject parentObject, String parentProperty ) Instantiates and adds a new embedded object to the Realm.
public DynamicRealmObject	createObject ( String className, Object primaryKeyValue ) Creates an object with a given primary key.
public DynamicRealmObject	createObject ( String className ) Instantiates and adds a new object to the Realm.
public void	delete ( String className ) Deletes all objects of the specified class from the Realm.
public void	executeTransaction ( DynamicRealm.Transaction transaction ) Executes a given transaction on the DynamicRealm.
public RealmAsyncTask	executeTransactionAsync ( DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnSuccess onSuccess, DynamicRealm.Transaction.OnError onError ) Similar to executeTransactionAsync(Transaction) , but also accepts an OnSuccess and OnError callbacks.
public RealmAsyncTask	executeTransactionAsync ( DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnError onError ) Similar to executeTransactionAsync(Transaction) , but also accepts an OnError callback.
public RealmAsyncTask	executeTransactionAsync ( DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnSuccess onSuccess ) Similar to executeTransactionAsync(Transaction) , but also accepts an OnSuccess callback.
public RealmAsyncTask	executeTransactionAsync ( DynamicRealm.Transaction transaction ) Similar to executeTransaction(Transaction) but runs asynchronously on a worker thread.
public DynamicRealm	freeze () Returns a frozen snapshot of the current Realm.
public static DynamicRealm	getInstance ( RealmConfiguration configuration ) Realm static constructor that returns a dynamic variant of the Realm instance defined by provided io.realm.RealmConfiguration .
public static RealmAsyncTask	getInstanceAsync ( RealmConfiguration configuration, DynamicRealm.Callback callback ) The creation of the first Realm instance per RealmConfiguration in a process can take some time as all initialization code need to run at that point (Setting up the Realm, validating schemas and creating initial data).
public RealmSchema	getSchema () Returns the mutable schema for this Realm.
public boolean	isEmpty () Checks if this io.realm.Realm contains any objects.
public void	removeAllChangeListeners () Removes all user-defined change listeners.
public void	removeChangeListener ( io.realm.RealmChangeListener<io.realm.DynamicRealm> listener ) Removes the specified change listener.
public RealmQuery	where ( String className ) Returns a RealmQuery, which can be used to query the provided class.

Inherited Methods

Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize
Methods inherited from class io.realm.BaseRealm: setAutoRefresh , isAutoRefresh , refresh , isInTransaction , addListener , removeListener , asFlowable , removeAllListeners , writeCopyTo , writeEncryptedCopyTo , waitForChange , stopWaitForChange , beginTransaction , commitTransaction , cancelTransaction , freeze , isFrozen , getNumberOfActiveVersions , checkIfValid , checkAllowQueriesOnUiThread , checkAllowWritesOnUiThread , checkIfInTransaction , checkIfValidAndInTransaction , getPath , getConfiguration , getVersion , close , isClosed , isEmpty , getSchema , getSubscriptions , deleteAll , migrateRealm , finalize

Method Detail

addChangeListener

public void addChangeListener (

io.realm.RealmChangeListener<io.realm.DynamicRealm> listener

)

Adds a change listener to the Realm.The listeners will be executed when changes are committed by this or another thread.

Realm instances are cached per thread. For that reason it is important to remember to remove listeners again either using removeChangeListener(RealmChangeListener) or removeAllChangeListeners() . Not doing so can cause memory leaks.

Parameters

listener - the change listener.

Throws

IllegalArgumentException - if the change listener is null .

Tip

asFlowable

public <any> asFlowable ()

Returns an RxJava Flowable 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.

Items emitted from Realm Flowables are frozen (See freeze(). This means that they are immutable and can be read on any thread.

Realm Flowables always emit items from the thread holding the live Realm. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:

realm.asFlowable()
 .observeOn(Schedulers.computation())
 .map(rxRealm -> doExpensiveWork(rxRealm))
 .observeOn(AndroidSchedulers.mainThread())
 .subscribe( ... );

If you would like the asFlowable() to stop emitting items, you can instruct RxJava to only emit only the first item by using the first() operator:

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

Returns

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

Overrides

asFlowable in class BaseRealm

createEmbeddedObject

public DynamicRealmObject createEmbeddedObject (

String  className,
DynamicRealmObject  parentObject,
String  parentProperty

)

Instantiates and adds a new embedded object to the Realm.This method should only be used to create objects of types marked as embedded.

Parameters

className - the class name of the object to create.
parentObject - The parent object which should hold a reference to the embedded object. If the parent property is a list the embedded object will be added to the end of that list.
parentProperty - the property in the parent class which holds the reference.

Returns

the newly created embedded object.

Throws

IllegalArgumentException - if clazz is not an embedded class or if the property in the parent class cannot hold objects of the appropriate type.

Tip

createObject

public DynamicRealmObject createObject (

String className,

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

RealmException - if object could not be created due to the primary key being invalid.
IllegalStateException - if the model clazz does not have a primary key defined.
IllegalArgumentException - if the primaryKeyValue doesn't have a value that can be converted to the expected value.

public DynamicRealmObject createObject ( 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.

delete

public void delete ( String className )
Deletes all objects of the specified class from the Realm. Parameters `className` - the class for which all objects should be removed. Throws IllegalStateException - if the Realm is closed or called from an incorrect thread.

executeTransaction

public void executeTransaction (

DynamicRealm.Transaction transaction

)

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

Calling this method from the UI thread will throw a RealmException . Doing so may result in a drop of frames or even ANRs. We recommend calling this method from a non-UI thread or using executeTransactionAsync(Transaction) instead.

Parameters

transaction - Transaction to execute.

Throws

IllegalArgumentException - if the transaction is null .
RealmException - if called from the UI thread, unless an explicit opt-in has been declared in RealmConfiguration.Builder.allowWritesOnUiThread(boolean) .

executeTransactionAsync

public RealmAsyncTask executeTransactionAsync (

DynamicRealm.Transaction  transaction,
DynamicRealm.Transaction.OnSuccess  onSuccess,
DynamicRealm.Transaction.OnError  onError

)

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

Parameters

transaction - Transaction to execute.
onSuccess - callback invoked when the transaction succeeds.
onError - callback invoked when the transaction fails.

Returns

a RealmAsyncTask representing a cancellable task.

Throws

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

public RealmAsyncTask executeTransactionAsync ( DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnError onError )
Similar to executeTransactionAsync(Transaction) , but also accepts an OnError callback. Parameters `transaction` - Transaction to execute. `onError` - callback invoked when the transaction fails. Returns a RealmAsyncTask representing a cancellable task. Throws IllegalArgumentException - if the `transaction` is `null` , or if the realm is opened from another thread.

public RealmAsyncTask executeTransactionAsync ( DynamicRealm.Transaction transaction, DynamicRealm.Transaction.OnSuccess onSuccess )
Similar to executeTransactionAsync(Transaction) , but also accepts an OnSuccess callback. Parameters `transaction` - Transaction to execute. `onSuccess` - callback invoked when the transaction succeeds. Returns a RealmAsyncTask representing a cancellable task. Throws IllegalArgumentException - if the `transaction` is `null` , or if the realm is opened from another thread.

public RealmAsyncTask executeTransactionAsync ( DynamicRealm.Transaction transaction )
Similar to executeTransaction(Transaction) but runs asynchronously on a worker thread. Parameters `transaction` - Transaction to execute. Returns a RealmAsyncTask representing a cancellable task. Throws IllegalArgumentException - if the `transaction` is `null` , or if the Realm is opened from another thread.

freeze

public DynamicRealm freeze ()

Returns a frozen snapshot of the current Realm. This Realm can be read and queried from any thread without throwing an IllegalStateException . A frozen Realm has its own lifecycle and can be closed by calling close(), but fully closing the Realm that spawned the frozen copy will also close the frozen Realm.

Frozen data can be queried as normal, but trying to mutate it in any way or attempting to register any listener will throw an IllegalStateException .

Note: Keeping a large number of Realms with different versions alive can have a negative impact on the filesize of the Realm. In order to avoid such a situation, it is possible to set RealmConfiguration.Builder.maxNumberOfActiveVersions(long) .

Returns

a frozen copy of this Realm.

Overrides

freeze in class BaseRealm

getInstance

public static DynamicRealm getInstance (

RealmConfiguration configuration

)

Realm static constructor that returns a dynamic variant of the Realm instance defined by provided io.realm.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

RealmFileException - if an error happened when accessing the underlying Realm file.
IllegalArgumentException - if configuration argument is null .

Tip

getInstanceAsync

public static RealmAsyncTask getInstanceAsync (

RealmConfiguration configuration,

DynamicRealm.Callback callback

)

The creation of the first Realm instance per RealmConfiguration in a process can take some time as all initialization code need to run at that point (Setting up the Realm, validating schemas and creating initial data). This method places the initialization work in a background thread and deliver the Realm instance to the caller thread asynchronously after the initialization is finished.

Parameters

configuration - RealmConfiguration used to open the Realm.
callback - invoked to return the results.

Returns

a RealmAsyncTask representing a cancellable task.

Throws

IllegalArgumentException - if a null RealmConfiguration or a null Callback is provided.
IllegalStateException - if it is called from a non-Looper or android.app.IntentService thread.

Tip

getSchema

public RealmSchema getSchema ()
Returns the mutable schema for this Realm. Returns The RealmSchema for this Realm. Overrides `getSchema` in class BaseRealm

isEmpty

public boolean isEmpty ()
Checks if this io.realm.Realm contains any objects. Returns `true` if empty, @{code false} otherwise. Overrides `isEmpty` in class BaseRealm

removeAllChangeListeners

public void removeAllChangeListeners ()
Removes all user-defined change listeners. Throws IllegalStateException - if you try to remove listeners from a non-Looper Thread. Tip See also: io.realm.RealmChangeListener

removeChangeListener

public void removeChangeListener ( io.realm.RealmChangeListener<io.realm.DynamicRealm> listener )
Removes the specified change listener. Parameters `listener` - the change listener to be removed. Throws IllegalArgumentException - if the change listener is `null` . IllegalStateException - if you try to remove a listener from a non-Looper Thread. Tip See also: io.realm.RealmChangeListener

where

public RealmQuery where ( String className )
Returns a RealmQuery, which can be used to query the provided class. Parameters `className` - the class of the object which is to be queried. Returns a RealmQuery, which can be used to query for specific objects of provided type. Throws IllegalArgumentException - if the class doesn't exist. Tip See also: io.realm.RealmQuery

Back

DefaultCompactOnLaunchCallback

DynamicRealm.Callback

io.realm

Tip

See also:

Nested Class Summary

Method Summary

Inherited Methods

Method Detail

addChangeListener

Tip

See also:

asFlowable

createEmbeddedObject

Tip

See also:

createObject

delete

executeTransaction

executeTransactionAsync

freeze

getInstance

Tip

See also:

getInstanceAsync

Tip

See also:

getSchema

isEmpty

removeAllChangeListeners

Tip

See also:

removeChangeListener

Tip

See also:

where

Tip

See also: