Configurar y abrir un dominio - SDK de Kotlin

Archivos del reino

Realm almacena una versión codificada en binario de cada objeto y tipo en un reino en un solo .realm Archivo. Al abrir un dominio, Realm crea el archivo .realm si aún no existe. El archivo se encuentra en una ruta específica, que puedes definir al abrir el dominio.

Si no desea crear un archivo .realm ni sus archivos auxiliares asociados, puede abrir un dominio en memoria. Consulte la Abra una sección de Reino en memoria para obtener más información.

Abrir un reino

Para abrir un reino, cree un objeto RealmConfiguration que defina sus detalles. Luego, pase el resultado RealmConfiguration a Realm.open().

Puede abrir un dominio con valores de configuración predeterminados o crear un RealmConfiguration con opciones de configuración adicionales. Sin embargo,debe pasar un parámetro de esquema que incluya todas las clases de objeto que desea usar en el dominio.

Después de abrir el reino con la configuración deseada, puede leer y escribir datos según el esquema definido.

Los ejemplos de esta página se refieren a los siguientes objetos Realm:

class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
}
class Person : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
}

// 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}")
// ... use the open realm ...

// 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")
// ... use the open realm ...

Personalizar una configuración de reino

Puede agregar argumentos opcionales a RealmConfiguration para controlar los detalles del reino que desea abrir, incluidos:

• Definición de un nombre de archivo personalizado y una ruta de archivo

• Pasar una clave de cifrado para cifrar un reino

• Compactar un reino para reducir su tamaño de archivo

• Especificación de una versión de esquema o un bloque de migración al realizar cambios de esquema

• Marcar si Realm debe eliminar el archivo de reino si se requiere una migración

Para obtener más información sobre implementaciones de configuración específicas, consulte Administrar archivos de Realm - Kotlin SDK.

Para configurar un dominio con valores no predeterminados, cree el RealmConfiguration mediante RealmConfiguration.Builder.build() y pase las propiedades que desee configurar. Luego, pase el resultante RealmConfiguration a Realm.open().

En el siguiente ejemplo, RealmConfiguration especifica un nombre y un directorio personalizados ("my-directory-path/myRealmName.realm") y una clave de cifrado:

// Create a realm configuration with configuration builder
// and pass all optional arguments
val config = RealmConfiguration.Builder(
    schema = setOf(Frog::class, Person::class)
)
    .name("myRealmName.realm")
    .directory("my-directory-path")
    .encryptionKey(myEncryptionKey)
    .build()
// Open the realm with the configuration object
val realm = Realm.open(config)
Log.v("Successfully opened realm: ${realm.configuration.name}")
// ... use the open realm ...

val config = RealmConfiguration.Builder(
    schema = setOf(Frog::class, Person::class)
)
    .initialData {
        copyToRealm(Frog().apply { name = "Kermit" })
        copyToRealm(Person().apply { name = "Jim Henson" })
    }
    .build()
val realm = Realm.open(config)
Log.v("Successfully opened realm: ${realm.configuration.name}")
// Opened realm includes the initial data
val initialFrog = realm.query<Frog>().find().first()
val initialPerson = realm.query<Person>().find().first()
Log.v("Realm initialized with: ${initialFrog.name} and ${initialPerson.name}")

Encontrar una ruta de archivo de Realm

Para encontrar la ruta del .realm archivo, utilice la propiedad realm.configuration.path:

val realmPath = realm.configuration.path
Log.v("Realm path: $realmPath")

Cerrar un reino

Se cierra un dominio con realm.close(). Este método se bloquea hasta que se completen todas las transacciones de escritura en el dominio.

realm.close()

Copiar datos a un nuevo reino

Para copiar datos de un dominio existente a uno nuevo con diferentes opciones de configuración, pase la nueva configuración al método Realm.writeCopyTo(). Por ejemplo, podría copiar datos para hacer una copia de seguridad de un dominio local o para convertir un dominio sincronizado en uno local.

Puede copiar datos a un reino que use la misma configuración:

• Realm local a realm local

• De un reino en memoria a otro reino en memoria

• Reino sincronizado con reino sincronizado

Puede copiar datos a un reino que utilice diferentes configuraciones de sincronización:

