Configurar y abrir un dominio - SDK de Kotlin

Realm Files

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 realm, crea un objeto RealmConfiguration que defina los detalles de un realm. Luego, pase el RealmConfiguration resultante 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.

After you open the realm with the desired configuration, you can read and write data based on your defined schema.

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 ...

Customize a Realm Configuration

You can add optional arguments to the RealmConfiguration to control the specifics of the realm that you would like to open, including:

• Definir un nombre de archivo y una ruta de archivo personalizados

• Pasar una clave de cifrado para cifrar un reino

• Compacting a realm to reduce its file size

• Specifying a schema version or migration block when making schema changes

• Flagging whether Realm should delete the realm file if a migration is required

For more information on specific configuration implementations, refer to Manage Realm Files - 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, el RealmConfiguration especifica un nombre personalizado, un directorio ("my-directory-path/myRealmName.realm") y una llave 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}")

Encuentra una ruta de archivo Realm

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

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

Close a Realm

You close a realm with realm.close(). This method blocks until all write transactions on the realm have completed.

realm.close()

Copy Data into a New Realm

To copy data from an existing realm to a new realm with different configuration options, pass the new configuration to the Realm.writeCopyTo() method. For example, you might copy data as a way to backup a local realm or to convert a synced realm to a local realm.

You can copy data to a realm that uses the same configuration:

• Realm local a realm local

• In-memory realm to in-memory realm

• Reino sincronizado con reino sincronizado

You can copy data to a realm that uses different sync configurations:

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

• Synced realm to local realm

• Synced realm to a synced realm for a different user

You can also combine changes to the configuration. For example, you can copy data from an unencrypted, in-memory synced realm to an encrypted local realm.

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.

• Cuando uses Device Sync, debes sincronizar todos los cambios locales con el servidor antes de escribir la copia. Esto asegura que el archivo pueda ser usado como punto de partida para una aplicación recién instalada. Realm genera un error si hay cargas pendientes.

  You can use uploadAllLocalChanges() and downloadAllServerChanges() to ensure all sync processes are completed.

// 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()
}

You can also include a new encryption key in the copied realm's configuration or remove the encryption key from the new configuration.

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()
}