Tutorial: Atlas Device Sync para Kotlin

Agregar una nueva propiedad al modelo

Now that you have confirmed everything is working as expected, we can add changes. In this tutorial, we have decided that we want to add a "priority" property to each Item so that we can filter Items by their priority level. The priority property will be mapped to a PriorityLevel enum to constrain the possible values, and we will use the ordinal of each enum to correspond to the priority integer so we can query based on a numeric priority level later.

Para ello siga estos pasos:

1. Dentro de la carpeta app/java/com.mongodb.app/domain, abra el archivo de clase Item.

2. Agregue una enumeración PriorityLevel para restringir los valores posibles. También agregue una propiedad priority a la clase Item, que establece la prioridad predeterminada en 3, lo que indica que es una tarea pendiente de baja prioridad:

   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
   }

Establecer la prioridad al crear un nuevo elemento

1. Desde la carpeta ui/tasks, abra el archivo AddItem.kt. Este archivo define las funciones componibles para la interfaz de usuario que se muestra cuando un usuario hace clic en el botón "+" para añadir una nueva tarea.

2. Primero, agregue las siguientes importaciones debajo de 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. Ahora podemos añadir un campo desplegable a la función componible AddItemPrompt que permitirá al usuario elegir un nivel de prioridad de una lista utilizando los enums PriorityLevel como valores disponibles:

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

   Android Studio identificará varios errores. Los corregiremos en los próximos pasos añadiendo las funciones correspondientes.

4. A continuación, definiremos la etiqueta del campo desplegable como un recurso de cadena. Abra el archivo res/values/strings.xml y agregue lo siguiente antes de cerrar el elemento "resource":

   res/values/strings.xml

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

5. Ahora, dentro de la carpeta presentation/tasks, abre el archivo AddItemViewModel.kt. Aquí agregaremos la lógica de negocio relacionada con nuestro nuevo campo de menú desplegable.

   Agregue la importación PriorityLevel debajo de package com.mongodb.app, luego agregue las variables y funciones a la clase AddItemViewModel necesarias para manejar los cambios de estado dentro del menú desplegable:

   presentation/tareas/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
      }

   Ahora actualice las funciones addTask() y cleanUpAndClose() para incluir el nuevo parámetro taskPriority, actualice el mensaje con la información de prioridad y restablezca el campo de prioridad a bajo una vez que se cierre la vista Agregar elemento:

   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, desde la carpeta data, abra el archivo SyncRepository.kt para reflejar los mismos cambios en la función addTask(), que escribe el elemento en el reino.

   Primero, agregue la importación PriorityLevel debajo de package com.mongodb.app, luego actualice las funciones addTask() para pasar taskPriority como parámetro y escriba el campo priority en el reino como un entero (usando el ordinal de enumeración):

   datos/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
   }

Ejecutar y probar

At this point, you can rerun the application. Log in using the account you created earlier in this tutorial. You will see the one Item you previously created. Add a new Item, and you will see that you can now set the priority. Choose High for the priority and save the Item.

Ahora, regrese a la página de datos del Atlas en su navegador y actualice la Item colección. Debería ver el nuevo elemento con el priority campo agregado y configurado en 1. El elemento existente no tiene el priority campo.

haga clic para ampliar

Update the subscription

Dentro de la carpeta app/java/com.mongodb.app/data, abre el archivo SyncRepository.kt, donde definimos la suscripción Flexible Sync. La suscripción define qué documentos sincronizamos con el dispositivo y la cuenta del usuario. Busca la función getQuery(). Puedes ver que actualmente estamos suscritos a dos suscripciones:

• MINE:Todos los documentos donde la propiedad ownerId coincide con el usuario autenticado.

• ALL: Todos los documentos de todos los usuarios.

Queremos actualizar la MINE suscripción para sincronizar únicamente los elementos que estén marcados como prioridad alta o grave.

Como recordarás, el campo priority es de tipo int, donde la prioridad más alta ("Grave") tiene un valor de 0 y la prioridad más baja ("Baja") tiene un valor de 3. Podemos hacer comparaciones directas entre un entero y la propiedad de prioridad. Para ello, edita la instrucción RQL para incluir documentos donde la prioridad sea igual o menor que PriorityLevel.High (o 1), como se muestra aquí:

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

We'll also force the subscription query to recalculate which documents to sync every time we open the app.

Para ello, busque la función SyncConfiguration.Builder().initialSubscriptions() que nuestra aplicación llama al inicio. Primero, añada el parámetro reRunOnOpen a true y, a continuación, configure updateExisting a true, lo que permite actualizar la consulta existente.

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

Ejecutar y probar

Vuelve a ejecutar la aplicación. Inicia sesión usando la cuenta que creaste anteriormente en este tutorial.

Después de un momento inicial cuando Realm vuelve a sincronizar la colección de documentos, verá el nuevo elemento de alta prioridad que creó.

Si desea probar la funcionalidad con más detalle, puede crear elementos con diferentes prioridades. Observará que si intenta agregar un elemento con una prioridad inferior a Alta, recibirá un mensaje de notificación indicando que no tiene permiso. Si revisa sus registros con Logcat, verá un mensaje indicando que el elemento se agregó correctamente, seguido de un error de sincronización:

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

Esto se debe a que, en este escenario, Realm crea el elemento localmente, lo sincroniza con el backend y luego revierte la escritura porque no cumple con las reglas de suscripción.

También, notarás que el documento que creaste inicialmente no está sincronizado porque tiene una prioridad de null. Si deseas que este elemento se sincronice, puedes editar el documento en la interfaz de usuario de Atlas y agregar un valor para el campo de prioridad.