Managed assinaturas de sincronização - Kotlin SDK

Assine tipos de objetos

Os conjuntos de assinaturas são baseados no tipo de objeto. Você pode ter várias assinaturas se tiver muitos tipos de objetos do Realm. Você também pode ter várias assinaturas no mesmo tipo de objeto.

No entanto, se você utilizar objetos vinculados , objetos assimétricos ou dados geoespaciais em seu aplicativo, consulte as seguintes seções para informações adicionais:

Assinaturas iniciais

Você deve ter pelo menos uma assinatura antes de ler ou gravar no domínio.

Inscrever-se em uma query

Você pode .subscribe() a uma query para criar uma assinatura para objetos correspondentes a uma query específica:

// Subscribe to a specific query
val realmResults = realm.query<Task>("progressMinutes >= $0", 60)
    .subscribe()
// Subscribe to all objects of a specific type
val realmQuery = realm.query<Team>()
realmQuery.subscribe()

Isso cria uma assinatura sem nome e a adiciona ao MutableSubscriptionSet, em vez de exigir que você adicione manualmente a assinatura ao conjunto de assinatura .

// Add a subscription named "team_developer_education"
val results = realm.query<Team>("teamName == $0", "Developer Education")
    .subscribe("team_developer_education")

Atualizar uma assinatura de query

Você pode atualizar uma assinatura de query nomeada com uma nova query definindo updateExisting como true:

// Create a subscription named "bob_smith_teams"
val results = realm.query<Team>("$0 IN members", "Bob Smith")
    .subscribe("bob_smith_teams")
// Add another subscription with the same name with `updateExisting` set to true
// to replace the existing subscription
val updateResults =
        realm.query<Team>("$0 IN members AND teamName == $1", "Bob Smith", "QA")
            .subscribe("bob_smith_teams", updateExisting = true)

Isso atualiza a assinatura automaticamente, em vez de exigir que você atualize manualmente a assinatura no conjunto de assinatura .

Aguarde uma assinatura de query para sincronizar

Quando você assina o conjunto de resultados de uma query, esse conjunto não contém objetos até que seja sincronizado. Se o seu aplicativo criar objetos, talvez você não precise baixar os dados sincronizados antes de o usuário trabalhar com ele. No entanto, se seu aplicativo exigir dados do servidor antes que o usuário possa trabalhar com ele, você pode especificar que o aplicativo deve aguardar a sincronização dos dados. Isso bloqueia a execução do aplicativo até que os dados sejam sincronizados com o servidor.

val results = realm.query<Team>("$0 IN members", "Bob Smith")
    .subscribe("bob_smith_teams", updateExisting = false, WaitForSync.ALWAYS)
// After waiting for sync, the results set contains all the objects
// that match the query - in our case, 1
println("The number of teams that have Bob Smith as a member is ${results.size}")

Esta opção utiliza o enumeração WaitForSync , cujos valores são:

• FIRST_TIME: (padrão) Espere para baixar objetos correspondentes quando seu aplicativo cria inicialmente a assinatura. Caso contrário, volte sem aguardar novos downloads. O aplicativo deve ter uma conexão com a internet para baixar os dados quando você adiciona inicialmente a assinatura. Opcionalmente, você pode especificar um valor timeout .

• ALWAYS: Aguarde o download dos objetos correspondentes toda vez que o método .subscribe() for chamado. O aplicativo deve ter uma conexão de internet para baixar os dados. Opcionalmente, você pode especificar um valor timeout .

• NEVER: Nunca espere para baixar objetos correspondentes. O aplicativo precisa de uma conexão com a Internet para que o usuário se autentique na primeira vez que o aplicativo for iniciado, mas pode ser aberto offline nas execuções subsequentes usando credenciais em cache.

Adicionar uma assinatura

Você pode adicionar uma assinatura sem nome ou uma assinatura nomeada.

Para criar manualmente uma assinatura, adicione a assinatura em um bloco de atualização de assinaturas. Você anexa cada nova assinatura às assinaturas do Realm do cliente.

realm.subscriptions.update {
    add(
        realm.query<Task>("progressMinutes >= $0",60)
    )
}

Você também pode especificar um nome de assinatura ao criar a assinatura:

// Add a subscription named "team_dev_ed"
realm.subscriptions.update { realm ->
        add(
            realm.query<Team>("teamName == $0", "Developer Education"),
            name = "team_dev_ed"
        )
    }

