Tutorial: Atlas Device Sync para Kotlin

Adicionar uma nova propriedade ao modelo

Agora que você confirmou que tudo está funcionando conforme o esperado, podemos adicionar as alterações. Neste tutorial, decidimos que queremos adicionar uma propriedade "priority" a cada item para que possamos filtrar os itens por seu nível de prioridade. A propriedade priority será mapeada a um enum PriorityLevel para restringir os valores possíveis, e usaremos o ordinal de cada enum para corresponder ao número inteiro priority para que possamos consultar com base em um nível de priority numérico posteriormente.

Para fazer isso, siga estas etapas:

1. Dentro da pasta app/java/com.mongodb.app/domain, abra o arquivo de classe Item.

2. Adicione um enum PriorityLevel para restringir os valores possíveis. Adicione também uma propriedade priority à classe Item, que define a priority padrão como 3, indicando que é um item de tarefas de baixa priority:

   domain/Item.kt

   // ... imports
      enum class PriorityLevel() {
         Severe, // priority 0
         High,   // priority 1
         Medium, // priority 2
         Low     // priority 3
      }
      class Item() : RealmObject {
         @PrimaryKey
         var _id: ObjectId = ObjectId.create()
         var isComplete: Boolean = false
         var summary: String = ""
         var owner_id: String = ""
         var priority: Int = PriorityLevel.Low.ordinal
         constructor(ownerId: String = "") : this() {
            owner_id = ownerId
         }
   // ... equals() and hashCode() functions
   }

Definir a prioridade ao criar um novo item

1. Na pasta ui/tasks, abra o arquivo AddItem.kt. Esse arquivo define as funções que podem ser compostas para a interface do usuário que são exibidas quando um usuário clica no botão '+' para adicionar um novo item de tarefa.

2. Primeiro, adicione as seguintes importações abaixo do package com.mongodb.app:

   ui/tasks/AddItem.kt

   import androidx.compose.foundation.layout.fillMaxWidth
   import androidx.compose.foundation.layout.padding
   import androidx.compose.material3.DropdownMenuItem
   import androidx.compose.material3.ExposedDropdownMenuBox
   import androidx.compose.ui.Modifier
   import androidx.compose.ui.unit.dp
   import com.mongodb.app.domain.PriorityLevel

3. Agora podemos adicionar um campo suspenso à função composta do AddItemPrompt que permitirá ao usuário escolher um nível de prioridade em uma lista usando os enums PriorityLevel como valores disponíveis:

   ui/tasks/AddItem.kt

   // ... imports
   @OptIn(ExperimentalMaterial3Api::class)
   @Composable
   fun AddItemPrompt(viewModel: AddItemViewModel) {
      AlertDialog(
         containerColor = Color.White,
         onDismissRequest = {
               viewModel.closeAddTaskDialog()
         },
         title = { Text(stringResource(R.string.add_item)) },
         text = {
               Column {
                  Text(stringResource(R.string.enter_item_name))
                  TextField(
                     colors = ExposedDropdownMenuDefaults.textFieldColors(containerColor = Color.White),
                     value = viewModel.taskSummary.value,
                     maxLines = 2,
                     onValueChange = {
                           viewModel.updateTaskSummary(it)
                     },
                     label = { Text(stringResource(R.string.item_summary)) }
                  )
                  val priorities = PriorityLevel.values()
                  ExposedDropdownMenuBox(
                     modifier = Modifier.padding(16.dp),
                     expanded = viewModel.expanded.value,
                     onExpandedChange = { viewModel.open() },
                  ) {
                     TextField(
                           readOnly = true,
                           value = viewModel.taskPriority.value.name,
                           onValueChange = {},
                           label = { Text(stringResource(R.string.item_priority)) },
                           trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = viewModel.expanded.value) },
                           colors = ExposedDropdownMenuDefaults.textFieldColors(),
                           modifier = Modifier
                              .fillMaxWidth()
                              .menuAnchor()
                     )
                     ExposedDropdownMenu(
                           expanded = viewModel.expanded.value,
                           onDismissRequest = { viewModel.close() }
                     ) {
                           priorities.forEach {
                              DropdownMenuItem(
                                 text = { Text(it.name) },
                                 onClick = {
                                       viewModel.updateTaskPriority(it)
                                       viewModel.close()
                                 }
                              )
                           }
                     }
                  }
               }
         },
         // ... buttons
      )
   }

   O Android Studio identificará vários erros. Corrigiremos isso nas próximas etapas adicionando as funções relacionadas.

4. Em seguida, definiremos a etiqueta do campo suspenso como um recurso de string. Abra o arquivo res/values/strings.xml e adicione o seguinte antes de fechar o elemento "recurso":

   res/values/strings.xml

   <string name="item_priority">Item Priority</string>

