Open & Close a Realm - Java SDK
On this page
Interacting with realms in an Android application uses the following high-level series of steps:
Create a configuration for the realm you want to open.
Open the realm using the config.
Close the realm to free up resources when you're finished.
The Default Realm
You can save any RealmConfiguration or SyncConfiguration as the default for your application using the setDefaultConfiguration() method:
You can then use getDefaultConfiguration() to access that configuration, or getDefaultInstance() to open a realm with that configuration:
Local Realms
Local realms store data only on the client device. You can customize
the settings for a local realm with RealmConfiguration.
Local Realm Configuration
To configure settings for a realm, create a RealmConfiguration with a RealmConfiguration.Builder. The following example configures a local realm with:
the file name "alternate-realm"
synchronous reads explicitly allowed on the UI thread
synchronous writes explicitly allowed on the UI thread
automatic compaction when launching the realm to save file space
Important
Synchronous Reads and Writes on the UI Thread
By default, you can only read or write to a realm in your
application's UI thread using
asynchronous transactions. That is,
you can only use Realm methods whose name ends with the word
Async in the main thread of your Android application unless you
explicitly allow the use of synchronous methods.
This restriction exists for the benefit of your application users:
performing read and write operations on the UI thread can lead to
unresponsive or slow UI interactions, so it's usually best to handle
these operations either asynchronously or in a background thread.
However, if your application requires the use of synchronous
realm reads or writes on the UI thread, you can explicitly allow
the use of synchronous methods with the following
SyncConfiguration options:
Open a Local Realm
To open a realm, create a
RealmConfiguration with
RealmConfiguration.Builder and
pass the resulting RealmConfiguration to
getInstance()
or getInstanceAsync():
Read-Only Realms
It's sometimes useful to ship a prepared realm file with your app
that contains shared data that does not frequently change. You can use
the readOnly()
method when configuring your realm to make it read-only. This can
prevent accidental writes to the realm and causes the realm to
throw an IllegalStateException if a write occurs.
Warning
Read-Only Realm Files are Writeable
Read-only realms are only enforced as read-only in process. The realm file itself is still writeable.
In-Memory Realms
You can create a realm that runs entirely in memory without being written to a file. When memory runs low on an Android device, in-memory realms may swap temporarily from main memory to disk space. The SDK deletes all files created by an in-memory realm when:
the realm closes
all references to that realm fall out of scope
To create an in-memory realm, use inMemory() when configuring your realm:
Dynamic Realms
Conventional realms define a schema using RealmObject subclasses
or the RealmModel interface. A
DynamicRealm uses strings to
define a schema at runtime. Opening a dynamic realm uses the same
configuration as a conventional realm, but dynamic realms ignore
all configured schema, migration, and schema versions.
Dynamic realms offer flexibility at the expense of type safety and performance. As a result, only use dynamic realms when that flexibility is required, such as during migrations, manual client resets, and when working with string-based data like CSV files or JSON.
To open a Dynamic Realm with a mutable schema, use DynamicRealm:
Close a Realm
It is important to remember to call the close() method when done with a
realm instance to free resources. Neglecting to close realms can lead to an
OutOfMemoryError.
Configure Which Classes to Include in Your Realm Schema
Realm modules are collections of Realm object models. Specify a module or modules when opening a realm to control which classes Realm should include in your schema. If you do not specify a module, Realm uses the default module, which includes all Realm objects defined in your application.
Note
Libraries that include Realm must expose and use their
schema through a module. Doing so prevents the library from
generating the default RealmModule, which would conflict with
the default RealmModule used by any app that includes the library.
Apps using the library access library classes through the module.