DynamicRealm (Realm 0.86.0)

java.lang.Object
- io.realm.DynamicRealm

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable
```
public final class DynamicRealm
extends java.lang.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, 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.

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addChangeListener(RealmChangeListener listener)` Adds a change listener to the Realm.
`RealmResults<DynamicRealmObject>`	`allObjects(java.lang.String className)` Get all objects of a specific class name.
`RealmResults<DynamicRealmObject>`	`allObjectsSorted(java.lang.String className, java.lang.String[] fieldNames, Sort[] sortOrders)` Get all objects of a specific class name sorted by multiple fields.
`RealmResults<DynamicRealmObject>`	`allObjectsSorted(java.lang.String className, java.lang.String fieldName, Sort sortOrder)` Get 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)` Get all objects of a specific class name sorted by two specific field names.
`void`	`beginTransaction()` Starts a transaction, this must be closed with `BaseRealm.commitTransaction()` or aborted by `BaseRealm.cancelTransaction()`.
`void`	`cancelTransaction()` Reverts all writes (created, updated, or deleted objects) made in the current write transaction and end the transaction.
`void`	`clear(java.lang.String className)` 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 the Realm file defined by the given configuration.
`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.
`RealmResults<DynamicRealmObject>`	`distinct(java.lang.String className, java.lang.String fieldName)` Return a distinct set of objects of a specific class.
`RealmResults<DynamicRealmObject>`	`distinctAsync(java.lang.String className, java.lang.String fieldName)` Return a distinct set of objects of a specific class.
`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`.
`java.lang.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`	`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.
`void`	`setAutoRefresh(boolean autoRefresh)` Sets the auto-refresh status of the Realm instance.
`RealmQuery<DynamicRealmObject>`	`where(java.lang.String className)` Returns a RealmQuery, which can be used to query for the provided class.
`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

- 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.
    
    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
```
public void clear(java.lang.String className)
```
    Removes all objects of the specified class.
    
    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:
    
    RealmException - if any error happened during the transaction.
  - allObjects
```
public RealmResults<DynamicRealmObject> allObjects(java.lang.String className)
```
    Get 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)
```
    Get 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)
```
    Get 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)
```
    Get 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_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 RealmResults<DynamicRealmObject> distinct(java.lang.String className,
                                                 java.lang.String fieldName)
```
    Return a distinct set of objects of a specific class. As a Realm is unordered, it is undefined which objects are returned in case of multiple occurrences.
    
    Parameters:
    
    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 name does not exist or the field is not indexed.
  - distinctAsync
```
public RealmResults<DynamicRealmObject> distinctAsync(java.lang.String className,
                                                      java.lang.String fieldName)
```
    Return a distinct set of objects of a specific class. As a Realm is unordered, it is undefined which objects are returned in case of multiple occurrences. This method is only available from a Looper thread.
    
    Parameters:
    
    className - the Class to get objects of.
    
    fieldName - the field name.
    
    Returns:
    
    immediately an empty RealmResults. Users need to register a listener RealmResults.addChangeListener(RealmChangeListener) to be notified when the query completes.
    
    Throws:
    
    java.lang.IllegalArgumentException - if a field name does not exist or the field is not indexed.
  - 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.
  - 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.
    
    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.
    
    See Also:
    
    RealmChangeListener, addChangeListener(RealmChangeListener)
  - removeAllChangeListeners
```
public void removeAllChangeListeners()
```
    Removes all user-defined change listeners.
    
    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.
  - 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.
  - 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
  - isClosed
```
public boolean isClosed()
```
    Checks if the Realm instance has already been closed.
    
    Returns:
    
    true if closed, false otherwise.
  - 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.
  - compactRealm
```
public static boolean compactRealm(RealmConfiguration configuration)
```
    Compacts the Realm file defined by the given configuration.

Class DynamicRealm

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

createObject

createObject

where

clear

executeTransaction

allObjects

allObjectsSorted

allObjectsSorted

allObjectsSorted

distinct

distinctAsync

setAutoRefresh

isAutoRefresh

isInTransaction

addChangeListener

removeChangeListener

removeAllChangeListeners

writeCopyTo

writeEncryptedCopyTo

refresh

beginTransaction

commitTransaction

cancelTransaction

getPath

getConfiguration

getVersion

close

isClosed

isEmpty

getSchema

compactRealm