Tutorial: Atlas Device Sync for Kotlin

Add a New Property to the Model

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.

To do this, follow these steps:

1. Within the app/java/com.mongodb.app/domain folder, open the Item class file.

2. Add a PriorityLevel enum to constrain the possible values. Also add a priority property to the Item class, which sets the default priority to 3, indicating that it is a low-priority todo item:

   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
   }

Set the Priority when Creating a New Item

1. From the ui/tasks folder, open the AddItem.kt file. This file defines the composable functions for the UI that is displayed when a user clicks the '+' button to add a new todo item.

2. First, add the following imports below the 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. Now we can add a dropdown field to the AddItemPrompt composable function that will enable the user to pick a priority level from a list using the PriorityLevel enums as available values:

   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 will identify several errors. We'll correct these in the next steps by adding the related functions.

4. Next, we'll define the dropdown field label as a string resource. Open the res/values/strings.xml file, and add the following before the closing of the 'resource' element:

   res/values/strings.xml

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

5. Now within the presentation/tasks folder, open the AddItemViewModel.kt file. Here we will add the business logic related to our new dropdown field.

   Add the PriorityLevel import below the package com.mongodb.app, then add the variables and functions to the AddItemViewModel class needed to handle the state changes within the dropdown:

   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
      }

   Now update the addTask() and cleanUpAndClose() functions to include the new taskPriority parameter, update the message with the priority information, and reset the priority field to low once the Add Item view is closed:

   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. Finally, from the data folder, open the SyncRepository.kt file to reflect the same changes in the addTask() function, which writes the Item to the realm.

   First, add the PriorityLevel import below the package com.mongodb.app, then update the addTask() functions to pass the taskPriority as a parameter and write the priority field to the realm as an integer (using the 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
   }

Run and Test

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.

Now switch back to the Atlas data page in your browser, and refresh the Item collection. You should now see the new Item with the priority field added and set to 1. The existing Item does not have a priority field.

click to enlarge

Update the subscription

Within the app/java/com.mongodb.app/data folder, open the SyncRepository.kt file, where we define the Flexible Sync subscription. The subscription defines which documents we sync with the user's device and account. Find the getQuery() function. You can see that we are currently subscribing to two subscriptions:

• MINE: All documents where the ownerId property matches the authenticated user.

• ALL: All documents from all users.

We want to update the MINE subscription to only sync Items that are marked as High or Severe priority.

As you may recall, the priority field is of type int, where the highest priority ("Severe") has a value of 0, and the lowest priority ("Low") has a value of 3. We can make direct comparisons between an integer and the priority property. To do so, edit the RQL statement to include documents where the priority is equal to or less than PriorityLevel.High (or 1), as shown here:

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.

To do this, find the SyncConfiguration.Builder().initialSubscriptions() function that our application calls on start. First add the reRunOnOpen parameter set to true, then set updateExisting to true, which allows the existing query to be updated.

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

Run and Test

Run the application again. Log in using the account you created earlier in this tutorial.

After an initial moment when Realm re-syncs the document collection, you will see the new Item of High priority that you created.

If you want to test the functionality further, you can create Items of various priorities. You'll note that if you try to add an Item with a priority lower than High, you will get a Toast message indicating you do not have permission. And if you check your logs using Logcat, you will see a message indicating the item was "added successfully", followed by a sync error:

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

That's because, in this scenario, Realm creates the Item locally, syncs it with the backend, and then reverts the write because it doesn't meet the subscription rules.

You'll note, too, that the document you initially created is not synced, because it has a priority of null. If you want this Item to be synced, you can edit the document in the Atlas UI and add a value for the priority field.