io.realm

Class DynamicRealm

java.lang.Object

io.realm.DynamicRealm

All Implemented Interfaces:

Closeable, AutoCloseable

public final class DynamicRealm
extends Object

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. 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 class	io.realm.BaseRealm.RealmObjectContext
static interface	DynamicRealm.Transaction Encapsulates a Realm transaction.

Field Summary

Fields

Modifier and Type	Field and Description
static io.realm.BaseRealm.ThreadLocalRealmObjectContext	objectContext

Method Summary

Modifier and Type	Method and Description
void	addChangeListener(RealmChangeListener<DynamicRealm> listener) Adds a change listener to the Realm.
<any>	asObservable() Returns an RxJava Observable that monitors changes to this Realm.
void	beginTransaction() Starts a transaction which must be closed by 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	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.
DynamicRealmObject	createObject(String className) Instantiates and adds a new object to the Realm.
DynamicRealmObject	createObject(String className, Object primaryKeyValue) Creates an object with a given primary key.
void	delete(String className) Deletes all objects of the specified class from the Realm.
void	deleteAll() Deletes all objects from this Realm.
void	executeTransaction(DynamicRealm.Transaction transaction) Executes a given transaction on the DynamicRealm.
RealmConfiguration	getConfiguration() Returns the RealmConfiguration for this Realm.
static DynamicRealm	getInstance(RealmConfiguration configuration) Realm static constructor that returns a dynamic variant of the Realm instance defined by provided RealmConfiguration.
String	getPath() Returns the canonical path to where this Realm is persisted on disk.
RealmSchema	getSchema() Returns the schema for this Realm.
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.
void	removeAllChangeListeners() Removes all user-defined change listeners.
void	removeChangeListener(RealmChangeListener<? extends io.realm.BaseRealm> listener) Removes the specified change listener.
void	setAutoRefresh(boolean autoRefresh) Sets the auto-refresh status of the Realm instance.
void	stopWaitForChange() Makes any current waitForChange() return false immediately.
boolean	waitForChange() Blocks the current thread until new changes to the Realm are available or stopWaitForChange() is called from another thread.
RealmQuery<DynamicRealmObject>	where(String className) Returns a RealmQuery, which can be used to query the provided class.
void	writeCopyTo(File destination) Writes a compacted copy of the Realm to the given destination File.
void	writeEncryptedCopyTo(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

objectContext

public static final io.realm.BaseRealm.ThreadLocalRealmObjectContext objectContext

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:

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

IllegalArgumentException - if configuration argument is null.

See Also:

for details on how to configure a Realm.

createObject

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.

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 an primary key defined.

IllegalArgumentException - if the primaryKeyValue doesn't have a value that can be converted to the expected value.

where

public RealmQuery<DynamicRealmObject> 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.

See Also:

RealmQuery

addChangeListener

public void addChangeListener(RealmChangeListener<DynamicRealm> listener)

Adds a change listener to the Realm.

The listeners will be executed on every loop of a Handler thread if 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.

IllegalStateException - if you try to register a listener from a non-Looper or IntentService thread.

See Also:

RealmChangeListener, removeChangeListener(RealmChangeListener), removeAllChangeListeners()

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.

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

Parameters:

transaction - DynamicRealm.Transaction to execute.

Throws:

IllegalArgumentException - if the transaction is null.

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

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 RealmObject 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 on a Looper enabled thread.

Parameters:

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

Throws:

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.

removeChangeListener

public void removeChangeListener(RealmChangeListener<? extends io.realm.BaseRealm> 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.

See Also:

RealmChangeListener

removeAllChangeListeners

public void removeAllChangeListeners()

Removes all user-defined change listeners.

Throws:

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

See Also:

RealmChangeListener

writeCopyTo

public void writeCopyTo(File destination)

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:

RealmFileException - if an error happened when accessing the underlying Realm file or writing to the destination file.

writeEncryptedCopyTo

public void writeEncryptedCopyTo(File destination,
                                 byte[] key)

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:

IllegalArgumentException - if destination argument is null.

RealmFileException - if an error happened when accessing the underlying Realm file or writing to the destination file.

waitForChange

public boolean waitForChange()

Blocks the current thread until new changes to the Realm are available or stopWaitForChange() is called from another thread. Once stopWaitForChange is called, all future calls to this method will return false immediately.

Returns:

true if the Realm was updated to the latest version, false if it was cancelled by calling stopWaitForChange.

Throws:

IllegalStateException - if calling this from within a transaction or from a Looper thread.

RealmMigrationNeededException - on typed Realm if the latest version contains incompatible schema changes.

stopWaitForChange

public void stopWaitForChange()

Makes any current waitForChange() return false immediately. Once this is called, all future calls to waitForChange will immediately return false.

This method is thread-safe and should _only_ be called from another thread than the one that called waitForChange.

Throws:

IllegalStateException - if the Realm instance has already been closed.

beginTransaction

public void beginTransaction()

Starts a transaction which must be closed by BaseRealm.commitTransaction() or aborted by BaseRealm.cancelTransaction(). Transactions are used to atomically create, update and delete objects within a Realm.

Before beginning a transaction, the Realm instance is updated to the latest version in order to include all changes from other threads. This update does not trigger any registered RealmChangeListener.

It is therefore recommended to query for the items that should be modified from inside the transaction. Otherwise there is a risk that some of the results have been deleted or modified when the transaction begins.

 
 // Don't do this
 RealmResults<Person> persons = realm.where(Person.class).findAll();
 realm.beginTransaction();
 persons.first().setName("John");
 realm.commitTransaction();

 // Do this instead
 realm.beginTransaction();
 RealmResults<Person> persons = realm.where(Person.class).findAll();
 persons.first().setName("John");
 realm.commitTransaction();
 
 

Notice: it is not possible to nest transactions. If you start a transaction within a transaction an exception is thrown.

Throws:

RealmMigrationNeededException - on typed Realm if the latest version contains incompatible schema changes.

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 update their objects and RealmResults 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 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 Closeable

Specified by:

close in interface AutoCloseable

Throws:

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:

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

Deletes all objects from this Realm.

Throws:

IllegalStateException - if the corresponding Realm is closed or called from an incorrect thread.