5. Agora, na pasta presentation/tasks, abra o arquivo AddItemViewModel.kt . Aqui adicionaremos a lógica de negócios relacionada ao nosso novo campo suspenso.

   Adicione a importação PriorityLevel abaixo do package com.mongodb.app e, em seguida, adicione as variáveis e funções à classe AddItemViewModel necessária para lidar com as alterações de estado no menu suspenso:

   presentation/tasks/AddItemViewModel.kt

      // ... imports
      import com.mongodb.app.domain.PriorityLevel
      // ... events
      class AddItemViewModel(
         private val repository: SyncRepository
      ) : ViewModel() {
         private val _addItemPopupVisible: MutableState<Boolean> = mutableStateOf(false)
         val addItemPopupVisible: State<Boolean>
            get() = _addItemPopupVisible
         private val _taskSummary: MutableState<String> = mutableStateOf("")
         val taskSummary: State<String>
            get() = _taskSummary
         private val _taskPriority: MutableState<PriorityLevel> = mutableStateOf(PriorityLevel.Low)
         val taskPriority: State<PriorityLevel>
            get() = _taskPriority
         private val _expanded: MutableState<Boolean> = mutableStateOf(false)
         val expanded: State<Boolean>
            get() = _expanded
         private val _addItemEvent: MutableSharedFlow<AddItemEvent> = MutableSharedFlow()
         val addItemEvent: Flow<AddItemEvent>
            get() = _addItemEvent
         fun openAddTaskDialog() {
            _addItemPopupVisible.value = true
         }
         fun closeAddTaskDialog() {
            cleanUpAndClose()
         }
         fun updateTaskSummary(taskSummary: String) {
            _taskSummary.value = taskSummary
         }
         fun updateTaskPriority(taskPriority: PriorityLevel) {
            _taskPriority.value = taskPriority
         }
         fun open() {
            _expanded.value = true
         }
         fun close() {
            _expanded.value = false
         }
         // addTask() and cleanUpAndClose() functions
      }

   Agora, atualize as funções addTask() e cleanUpAndClose() para incluir o novo parâmetro taskPriority, atualize a mensagem com as informações de prioridade e redefina o campo de priority para baixo assim que a exibição Adicionar item for fechado:

   fun addTask() {
      CoroutineScope(Dispatchers.IO).launch {
            runCatching {
               repository.addTask(taskSummary.value, taskPriority.value)
            }.onSuccess {
               withContext(Dispatchers.Main) {
                  _addItemEvent.emit(AddItemEvent.Info("Task '$taskSummary' with priority '$taskPriority' added successfully."))
               }
            }.onFailure {
               withContext(Dispatchers.Main) {
                  _addItemEvent.emit(AddItemEvent.Error("There was an error while adding the task '$taskSummary'", it))
               }
            }
            cleanUpAndClose()
      }
   }
   private fun cleanUpAndClose() {
      _taskSummary.value = ""
      _taskPriority.value = PriorityLevel.Low
      _addItemPopupVisible.value = false
   }

6. Finalmente, na pasta data, abra o arquivo SyncRepository.kt para refletir as mesmas alterações na função addTask(), que grava o item no realm.

   Primeiro, adicione a importação PriorityLevel abaixo do package com.mongodb.app e, em seguida, atualize as funções addTask() para passar o taskPriority como parâmetro e gravar o campo priority no domínio como um número inteiro (usando o enum ordinal):

   data/SyncRepository.kt

   // ... imports
   import com.mongodb.app.domain.PriorityLevel
   interface SyncRepository {
      // ... Sync functions
      suspend fun addTask(taskSummary: String, taskPriority: PriorityLevel)
      // ... Sync functions
   }
   class RealmSyncRepository(
      onSyncError: (session: SyncSession, error: SyncException) -> Unit
   ) : SyncRepository {
      // ... variables and SyncConfiguration initializer
      // ... Sync functions
      override suspend fun addTask(taskSummary: String, taskPriority: PriorityLevel) {
         val task = Item().apply {
               owner_id = currentUser.id
               summary = taskSummary
               priority = taskPriority.ordinal
         }
         realm.write {
               copyToRealm(task)
         }
      }
      override suspend fun updateSubscriptions(subscriptionType: SubscriptionType) {
         realm.subscriptions.update {
               removeAll()
               val query = when (subscriptionType) {
                  SubscriptionType.MINE -> getQuery(realm, SubscriptionType.MINE)
                  SubscriptionType.ALL -> getQuery(realm, SubscriptionType.ALL)
               }
               add(query, subscriptionType.name)
         }
      }
      // ... additional Sync functions
   }
   class MockRepository : SyncRepository {
      override fun getTaskList(): Flow<ResultsChange<Item>> = flowOf()
      override suspend fun toggleIsComplete(task: Item) = Unit
      override suspend fun addTask(taskSummary: String, taskPriority: PriorityLevel) = Unit
      override suspend fun updateSubscriptions(subscriptionType: SubscriptionType) = Unit
      override suspend fun deleteTask(task: Item) = Unit
      override fun getActiveSubscriptionType(realm: Realm?): SubscriptionType = SubscriptionType.ALL
      override fun pauseSync() = Unit
      override fun resumeSync() = Unit
      override fun isTaskMine(task: Item): Boolean = task.owner_id == MOCK_OWNER_ID_MINE
      override fun close() = Unit
      // ... companion object
   }