• Realm local a realm de sincronización basada en partición

• Reino sincronizado con el reino local

• Reino sincronizado con un reino sincronizado para un usuario diferente

También puede combinar cambios en la configuración. Por ejemplo, puede copiar datos de un dominio sincronizado en memoria sin cifrar a un dominio local cifrado.

Algunas consideraciones adicionales a tener en cuenta al utilizar Realm.writeCopyTo():

• El archivo de destino no puede existir ya.

• No se permite copiar un realm dentro de una transacción de escritura ni durante una migración.

• Al usar Device Sync, debe sincronizar todos los cambios locales con el servidor antes de escribir la copia. Esto garantiza que el archivo pueda usarse como punto de partida para una aplicación recién instalada. Realm genera un error si hay cargas pendientes.

  Puede utilizar uploadAllLocalChanges() y downloadAllServerChanges() para garantizar que se completen todos los procesos de sincronización.

// Instantiate the synced realm with your App ID
val app = App.create(YOUR_APP_ID)
runBlocking {
    val user = app.login(credentials)
    // Create the synced realm configuration
    val syncConfig = SyncConfiguration.Builder(user, setOf(Frog::class))
        .initialSubscriptions { realm ->
            add(realm.query<Frog>(),"all-frogs")
        }
        .build()
    // Open the synced realm and add data to it
    val syncRealm = Realm.open(syncConfig)
    Log.v("Successfully opened realm: ${syncRealm.configuration.name}")
    syncRealm.write {
        this.copyToRealm(Frog().apply {
            name = "Kermit"
        })
    }
    // Wait for write to sync
    syncRealm.syncSession.uploadAllLocalChanges(30.seconds)
    // Create the local realm
    val localConfig = RealmConfiguration.Builder(setOf(Frog::class))
        .name("local.realm")
        .build()
    // Copy data from synced realm to the new realm
    syncRealm.writeCopyTo(localConfig)
    // Close the synced realm when you're done copying
    syncRealm.close()
    // Open the new local realm
    val localRealm = Realm.open(localConfig)
    // Copied Frog object is available in the new realm
    val frog = localRealm.query<Frog>().find().first()
    Log.v("Copied Frog: ${frog.name}")
    localRealm.close()
}

También puede incluir una nueva clave de cifrado en la configuración del reino copiado o eliminar la clave de cifrado de la nueva configuración.

runBlocking {
    // Create the unencrypted realm
    val unencryptedConfig = RealmConfiguration.Builder(setOf(Frog::class))
        .name("unencrypted.realm")
        .build()
    // Open the realm and add data to it
    val unencryptedRealm = Realm.open(unencryptedConfig)
    unencryptedRealm.write {
        this.copyToRealm(Frog().apply {
            name = "Kermit"
        })
    }
    // ... Generate encryption key ...
    // Create the encrypted realm
    val encryptedConfig = RealmConfiguration.Builder(setOf(Frog::class))
        .name("encrypted.realm")
        .encryptionKey(encryptionKey)
        .build()
    // Copy data from `unencryptedRealm` to the new realm
    // Data is encrypted as part of the copy process
    unencryptedRealm.writeCopyTo(encryptedConfig)
    // Close the original realm when you're done copying
    unencryptedRealm.close()
    // Open the new encrypted realm
    val encryptedRealm = Realm.open(encryptedConfig)
    // Copied Frog object is available in the new realm
    val frog = encryptedRealm.query<Frog>().find().first()
    Log.v("Copied Frog: ${frog.name}")
    encryptedRealm.close()
}

runBlocking {
    // Create the in-memory realm
    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(Frog().apply {
            name = "Kermit"
        })
    }
    // Create the local realm
    val localConfig = RealmConfiguration.Builder(setOf(Frog::class))
        .name("local.realm")
        .build()
    // Copy data from `inMemoryRealm` to the new realm
    inMemoryRealm.writeCopyTo(localConfig)
    // Close the original realm when you're done copying
    inMemoryRealm.close()
    // Open the new local realm
    val localRealm = Realm.open(localConfig)
    // Copied Frog object is available in the new realm
    val frog = localRealm.query<Frog>().find().first()
    Log.v("Copied Frog: ${frog.name}")
    localRealm.close()
}