diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/OpenARealmTest.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/OpenARealmTest.kt index cc7eff3d940..39df32c3db5 100644 --- a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/OpenARealmTest.kt +++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/OpenARealmTest.kt @@ -11,100 +11,195 @@ import io.realm.kotlin.mongodb.syncSession import io.realm.kotlin.types.RealmObject import io.realm.kotlin.types.annotations.PrimaryKey import org.mongodb.kbson.ObjectId +import kotlin.test.AfterTest import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertTrue import kotlin.time.Duration.Companion.seconds // :replace-start: { // "terms": { +// "TMP_PATH": "\"my-directory-path\"", // "local2": "local", // "yourFlexAppId": "YOUR_APP_ID" // } // } class OpenARealmTest: RealmTest() { - - class Toad: RealmObject { + // :snippet-start: open-realm-object-schemas + class Frog : RealmObject { @PrimaryKey var _id: ObjectId = ObjectId() var name: String = "" } + + class Person : RealmObject { + var _id: Int? = null + var name: String = "" + } + // :snippet-end: + + @AfterTest + fun cleanup() { + + } + @Test - fun openAndCloseARealmTest() { + fun openAndCloseDefaultRealmTest() { runBlocking { - // :snippet-start: open-a-realm - val config = RealmConfiguration.Builder(setOf(Toad::class)) - // :remove-start: - .directory("/tmp/") // default location for jvm is... in the project root - // :remove-end: - .build() + // :snippet-start: open-a-default-realm + // Creates a realm with default configuration values + val config = RealmConfiguration.create( + // Pass object classes for the realm schema + schema = setOf(Frog::class, Person::class) + ) + + // Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // :snippet-end: + assertTrue(config.path.contains("default.realm")) + assertTrue(config.schema.contains(Frog::class)) // :snippet-start: close-a-realm realm.close() // :snippet-end: + assertTrue(realm.isClosed()) + Realm.deleteRealm(config) + } + } + + @Test + fun openConfiguredRealmTest() { + runBlocking { + // :snippet-start: open-a-realm + // Create a realm configuration with optional arguments + val config = RealmConfiguration.Builder( + schema = setOf(Frog::class, Person::class) + ) + .name("my-realm.realm") + .directory(TMP_PATH) + .build() + + // Open the realm with the configuration object + val realm = Realm.open(config) + Log.v("Successfully opened realm: ${realm.configuration.name}") + // :snippet-end: + // :snippet-start: find-realm-path + val realmPath = realm.configuration.path + Log.v("Realm path: $realmPath") + // :snippet-end: + assertTrue(realmPath.contains("tmp")) + assertEquals("my-realm.realm", config.name) + realm.close() + assertTrue(realm.isClosed()) + Realm.deleteRealm(config) } } + @Test fun deleteRealmIfMigrationNeeded() { - val REALM_NAME = getRandom() runBlocking { // :snippet-start: delete-realm-if-migration-needed - val config = RealmConfiguration.Builder(setOf(Toad::class)) - // :remove-start: - .name(REALM_NAME) - // :remove-end: + val config = RealmConfiguration.Builder( + schema = setOf(Frog::class) + ) .deleteRealmIfMigrationNeeded() .build() val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // :snippet-end: + assertTrue(config.deleteRealmIfMigrationNeeded) + realm.close() + assertTrue(realm.isClosed()) + Realm.deleteRealm(config) } } + @Test - fun onAnInMemoryRealm() { + fun openAnInMemoryRealmTest() { runBlocking { // :snippet-start: open-an-in-memory-realm - val config = RealmConfiguration.Builder(setOf(Toad::class)) + // Create the in-memory realm configuration + val config = RealmConfiguration.Builder( + schema = setOf(Frog::class, Person::class) + ) .inMemory() .build() + // Open the realm with the configuration object val realm = Realm.open(config) - Log.v("Successfully opened an in memory realm") + Log.v("Successfully opened an in-memory realm") // :snippet-end: + assertTrue(config.inMemory) realm.close() + assertTrue(realm.isClosed()) + Realm.deleteRealm(config) + } + } + + @Test + fun initialDataCallbackTest() { + runBlocking { + // :snippet-start: initial-data-callback + val config = RealmConfiguration.Builder( + schema = setOf(Frog::class) + ) + .initialData { + copyToRealm(Frog().apply { + name = "Kermit" + }) + } + .inMemory() // :remove: + .build() + + val realm = Realm.open(config) + Log.v("Successfully opened realm: ${realm.configuration.name}") + + val initialFrog = realm.query().find().first() + Log.v("Realm initialized with: ${initialFrog.name}" ) + // :snippet-end: + assertEquals(1, realm.query().find().size) + assertEquals("Kermit", initialFrog.name) + realm.close() + assertTrue(realm.isClosed()) + Realm.deleteRealm(config) } } @Test fun syncToLocalRealm() { + val credentials = Credentials.anonymous(reuseExisting = false) // :snippet-start: sync-to-local-realm // Instantiate the synced realm with your App ID val app = App.create(yourFlexAppId) runBlocking { - val user = app.login(Credentials.anonymous()) + val user = app.login(credentials) // Create the synced realm configuration - val syncConfig = SyncConfiguration.Builder(user, setOf(Toad::class)) + val syncConfig = SyncConfiguration.Builder(user, setOf(Frog::class)) .initialSubscriptions { realm -> - add(realm.query(),"subscription name") + add(realm.query(),"all-frogs") } .build() // Open the synced realm and add data to it val syncRealm = Realm.open(syncConfig) - Log.v("Successfully opened realm: ${syncRealm.configuration}") + Log.v("Successfully opened realm: ${syncRealm.configuration.name}") syncRealm.write { - this.copyToRealm(Toad().apply { + this.copyToRealm(Frog().apply { name = "Kermit" }) } // Wait for write to sync syncRealm.syncSession.uploadAllLocalChanges(30.seconds) + // :remove-start: + val syncFrog = syncRealm.query().find().first() + assertEquals("Kermit", syncFrog.name) + // :remove-end: // Create the local realm - val localConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local.realm") .build() // Copy data from synced realm to the new realm @@ -115,13 +210,19 @@ class OpenARealmTest: RealmTest() { // Open the new local realm val localRealm = Realm.open(localConfig) - // Copied Toad object is available in the new realm - val toad: Toad = - localRealm.query().find().first() - Log.v("Copied Toad: ${toad.name}") + // Copied Frog object is available in the new realm + val frog = localRealm.query().find().first() + Log.v("Copied Frog: ${frog.name}") + assertEquals("Kermit", frog.name) // :remove: localRealm.close() - Realm.deleteRealm(localConfig) // :remove: + // :remove-start: + assertTrue(syncRealm.isClosed()) + assertTrue(localRealm.isClosed()) + app.close() + Realm.deleteRealm(localConfig) + //Realm.deleteRealm(syncConfig) // [RLM_ERR_DELETE_OPENED_REALM]: Cannot delete files of an open Realm + // :remove-end: } // :snippet-end: } @@ -130,21 +231,27 @@ class OpenARealmTest: RealmTest() { // :snippet-start: in-memory-to-local-realm runBlocking { // Create the in-memory realm - val inMemoryConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val inMemoryConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("inMemory.realm") .inMemory() .build() // Open the realm and add data to it val inMemoryRealm = Realm.open(inMemoryConfig) + assertTrue(inMemoryRealm.configuration.inMemory) // :remove: + inMemoryRealm.write { - this.copyToRealm(Toad().apply { + this.copyToRealm(Frog().apply { name = "Kermit" }) } + // :remove-start: + val inMemoryFrog = inMemoryRealm.query().find().first() + assertEquals("Kermit", inMemoryFrog.name) + // :remove-end: // Create the local realm - val localConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local2.realm") .build() // Copy data from `inMemoryRealm` to the new realm @@ -155,23 +262,28 @@ class OpenARealmTest: RealmTest() { // Open the new local realm val localRealm = Realm.open(localConfig) - // Copied Toad object is available in the new realm - val toad: Toad = - localRealm.query().find().first() - Log.v("Copied Toad: ${toad.name}") + // Copied Frog object is available in the new realm + val frog = localRealm.query().find().first() + Log.v("Copied Frog: ${frog.name}") + assertEquals("Kermit", frog.name) // :remove: localRealm.close() - Realm.deleteRealm(inMemoryConfig) // :remove: - Realm.deleteRealm(localConfig) // :remove: + // :remove-start: + assertTrue(inMemoryRealm.isClosed()) + assertTrue(localRealm.isClosed()) + Realm.deleteRealm(inMemoryConfig) + Realm.deleteRealm(localConfig) + // :remove-end: } // :snippet-end: } @Test fun unencryptedToEncryptedRealm() { + val encryptionKey = getEncryptionKey() // :snippet-start: unencrypted-to-encrypted-realm runBlocking { // Create the unencrypted realm - val unencryptedConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val unencryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("unencrypted.realm") .build() @@ -179,7 +291,7 @@ class OpenARealmTest: RealmTest() { val unencryptedRealm = Realm.open(unencryptedConfig) unencryptedRealm.write { - this.copyToRealm(Toad().apply { + this.copyToRealm(Frog().apply { name = "Kermit" }) } @@ -187,9 +299,9 @@ class OpenARealmTest: RealmTest() { // ... Generate encryption key ... // Create the encrypted realm - val encryptedConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val encryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("encrypted.realm") - .encryptionKey(getEncryptionKey()) + .encryptionKey(encryptionKey) .build() // Copy data from `unencryptedRealm` to the new realm @@ -202,16 +314,22 @@ class OpenARealmTest: RealmTest() { // Open the new encrypted realm val encryptedRealm = Realm.open(encryptedConfig) - // Copied Toad object is available in the new realm - val toad: Toad = - encryptedRealm.query().find().first() - Log.v("Copied Toad: ${toad.name}") - + // Copied Frog object is available in the new realm + val frog = encryptedRealm.query().find().first() + Log.v("Copied Frog: ${frog.name}") + // :remove-start: + assertEquals("Kermit", frog.name) + assertEquals(encryptionKey, encryptedRealm.configuration.encryptionKey) + // :remove-end: encryptedRealm.close() - Realm.deleteRealm(unencryptedConfig) // :remove: - Realm.deleteRealm(encryptedConfig) // :remove: + // :remove-start: + assertTrue(encryptedRealm.isClosed()) + assertTrue(unencryptedRealm.isClosed()) + Realm.deleteRealm(unencryptedConfig) + Realm.deleteRealm(encryptedConfig) + // :remove-end: } // :snippet-end: } } - // :replace-end: \ No newline at end of file + // :replace-end: \ No newline at end of file diff --git a/snooty.toml b/snooty.toml index f3713d98517..ffbec297c27 100644 --- a/snooty.toml +++ b/snooty.toml @@ -52,7 +52,6 @@ toc_landing_pages = [ "/sdk/kotlin/users", "/sdk/kotlin/realm-database", "/sdk/kotlin/realm-database/schemas", - "/sdk/kotlin/realm-database/realm-files", "/sdk/kotlin/realm-database/write-transactions", "/sdk/kotlin/sync", "/sdk/web", diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.delete-realm-if-migration-needed.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.delete-realm-if-migration-needed.kt index 35fd0515da4..550c17bbdc1 100644 --- a/source/examples/generated/kotlin/OpenARealmTest.snippet.delete-realm-if-migration-needed.kt +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.delete-realm-if-migration-needed.kt @@ -1,4 +1,6 @@ -val config = RealmConfiguration.Builder(setOf(Toad::class)) +val config = RealmConfiguration.Builder( + schema = setOf(Frog::class) +) .deleteRealmIfMigrationNeeded() .build() val realm = Realm.open(config) diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.find-realm-path.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.find-realm-path.kt new file mode 100644 index 00000000000..b44bc5c2d59 --- /dev/null +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.find-realm-path.kt @@ -0,0 +1,2 @@ +val realmPath = realm.configuration.path +Log.v("Realm path: $realmPath") diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.in-memory-to-local-realm.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.in-memory-to-local-realm.kt index 098e90fa6a7..b432b1659b1 100644 --- a/source/examples/generated/kotlin/OpenARealmTest.snippet.in-memory-to-local-realm.kt +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.in-memory-to-local-realm.kt @@ -1,20 +1,21 @@ runBlocking { // Create the in-memory realm - val inMemoryConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val inMemoryConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("inMemory.realm") .inMemory() .build() // Open the realm and add data to it val inMemoryRealm = Realm.open(inMemoryConfig) + inMemoryRealm.write { - this.copyToRealm(Toad().apply { + this.copyToRealm(Frog().apply { name = "Kermit" }) } // Create the local realm - val localConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local.realm") .build() // Copy data from `inMemoryRealm` to the new realm @@ -25,10 +26,9 @@ runBlocking { // Open the new local realm val localRealm = Realm.open(localConfig) - // Copied Toad object is available in the new realm - val toad: Toad = - localRealm.query().find().first() - Log.v("Copied Toad: ${toad.name}") + // Copied Frog object is available in the new realm + val frog = localRealm.query().find().first() + Log.v("Copied Frog: ${frog.name}") localRealm.close() } diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.initial-data-callback.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.initial-data-callback.kt new file mode 100644 index 00000000000..85719639e36 --- /dev/null +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.initial-data-callback.kt @@ -0,0 +1,15 @@ +val config = RealmConfiguration.Builder( + schema = setOf(Frog::class) +) + .initialData { + copyToRealm(Frog().apply { + name = "Kermit" + }) + } + .build() + +val realm = Realm.open(config) +Log.v("Successfully opened realm: ${realm.configuration.name}") + +val initialFrog = realm.query().find().first() +Log.v("Realm initialized with: ${initialFrog.name}" ) diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.open-a-default-realm.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-a-default-realm.kt new file mode 100644 index 00000000000..51adc0d594f --- /dev/null +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-a-default-realm.kt @@ -0,0 +1,9 @@ +// Creates a realm with default configuration values +val config = RealmConfiguration.create( + // Pass object classes for the realm schema + schema = setOf(Frog::class, Person::class) +) + +// Open the realm with the configuration object +val realm = Realm.open(config) +Log.v("Successfully opened realm: ${realm.configuration.name}") diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.open-a-realm.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-a-realm.kt index c66d46e25cd..9dc63cf97bd 100644 --- a/source/examples/generated/kotlin/OpenARealmTest.snippet.open-a-realm.kt +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-a-realm.kt @@ -1,4 +1,11 @@ -val config = RealmConfiguration.Builder(setOf(Toad::class)) +// Create a realm configuration with optional arguments +val config = RealmConfiguration.Builder( + schema = setOf(Frog::class, Person::class) +) + .name("my-realm.realm") + .directory("my-directory-path") .build() + +// Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.open-an-in-memory-realm.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-an-in-memory-realm.kt index b162cc0549e..937275fe829 100644 --- a/source/examples/generated/kotlin/OpenARealmTest.snippet.open-an-in-memory-realm.kt +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-an-in-memory-realm.kt @@ -1,6 +1,10 @@ -val config = RealmConfiguration.Builder(setOf(Toad::class)) +// Create the in-memory realm configuration +val config = RealmConfiguration.Builder( + schema = setOf(Frog::class, Person::class) +) .inMemory() .build() +// Open the realm with the configuration object val realm = Realm.open(config) -Log.v("Successfully opened an in memory realm") +Log.v("Successfully opened an in-memory realm") diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.open-realm-object-schemas.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-realm-object-schemas.kt new file mode 100644 index 00000000000..24c1bf03099 --- /dev/null +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.open-realm-object-schemas.kt @@ -0,0 +1,10 @@ +class Frog : RealmObject { + @PrimaryKey + var _id: ObjectId = ObjectId() + var name: String = "" +} + +class Person : RealmObject { + var _id: Int? = null + var name: String = "" +} diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.sync-to-local-realm.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.sync-to-local-realm.kt index d3c52706ccd..e6a88174e9d 100644 --- a/source/examples/generated/kotlin/OpenARealmTest.snippet.sync-to-local-realm.kt +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.sync-to-local-realm.kt @@ -2,20 +2,20 @@ val app = App.create(YOUR_APP_ID) runBlocking { - val user = app.login(Credentials.anonymous()) + val user = app.login(credentials) // Create the synced realm configuration - val syncConfig = SyncConfiguration.Builder(user, setOf(Toad::class)) + val syncConfig = SyncConfiguration.Builder(user, setOf(Frog::class)) .initialSubscriptions { realm -> - add(realm.query(),"subscription name") + add(realm.query(),"all-frogs") } .build() // Open the synced realm and add data to it val syncRealm = Realm.open(syncConfig) - Log.v("Successfully opened realm: ${syncRealm.configuration}") + Log.v("Successfully opened realm: ${syncRealm.configuration.name}") syncRealm.write { - this.copyToRealm(Toad().apply { + this.copyToRealm(Frog().apply { name = "Kermit" }) } @@ -23,7 +23,7 @@ runBlocking { syncRealm.syncSession.uploadAllLocalChanges(30.seconds) // Create the local realm - val localConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local.realm") .build() // Copy data from synced realm to the new realm @@ -34,10 +34,9 @@ runBlocking { // Open the new local realm val localRealm = Realm.open(localConfig) - // Copied Toad object is available in the new realm - val toad: Toad = - localRealm.query().find().first() - Log.v("Copied Toad: ${toad.name}") + // Copied Frog object is available in the new realm + val frog = localRealm.query().find().first() + Log.v("Copied Frog: ${frog.name}") localRealm.close() } diff --git a/source/examples/generated/kotlin/OpenARealmTest.snippet.unencrypted-to-encrypted-realm.kt b/source/examples/generated/kotlin/OpenARealmTest.snippet.unencrypted-to-encrypted-realm.kt index 58128c4c320..8f5b97b0363 100644 --- a/source/examples/generated/kotlin/OpenARealmTest.snippet.unencrypted-to-encrypted-realm.kt +++ b/source/examples/generated/kotlin/OpenARealmTest.snippet.unencrypted-to-encrypted-realm.kt @@ -1,6 +1,6 @@ runBlocking { // Create the unencrypted realm - val unencryptedConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val unencryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("unencrypted.realm") .build() @@ -8,7 +8,7 @@ runBlocking { val unencryptedRealm = Realm.open(unencryptedConfig) unencryptedRealm.write { - this.copyToRealm(Toad().apply { + this.copyToRealm(Frog().apply { name = "Kermit" }) } @@ -16,9 +16,9 @@ runBlocking { // ... Generate encryption key ... // Create the encrypted realm - val encryptedConfig = RealmConfiguration.Builder(setOf(Toad::class)) + val encryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("encrypted.realm") - .encryptionKey(getEncryptionKey()) + .encryptionKey(encryptionKey) .build() // Copy data from `unencryptedRealm` to the new realm @@ -31,10 +31,8 @@ runBlocking { // Open the new encrypted realm val encryptedRealm = Realm.open(encryptedConfig) - // Copied Toad object is available in the new realm - val toad: Toad = - encryptedRealm.query().find().first() - Log.v("Copied Toad: ${toad.name}") - + // Copied Frog object is available in the new realm + val frog = encryptedRealm.query().find().first() + Log.v("Copied Frog: ${frog.name}") encryptedRealm.close() } diff --git a/source/sdk/kotlin/realm-database/realm-files.txt b/source/sdk/kotlin/realm-database/realm-files.txt index b57029e9b94..a17bc23bbea 100644 --- a/source/sdk/kotlin/realm-database/realm-files.txt +++ b/source/sdk/kotlin/realm-database/realm-files.txt @@ -1,5 +1,3 @@ -.. _kotlin-realm-files: - =============================== Manage Realm Files - Kotlin SDK =============================== @@ -12,43 +10,3 @@ Manage Realm Files - Kotlin SDK Delete a Realm Encrypt a Realm Bundle a Realm - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -A **realm** is the core data structure used to organize data in -Realm. A realm is a collection of the objects that you use -in your application, called Realm objects, as well as additional metadata -that describe the objects. To learn how to define a Realm object, see -:ref:`Define a Realm Object Schema `. - -When you :ref:`open a realm `, you can include configuration that specifies additional details -about how to configure the realm file. This includes things like: - -- Pass a file path or in-memory identifier to customize how the realm is stored on device -- Provide a logged-in user and Sync details to use Sync with the realm -- Specify the realm use only a subset of your app's classes -- Whether and when to compact a realm to reduce its file size -- Pass an encryption key to encrypt a realm -- Provide a schema version or migration block when making schema changes - -.. _kotlin-realm-file: - -Realm Files ------------ - -Realm stores a binary encoded version of every object and type in a -realm in a single ``.realm`` file. The file is located at a specific -path that you can define when you open the realm. -You can open, view, and edit the contents of these files with -:ref:`realm-studio`. - -Realm also creates additional files for each realm. -To learn more about these files, see :ref:`Realm Internals -`. Deleting these files has important implications. - -For more information about deleting ``.realm`` or auxiliary files, refer to -:ref:`Delete a Realm `. diff --git a/source/sdk/kotlin/realm-database/realm-files/delete-a-realm.txt b/source/sdk/kotlin/realm-database/realm-files/delete-a-realm.txt index 0c177c41247..a7d22e917c8 100644 --- a/source/sdk/kotlin/realm-database/realm-files/delete-a-realm.txt +++ b/source/sdk/kotlin/realm-database/realm-files/delete-a-realm.txt @@ -46,4 +46,8 @@ file if a migration is required. Then, you can create objects that match the new schema instead of writing migration blocks for development or test data. .. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.delete-realm-if-migration-needed.kt - :language: kotlin \ No newline at end of file + :language: kotlin + +.. important:: Do Not Use ``deleteRealmIfMigrationNeeded`` in Production + + Never release an app to production with this flag set to ``true``. diff --git a/source/sdk/kotlin/realm-database/realm-files/open-and-close-a-realm.txt b/source/sdk/kotlin/realm-database/realm-files/open-and-close-a-realm.txt index b7f7f8d9fa6..8f8c53f4345 100644 --- a/source/sdk/kotlin/realm-database/realm-files/open-and-close-a-realm.txt +++ b/source/sdk/kotlin/realm-database/realm-files/open-and-close-a-realm.txt @@ -10,39 +10,81 @@ Configure & Open a Realm - Kotlin SDK :depth: 2 :class: singlecol -.. note:: Automatic Compaction of Realm File Size +This page describes realm files and how to open and close a realm that only +persists data locally. To open a realm that synchronizes data with Atlas +using Device Sync, refer to :ref:`Open a Synced Realm +`. + +.. _kotlin-realm-files: +.. _kotlin-realm-file: + +Realm Files +----------- + +A **realm** is the core data structure used to organize data in +Realm. Each realm is a collection of Realm objects: the objects +that you use in your application as well as additional metadata that +describe those objects. Learn how to :ref:``. + +Realm stores a binary-encoded version of every object and type in a realm +in a single ``.realm`` file. When you open a realm, Realm creates the +``.realm`` file if it doesn't already exist. The file is located at a specific +path, which you can define when you open the realm. Realm also creates +additional auxiliary files for each realm, such as lock and management files. +To learn more about these files, refer to :ref:``. +Note that deleting these files has important implications. +For more information about deleting ``.realm`` or auxiliary files, refer to +:ref:`Delete a Realm `. + +.. tip:: Work with Realm Files in Realm Studio + + You can open, view, and edit the contents of realm files with :ref:`realm-studio`. + +If you don't want to create a ``.realm`` file or its associated auxiliary +files, you can open an in-memory realm. +Refer to the :ref:`` section for +more information. - .. versionadded:: 1.6.0 - - Realm automatically compacts files in the background by continuously - reallocating data in the file and removing unused file space. Realm will - automatically compact the file only when the file is not being accessed. +.. _kotlin-open-a-realm: Open a Realm ------------ -Use -`RealmConfiguration <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__ -to control the specifics of your realm that you would like to open. +To open a realm, create a `RealmConfiguration +<{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__ +object that defines the details of a realm. Then, pass the resulting +``RealmConfiguration`` to `Realm.open() +<{+kotlin-local-prefix+}io.realm.kotlin/-realm/-companion/open.html>`__. -When you open the realm, you must provide a list of -:ref:`object schemas ` as -an argument. +You can open a realm with default configuration values or you can build a +``RealmConfiguration`` with additional configuration options. However, you +*must* pass a `schema +<{+kotlin-local-prefix+}io.realm.kotlin/-configuration/schema.html>`__ +parameter that includes all :ref:`object classes ` +that you want to use in the realm. -.. include:: /includes/realm-schema.rst +After you open the realm with the desired configuration, you can +:ref:`read and write data ` based on your defined schema. -.. _kotlin-open-a-realm: +The examples on this page refer to the following Realm objects: -Open a Local-Only Realm -~~~~~~~~~~~~~~~~~~~~~~~ +.. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.open-realm-object-schemas.kt + :language: kotlin -To open a realm that only persists data locally, create a -`RealmConfiguration <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__ with -`RealmConfiguration.Builder <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/-builder/index.html>`__ -and pass the resulting :file:`RealmConfiguration` to -`Realm.open() <{+kotlin-local-prefix+}io.realm.kotlin/-realm/-companion/open.html>`__: +Open a Default Realm +~~~~~~~~~~~~~~~~~~~~ -.. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.open-a-realm.kt +To open a realm with default configuration values, use the +`RealmConfiguration.create() +<{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/-companion/create.html>`__. +method. You only need to define a set of object classes as the realm schema. +Then, pass the ``RealmConfiguration`` to `Realm.open() +<{+kotlin-local-prefix+}io.realm.kotlin/-realm/-companion/open.html>`__. + +The following example opens a ``default.realm`` file at the default path with +a schema that includes the ``Frog`` and ``Person`` classes: + +.. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.open-a-default-realm.kt :language: kotlin .. _kotlin-open-an-in-memory-realm: @@ -50,34 +92,98 @@ and pass the resulting :file:`RealmConfiguration` to Open an In-Memory Realm ~~~~~~~~~~~~~~~~~~~~~~~ -To open a realm that runs entirely in memory without being written to a file, -create a `RealmConfiguration <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__ -using the `inMemory <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html#1296212310%2FProperties%2F-1651551339>`__ -property with `RealmConfiguration.Builder <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/-builder/index.html>`__. -Then pass the resulting :file:`RealmConfiguration` to `Realm.open() <{+kotlin-local-prefix+}io.realm.kotlin/-realm/-companion/open.html>`__: +You can open a realm entirely in memory, which does not create a +``.realm`` file or its associated auxiliary files. Instead, the SDK stores +objects in memory while the realm is open, and then discards the data +when all instances are closed. + +To open a realm that runs without being written to a file, build a +``RealmConfiguration`` with the +`RealmConfiguration.Builder +<{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/-builder/index.html>`__ +using the `inMemory +<{+kotlin-local-prefix+}io.realm.kotlin/-configuration/in-memory.html>`__ +property. +Then, pass the resulting ``RealmConfiguration`` to `Realm.open() +<{+kotlin-local-prefix+}io.realm.kotlin/-realm/-companion/open.html>`__: .. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.open-an-in-memory-realm.kt :language: kotlin + :emphasize-lines: 5 + +Configure a Realm +----------------- + +You can add optional arguments to the ``RealmConfiguration`` to control the +specifics of the realm that you would like to open, including: + +- A file name or directory to customize how the ``.realm`` is stored on device +- Whether and when to :ref:`compact a realm ` to + reduce its file size +- Pass an encryption key to :ref:`encrypt a realm ` +- Provide a schema version or migration block when + :ref:`making schema changes ` +- Specify that Realm :ref:`delete the realm file ` + if a migration is required + +To configure a realm, create the ``RealmConfiguration`` through +`RealmConfiguration.Builder.build() +<{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/-builder/index.html>`__ +and pass any properties you want to set. Then, pass the resulting +``RealmConfiguration`` to `Realm.open() +<{+kotlin-local-prefix+}io.realm.kotlin/-realm/-companion/open.html>`__: + +.. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.open-a-realm.kt + :language: kotlin -Open a Synced Realm -~~~~~~~~~~~~~~~~~~~ +Add Initial Data to Realm +~~~~~~~~~~~~~~~~~~~~~~~~~ -To open a realm that synchronizes data with Atlas using Device Sync, -refer to :ref:`Open a Synced Realm `. +You can add initial data to a realm by using an `initialDataCallback +<+kotlin-local-prefix+}io.realm.kotlin/-configuration/initial-data-callback.html>`__. +The callback is triggered when the realm is opened for the first time. + +.. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.initial-data-callback.kt + :language: kotlin + :emphasize-lines: 4-8 + +Find a Realm File Path +---------------------- + +You can optionally define the directory for the realm file when you open the +realm. Otherwise, the default app storage location for the platform is used. +You can find the default directory with the following: + +- Android: ``Context.getFiles()`` +- JVM: ``System.getProperty("user.dir")`` +- macOS: ``platform.Foundation.NSFileManager.defaultManager.currentDirectoryPath`` +- iOS: ``NSFileManager.defaultManager.URLForDirectory( + NSDocumentDirectory, + NSUserDomainMask, + null, + true, + null + )`` + +To find the file path for a ``.realm`` file, use the `realm.configuration.path +<{+kotlin-local-prefix+}io.realm.kotlin/-configuration/path.html>`__ property: + +.. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.find-realm-path.kt + :language: kotlin .. _kotlin-close-a-realm: Close a Realm ------------- -You close a realm with `realm.close() <{+kotlin-local-prefix+}io.realm.kotlin/-realm/close.html>`__. -The :file:`close()` method blocks until all write transactions on the -realm have completed. +You close a realm with `realm.close() +<{+kotlin-local-prefix+}io.realm.kotlin/-realm/close.html>`__. This method +blocks until all write transactions on the realm have completed. .. literalinclude:: /examples/generated/kotlin/OpenARealmTest.snippet.close-a-realm.kt :language: kotlin -.. warning:: +.. warning:: Close Realms to Prevent Memory Leaks It's important to close your realm instance to free resources. Failing to close realms can lead to an ``OutOfMemoryError``. @@ -120,7 +226,7 @@ Some additional considerations to keep in mind while using - The destination file cannot already exist. - Copying a realm is not allowed within a write transaction or during - a :ref:`migration`. + a :ref:`migration `. - When using :ref:`Device Sync `, you must sync all local changes with the server before the copy is written. This ensures that the file can be used as a starting point for a newly installed application.