Executar e testar

Agora você pode executar o aplicativo novamente. Faça login usando a conta que você criou neste tutorial. Você verá o único item que criou anteriormente. Adicione um novo item e você verá que agora pode definir a priority. Escolha High para a priority e salve o item.

Agora volte para a página de dados do Atlas em seu navegador e atualize a coleção do Item. Você deve agora visualizar o novo Item com o campo priority adicionado e configurado para 1. O item existente não tem um campo priority.

Atualizar a assinatura

Na pasta app/java/com.mongodb.app/data, abra o arquivo SyncRepository.kt, onde definimos a inscrição Flexible Sync. A inscrição define quais documentos sincronizamos com o dispositivo e a conta do usuário. Encontre a função getQuery(). Você pode ver que atualmente estamos assinando duas inscrições:

• MINE: Todos os documentos onde a propriedade ownerId corresponde ao usuário autenticado.

• ALL: Todos os documentos de todos os usuários.

Queremos atualizar a inscrição MINE para somente itens de sincronização marcados como prioridade Alta ou Grave.

Como você deve se lembrar, o campo priority é do tipo int, em que a prioridade mais alta ("Severe") tem o valor 0 e a prioridade mais baixa ("Low") tem o valor 3. Podemos fazer comparações diretas entre um número inteiro e a propriedade de prioridade. Para isso, edite a instrução RQL para incluir documentos em que a prioridade seja igual ou inferior a PriorityLevel.High (ou 1), conforme mostrado aqui:

private fun getQuery(realm: Realm, subscriptionType: SubscriptionType): RealmQuery<Item> =
   when (subscriptionType) {
         SubscriptionType.MINE -> realm.query("owner_id == $0 AND priority <= ${PriorityLevel.High.ordinal}", currentUser.id)
         SubscriptionType.ALL -> realm.query()
   }

Também forçaremos a query de inscrição a recalcular quais documentos sincronizar toda vez que abrirmos o aplicativo.

Para tal, localize a função SyncConfiguration.Builder().initialSubscriptions() que nosso aplicativo chama no início. Primeiro, adicione o parâmetro reRunOnOpen definido para true e, em seguida, defina updateExisting para true, o que permite que a query existente seja atualizada.

config = SyncConfiguration.Builder(currentUser, setOf(Item::class))
   .initialSubscriptions(rerunOnOpen = true) { realm ->
       // Subscribe to the active subscriptionType - first time defaults to MINE
       val activeSubscriptionType = getActiveSubscriptionType(realm)
       add(getQuery(realm, activeSubscriptionType), activeSubscriptionType.name, updateExisting = true)
   }
   .errorHandler { session: SyncSession, error: SyncException ->
       onSyncError.invoke(session, error)
   }
   .waitForInitialRemoteData()
   .build()

Executar e testar

Execute o aplicativo novamente. Faça login usando a conta que você criou neste tutorial.

Após um momento inicial em que o Realm ressincroniza a collection de documentos, você verá o novo item de alta priority que você criou.

Se quiser testar ainda mais a funcionalidade, crie itens de várias prioridades. Você verá que, se tentar adicionar um item com prioridade menor que Alta, receberá uma mensagem do sistema indicando que não tem permissão. E, se você verificar seus logs usando o Logcat, verá uma mensagem indicando que o item foi "adicionado com sucesso", seguida por um erro de sincronização:

ERROR "Client attempted a write that is outside of permissions or query
filters; it has been reverted"

Isso porque, nesse cenário, o Realm cria o item localmente, sincroniza-o com o backend e, em seguida, reverte a escrita porque ele não atende às regras de assinatura.

Você também notará que o documento que você criou inicialmente não está sincronizado, pois tem uma priority de null. Se você quiser que este Item seja sincronizado, você pode editar o documento na interface do usuário do Atlas e adicionar um valor para o campo prioritário.