Configurar e abrir um domínio - Realm Kotlin SDK

Arquivos Realm

O Realm armazena uma versão codificada binariamente de cada objeto e digita um domínio em um único arquivo .realm . Quando você abre um domínio, o Realm cria o arquivo .realm se ele ainda não existir. O arquivo está localizado em um caminho específico, que você pode definir ao abrir o domínio.

Se você não quiser criar um arquivo .realm ou seus arquivos auxiliares associados, poderá abrir um domínio na memória. Consulte a seção Abrir um domínio na memória para obter mais informações.

Abrir um Realm

Para abrir um domínio, crie um objeto RealmConfiguration que define os detalhes de um domínio. Em seguida, passe o RealmConfiguration resultante para Realm.open().

Você pode abrir um realm com valores de configuração padrão ou pode construir um RealmConfiguration com opções de configuração adicionais. No entanto, você deve passar um parâmetro de esquema que inclua todas as classes de objeto que deseja usar no domínio.

Depois de abrir o domínio com a configuração desejada, você pode ler e escrever dados com base no esquema definido.

Os exemplos nesta página referem-se aos seguintes objetos de 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 ...

Realm uma configuração de domínio

Você pode adicionar argumentos opcionais ao RealmConfiguration para controlar as especificidades do domínio que você gostaria de abrir, incluindo:

• Definir um nome de arquivo personalizado e um caminho de arquivo

• Passando uma chave de encriptação para criptografar um Realm

• Compactação de um domínio para reduzir o tamanho do arquivo

• Especificar uma versão do esquema ou bloco de migração ao fazer alterações no esquema

• Sinalizando se o Realm deve excluir o arquivo de domínio se uma migração for necessária

Para obter mais informações sobre implementações de configuração específicas, consulte Gerenciar arquivos Realm - Kotlin SDK.

Para configurar um realm com valores não padrão, crie o RealmConfiguration por meio de RealmConfiguration.Builder.build() e passar quaisquer propriedades que você queira definir. Em seguida, passe o RealmConfiguration resultante para Realm.open().

No exemplo a seguir, o RealmConfiguration especifica um nome personalizado e diretório ("my-directory-path/myRealmName.realm") e chave de criptografia:

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

Encontre um caminho de arquivo Realm

Para localizar o caminho de um arquivo .realm , use a propriedade realm.configuration.path :

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

Fechar um Realm

Você fecha um domínio com realm.close(). Este método bloqueia até que todas as transações de escrita no domínio tenham sido concluídas.

realm.close()

Copiar dados para um novo domínio

Para copiar dados de um domínio existente para um novo domínio com diferentes opções de configuração, passe a nova configuração para o método Realm.writeCopyTo() . Por exemplo, você pode copiar dados como uma forma de fazer backup de um domínio local ou converter um domínio sincronizado em um domínio local.

Você pode copiar dados para um domínio que usa a mesma configuração:

• Realm local para domínio local

• Realm na memória para domínio na memória

• Realm sincronizado para realm sincronizado

Você pode copiar dados para um domínio que usa configurações de sincronização diferentes:

• Realm local para domínio de sincronização baseada em partição

• Realm sincronizado com o domínio local

• Realm sincronizado com um Realm sincronizado para um usuário diferente

Você também pode combinar alterações na configuração. Por exemplo, você pode copiar dados de um realm sincronizado na memória não criptografado para um realm local criptografado.

Algumas considerações adicionais a serem lembradas ao usar Realm.writeCopyTo():

• O arquivo de destino já não pode existir.

• Não é permitido copiar um realm dentro de uma transação de escrita ou durante uma migração.

• Ao usar o Device Sync, você deve sincronizar todas as alterações locais com o servidor antes que a cópia seja gravada. Isso garante que o arquivo possa ser usado como ponto de partida para um aplicativo recém-instalado. O Realm apresenta um erro se houver carregamentos pendentes.

  Você pode usar uploadAllLocalChanges() e downloadAllServerChanges() para garantir que todos os processos de sincronização sejam concluídos.

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

Você também pode incluir uma nova chave de criptografia na configuração do realm copiado ou remover a chave de criptografia da nova configuração.

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