// Bootstrap the realm with an initial query to subscribe to
val flexSyncConfig =
    SyncConfiguration.Builder(user, setOf(Team::class, Task::class))
        .initialSubscriptions { realm ->
            add(
                realm.query<Team>("$0 IN members", "Bob Smith"),
                "bob_smith_teams"
            )
        }
        .build()

// `rerunOnOpen` lets the app recalculate this query every time the app opens
val rerunOnOpenConfig =
    SyncConfiguration.Builder(user, setOf(Team::class, Task::class))
        .initialSubscriptions(rerunOnOpen = true) { realm ->
            add(
                realm.query<Team>("completed == $0", false)
            )
        }
        .build()

Aguarde as alterações na assinatura para sincronizar

Escrever uma atualização para o conjunto de assinaturas localmente é apenas um componente da alteração de uma assinatura. Após a alteração da assinatura local, o cliente sincroniza com o servidor para resolver quaisquer atualizações nos dados devido à alteração da assinatura. Isso pode média adicionar ou remover dados do Realm sincronizado.

Use o método SyncConfiguration.waitForInitialRemoteData() método construtor para forçar seu aplicação a bloquear até que os dados de assinatura do cliente sejam sincronizados com o backend antes de abrir o Realm:

// Update the list of subscriptions
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Jane Doe"),
        "jane_doe_teams"
    )
}
// Wait for subscription to fully synchronize changes
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))

Você também pode usar SubscriptionSet.waitForSynchronization() para atrasar a execução até que a sincronização da assinatura seja concluída após instanciar uma conexão de sincronização.

Estado do conjunto de assinaturas

Use a propriedade SubscriptionSet.state para ler o estado atual do conjunto de assinaturas.

SUPERCEDED (sic -- observe a ortografia alternativa) é um SubscriptionSetState que pode ocorrer quando outro thread escreve uma assinatura em uma instância diferente do conjunto de assinaturas. Se o estado se tornar SUPERCEDED, você deverá obter uma nova instância do conjunto de assinaturas antes de poder gravar nele.

Atualizar assinaturas com uma nova query

Você pode atualizar assinaturas usando SubscriptionSet.update().

Neste exemplo, usamos MutableSubscriptionSet.add(). para atualizar a query da assinatura denominada "bob_smith_teams". Você deve definir o parâmetro updateExisting como true para atualizar uma assinatura com add():

// Create a subscription named "bob_smith_teams"
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams"
    )
}
// Set `updateExisting` to true to replace the existing
// "bob_smith_teams" subscription
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members AND $1 IN members", "Bob Smith", "Jane Doe"),
        "bob_smith_teams", updateExisting = true
    )
}

Você não pode atualizar assinaturas criadas sem um nome. No entanto, você pode procurar assinaturas não nomeadas por query, removê-las do conjunto de assinaturas e adicionar uma nova assinatura com uma query atualizada:

// Search for the subscription by query
val subscription =
    realm.subscriptions.findByQuery(
        realm.query<Team>("teamName == $0", "Developer Education")
    )
// Remove the returned subscription and add the updated query
if (subscription != null) {
    realm.subscriptions.update {
        remove(subscription)
        add(
            realm.query<Team>("teamName == $0", "DevEd"),
            "team_developer_education"
        )
    }
}

Remover subscrições

Para remover assinaturas, você pode:

• Remover uma query de assinatura única

• Remover todas as assinaturas de um tipo de objeto específico

• Remover todas as assinaturas

• Remover todas as assinaturas sem nome

Quando você remove uma query de assinatura, o Realm remove assíncronamente os dados sincronizados que corresponderam à query do dispositivo cliente.

realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams"
    )
}
// Wait for synchronization to complete before updating subscriptions
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))
// Remove subscription by name
realm.subscriptions.update {
    remove("bob_smith_teams")
}

realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams")
}
// Wait for synchronization to complete before updating subscriptions
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))
// Remove all subscriptions to type Team
realm.subscriptions.update {
    removeAll(Team::class)
}

// Remove all subscriptions
realm.subscriptions.update {
    removeAll()
}

// Remove all unnamed (anonymous) subscriptions
realm.subscriptions.update {
    removeAll(anonymousOnly = true)
}

Requisitos de inscrição de campos de query indexados

