配置并打开同步 Realm - Kotlin SDK

在此页面上

先决条件

打开同步 Realm
配置同步 Realm
打开前下载更改
在打开之前有条件地下载更改
离线打开同步 Realm

Atlas Device SDK 已弃用。有关详细信息，请参阅弃用页面。

本页介绍如何打开同步数据库以及各种可用的配置选项。

先决条件

从客户端访问同步 Realm 之前，您必须：

在用户界面中启用同步。Atlas App Services
安装适用于Android的 Kotlin SDK 或Kotlin Multiplatform 的同步发行版。
对客户端项目中的用户进行身份验证。

打开同步 Realm

要打开Flexible Sync 域，请将用户和一设立Realm 对象模式传递给SyncConfiguration.Builder() 。接下来，使用 initialSubscriptions()构建器方法创建一设立初始订阅。最后，将配置传递给Realm .open()以打开域的实例：

val app = App.create(YOUR_APP_ID)
// use constants for query names so you can edit or remove them later
val NAME_QUERY = "NAME_QUERY"
runBlocking {
    val user = app.login(Credentials.anonymous())
    val config = SyncConfiguration.Builder(user, setOf(Toad::class))
        .initialSubscriptions { realm ->
            add(
                realm.query<Toad>(
                    "name == $0",
                    "name value"
                ),
                "subscription name"
            )
        }
        .build()
    val realm = Realm.open(config)
    Log.v("Successfully opened realm: ${realm.configuration.name}")
    realm.close()
}

有关使用初始订阅引导域和托管同步域订阅的更多信息，请参阅托管同步订阅。

配置同步 Realm

要调整特定配置设置，请使用SyncConfiguration.Builder 提供的选项：

val app = App.create(YOUR_APP_ID)
runBlocking {
    val user = app.login(Credentials.anonymous())
    val config = SyncConfiguration.Builder(user, setOf(Toad::class))
        .maxNumberOfActiveVersions(10)
        .name("realm name")
        .initialSubscriptions { realm ->
            add(
                realm.query<Toad>(
                    "name == $0",
                    "name value"
                ),
                "subscription name"
            )
        }
        .build()
    val realm = Realm.open(config)
    Log.v("Successfully opened realm: ${realm.configuration}")
    realm.close()
}

1.13.0 版本新增：添加了同步超时配置选项

在 Kotlin v1.13.0 中，您可以覆盖用于同步操作的各种默认超时。您可以在App客户端配置中设置这些超时，它们适用于应用程序中的所有同步会话。要了解如何操作，请参阅配置同步超时。

打开前下载更改

当您使用Kotlin SDK打开同步域时，您可以使用.waitForInitialRemoteData() 函数在打开域之前从应用程序下载变更集。设置此项会阻止域在所有数据下载完成之前打开。如果设备离线，则会阻止打开域。由于初始数据下载可能是一个耗时的操作，因此您应该在背景线程上使用此设置打开一个域。

此函数接受超时持续时间。当下载超过超时持续时间时， Realm会抛出 DownloadingRealmTimeoutException。

val user = app.login(Credentials.emailPassword(email, password))
val config = SyncConfiguration.Builder(user, setOf(Toad::class))
    .waitForInitialRemoteData(60.seconds)
    .initialSubscriptions { realm ->
        add(
            realm.query<Toad>(
                "name == $0",
                "Jeremiah"
            ),
            "toads_named_jeremiah"
        )
    }
    .build()
val realm = Realm.open(config)
Log.v("Successfully opened realm: ${realm.configuration}")
// Query the realm we opened after waiting for data to download, and see that it contains data
val downloadedToads: RealmResults<Toad> = realm.query<Toad>().find()
Log.v("After downloading initial data, downloadedToads.size is ${downloadedToads.size}")
realm.close()

在打开之前有条件地下载更改

如果存在一个条件，决定应用程序在打开 Realm 之前是否应下载服务器数据，则可以将其与SyncSession.downloadAllServerChanges()一起使用，以便在打开 Realm 之前有条件地下载更改。调用此方法会阻塞，直到所有已知的远程更改都已下载并应用到 Realm，或者达到指定的超时时间。您应该只从非用户界面线程中调用此方法。

此函数接受超时持续时间。

val user = app.login(Credentials.emailPassword(email, password))
val config = SyncConfiguration.Builder(user, setOf(Toad::class))
    .initialSubscriptions { realm ->
        add(
            realm.query<Toad>(
                "name == $0",
                "Lollihops"
            ),
            "toads_named_lollihops"
        )
    }
    .build()
val realm = Realm.open(config)
// Conditionally download data before using the realm based on some business logic
if (downloadData) {
    realm.syncSession.downloadAllServerChanges(30.seconds)
}
// Query the realm we opened after waiting for data to download, and see that it contains data
val downloadedToads: RealmResults<Toad> = realm.query<Toad>().find()
Log.v("After conditionally downloading data, downloadedToads.size is ${downloadedToads.size}")
realm.close()

离线打开同步 Realm

当您的 Realm 应用程序对用户进行身份验证时，它会缓存该用户的档案。您可以检查是否存在现有用户档案以绕过登录流程并访问已缓存的用户。使用它可离线打开一个 Realm。

注意

初始登录需要网络连接

当用户注册您的应用或使用客户端上的现有帐户首次登录时，客户端必须具有网络连接。通过检查是否存在已缓存的用户档案，您可以离线打开 Realm，但前提是用户之前已在线登录。

仅当您不要求客户端应用在打开域之前下载更改时，才能离线打开该域。

// You can only open a synced realm offline if there is a cached user credential. If
// there is no app.currentUser, you must log them in, which requires a network connection.
if (app.currentUser == null) {
    app.login(Credentials.emailPassword(email, password))
}
// If the app.currentUser isn't null, you can use the cached credential to open the synced
// realm even if the user is offline.
val user = app.currentUser!!
val realm = Realm.open(config)
// Query the realm we opened, and see that it contains data
val offlineToads: RealmResults<Toad> = realm.query<Toad>().find()
Log.v("After opening a realm offline, offlineToads.size is ${offlineToads.size}")
realm.close()

后退

为应用添加同步功能

来年

管理订阅