Manage a Sync Session - Kotlin SDK

Sync Sessions

When you use Flexible Sync, the Realm Kotlin SDK syncs data with Atlas in the background using a sync session. The sync session starts whenever you open a synced realm.

val app = App.create(YOUR_APP_ID)
val user = app.login(credentials)
val config = SyncConfiguration.Builder(user, setOf(Task::class))
    .build()
// Open the synced realm
val realm = Realm.open(config)
// Sync session is now active
// ... do something with the synced realm

The sync session manages the following:

• Uploading and downloading changes to the realm

• Pausing and resuming sync

• Monitoring network connectivity

You can access the SyncSession of a single synced realm through the realm.syncSession property.

Wait for Changes to Upload and Download

To asynchronously wait for all changes to upload to Atlas from your synced realm, call uploadAllLocalChanges. This method returns true when all changes have been uploaded.

To asynchronously wait for all changes on Atlas to download from the Device Sync server to your synced realm, call downloadAllServerChanges. This method returns true when all changes have been downloaded.

You can also include an optional timeout parameter to either method to determine the maximum amount of time before returning false. Note that the upload or download continues in the background even after returning false.

The following example demonstrates calling both methods with a timeout defined:

// Wait to download all pending changes from Atlas
realm.syncSession.downloadAllServerChanges(1.minutes)
// Add data locally
realm.write {
    this.copyToRealm(Task().apply {
        taskName = "Review proposal"
        assignee = "Emma"
        progressMinutes = 0
    })
}
// Wait for local changes to be uploaded to Atlas
realm.syncSession.uploadAllLocalChanges(1.minutes)

Pause and Resume a Sync Session

To pause syncing for a session, call syncSession.pause(). The realm will not sync changes with Atlas while the session is paused.

To resume syncing a changes, call syncSession.resume().

You must manually call syncSession.pause() and syncSession.resume() for each realm whose Sync session you want to pause and restart. The sync state of one session has no impact on other open sessions.

The following code block demonstrates calling these methods:

// Pause the sync session
// Data that you write while session is paused does not sync to Atlas
realm.syncSession.pause()
// Add data locally
realm.write {
    this.copyToRealm(Task().apply {
        taskName = "Submit expense report"
        assignee = "Kevin"
        progressMinutes = 0
    })
}
// Resume sync session
// Local changes now sync to Atlas
realm.syncSession.resume()

Monitor Network Connection

You can get the state of the current network connection by checking the SyncSession.connectionState property. This returns a ConnectionState enum value that indicates the state of the network connection. The possible states are: CONNECTED, DISCONNECTED, or CONNECTING.

if (realm.syncSession.connectionState == ConnectionState.CONNECTED) {
    Log.i("Connected to network")
    // ... do something
}

Monitor the state of the network connection with connectionStateAsFlow. This property returns a Flow of ConnectionStateChange objects that updates when the network connection changes. You can access the new and old ConnectionState from ConnectionStateChange.

val connectionFlow = realm.syncSession.connectionStateAsFlow()
connectionFlow.collect { ConnectionStateChange ->
    if (ConnectionStateChange.newState == ConnectionState.CONNECTED) {
        Log.i("Connected to Atlas Device Sync server")
    }
}

Manually Reconnect All Sync Sessions

Realm automatically detects when a device regains connectivity after being offline and attempts to reconnect using an incremental backoff strategy.

In Kotlin SDK version 1.11.0 and later, you can choose to manually trigger a reconnect attempt with the App.Sync.reconnect() instead of waiting for the duration of the incremental backoff. This is useful if you have a more accurate understanding of the network conditions (for example, when monitoring network changes with the ConnectivityManager on Android) and don't want to rely on Realm's automatic reconnect detection. The SDK also automatically calls this method when a device toggles off airplane mode.

To manually trigger a reconnect attempt, call the App.Sync.reconnect() method, which is accessed through the App.Sync interface. Unlike SyncSession, which lets you access a single realm sync session, the App.Sync interface controls all sync sessions for your App.

app.sync.reconnect()

When you call this method, the SDK forces all sync sessions to attempt to reconnect immediately and resets any timers used for incremental backoff.