Open & Close a Realm - Java SDK
On this page
- The Default Realm
- Local Realms
- Local Realm Configuration
- Open a Local Realm
- Read-Only Realms
- In-Memory Realms
- Dynamic Realms
- Synced Realms
- Synced Realm Configuration
- Open a Synced Realm While Online
- Open a Synced Realm While Offline
- Open a Synced Realm with a Flexible Sync Configuration
- Close a Realm
- Configure Which Classes to Include in Your Realm Schema
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
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
Use the readOnly() method when configuring your realm to make it read-only:
In-Memory Realms
To create a realm that runs entirely in memory without being written to a file, use inMemory() when configuring your realm:
Dynamic Realms
To open a Dynamic Realm with a mutable schema, use DynamicRealm:
Synced Realms
Synced realms use Realm Sync to store data both on the client device
and in your synced data source. Opening a synced realm works exactly
like opening a local realm, except you use SyncConfiguration
to customize the settings for synced realms.
Synced Realm Configuration
To configure settings for a realm, create a SyncConfiguration with a SyncConfiguration.Builder. The following example configures a synced realm with:
- partition-based Realm Sync
- synchronous reads explicitly allowed on the UI thread
- synchronous writes explicitly allowed on the UI thread
- explicit waiting for all backend changes to synchronize to the device before returning an open realm
- automatic compaction when launching the realm to save file space
Applications used in production environments should handle client reset errors. To learn more, see Reset a Client Realm.
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 Synced Realm While Online
To open a synced realm, call
getInstanceAsync(),
passing in a SyncConfiguration
object. The following code demonstrates how to create a realm with
specific sync settings created using a SyncConfiguration object:
The code above shows how to open the realm asynchronously by using getInstanceAsync(). You can also open a realm synchronously by using getInstance(), which returns an open realm before synchronizing all data from the backend. However, this may lead to temporary data inconsistencies while the remote data is downloaded, and is generally not recommended. You can use the waitForInitialRemoteData() configuration option to force the SDK to fetch remote data before opening the realm to avoid these inconsistencies.
The partition value specifies which subset of your data to sync. This is typically a user ID, project ID, store ID, or some other category identifier in your app that has particular relevance to the current user.
Open a Synced Realm While Offline
You can open a synced realm when offline with the exact same syntax that you use to open a synced realm while online. Not all SDKs follow this pattern, so cross-platform developers should consult the documentation for each SDK to learn more.
Open a Synced Realm with a Flexible Sync Configuration
When your application uses Flexible Sync, call
the initialSubscriptions()
sync configuration builder method
with an instance of
SyncConfiguration.InitialFlexibleSyncSubscriptions()
to open a synced realm. While partition-based Sync requires a partition
value when you instantiate your SyncConfiguration, you should omit
the partition value when you use Flexible Sync. In the configure() method, instantiate
an UnmanagedSubscription with a name and query using
Subscription.create().
Pass your new subscription
to the add() method of the MutableSubscriptionSet
parameter to add it to your subscriptions:
For more information about subscriptions, see Subscribe to Queryable Fields.
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 Database 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.
Libraries that include Realm Database 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.