Adicionar um campo de query indexado à sua aplicação pode melhorar o desempenho de queries simples em dados fortemente particionados. Por exemplo, uma aplicação onde as queries mapeiam fortemente os dados para um dispositivo, armazém ou usuário, como user_id == $0, “641374b03725038381d2e1fb”, é uma boa candidata para um campo de query indexado. No entanto, um campo de query indexado tem requisitos específicos para uso em uma inscrição de query:

• O campo de query indexado deve ser usado em todas as inscrições de query. Não pode estar faltando na query.

• O campo de query indexado deve usar uma comparação == ou IN com uma constante pelo menos uma vez na query de inscrição. Por exemplo, user_id == $0, "641374b03725038381d2e1fb" ou store_id IN $0, {1,2,3}.

Opcionalmente, você pode incluir uma comparação AND, desde que o campo consultável indexado seja comparado diretamente com uma constante usando == ou IN pelo menos uma vez. Por exemplo, store_id IN {1,2,3} AND region=="Northeast" ou store_id == 1 AND (active_promotions < 5 OR num_employees < 10).

As consultas inválidas do Flexible Sync em um campo indexado que pode ser consultado incluem consultas em que:

• O campo de consulta indexado não utiliza AND com o resto da consulta. Por exemplo store_id IN {1,2,3} OR region=="Northeast" é inválido porque usa OR em vez de AND. Da mesma forma, store_id == 1 AND active_promotions < 5 OR num_employees < 10 é inválido porque o AND só se aplica ao termo ao lado, não à consulta inteira.

• O campo de consulta indexado não é utilizado em um operador de igualdade. Por exemplo store_id > 2 AND region=="Northeast" é inválido porque utiliza apenas o operador > com o campo de consulta indexado e não tem uma comparação de igualdade.

• A query está totalmente ausente do campo de query indexado. Por exemplo, region=="Northeast ou truepredicate são inválidos porque não contêm o campo de query indexado.

Operadores de consulta não suportados na sincronização flexível

A Flexible Sync tem algumas limitações ao usar operadores RQL. Quando você escreve a assinatura de consulta que determina quais dados sincronizar, o servidor não oferece suporte a esses operadores de consulta. No entanto, você ainda pode usar toda a gama de recursos de RQL para consultar o conjunto de dados sincronizado no aplicativo cliente.

Queries que não diferenciam maiúsculas de minúsculas ([c]) não podem usar índices de forma eficaz. Sendo assim, queries que não diferenciam maiúsculas de minúsculas não são recomendadas, pois podem causar problemas de desempenho.

A sincronização flexível suporta apenas @count para campos de array.

Listar queries

A sincronização flexível oferece suporte às listas de query usando o operador IN .

Você pode consultar uma lista de constantes para ver se ela contém o valor de um campo de consulta:

// Query a constant list for a queryable field value
"priority IN { 1, 2, 3 }"

Se um campo de query tiver um valor de array, você poderá consultar para ver se ele contém um valor constante:

// Query an array-valued queryable field for a constant value
"'comedy' IN genres"

// Invalid Flexible Sync query. Do not do this!
"{'comedy', 'horror', 'suspense'} IN genres"
// Another invalid Flexible Sync query. Do not do this!
"ANY {'comedy', 'horror', 'suspense'} != ANY genres"

Objetos incorporados ou vinculados

A Flexible Sync não oferece suporte à consulta de propriedades em objetos ou links embarcados. Por exemplo, obj1.field == "foo".

Limite de tamanho da query

O limite de tamanho para qualquer assinatura de query em seu conjunto de assinatura é de 256 kB. Exceder esse limite resulta em um erro de LimitsExceeded.

Eficiência da API

O gerenciamento de várias assinaturas com a API .subscribe() descrita na seção Assinar queries é menos eficiente do que executar atualizações em lote quando você gerencia assinaturas manualmente por meio da API do conjunto de assinaturas. Para obter melhor desempenho ao fazer várias alterações na assinatura, use a API subscriptions.update descrita na seção Gerenciar assinaturas manualmente .

Atualizações de grupo para melhorar o desempenho

Cada transação de escrita para um conjunto de assinaturas tem um custo de desempenho. Se você precisar fazer várias atualizações em um objeto do Realm durante uma sessão, considere manter objetos editados na memória até que todas as alterações sejam concluídas. Isso melhora o desempenho da sincronização, gravando apenas o objeto completo e atualizado em seu domínio, em vez de cada alteração.