配置并打开同步 Realm - Kotlin SDK
本页介绍如何打开同步数据库以及各种可用的配置选项。
先决条件
从客户端访问同步 Realm 之前,您必须:
在 用户界面中 启用同步 。Atlas App Services
安装适用于Android的 Kotlin SDK 或Kotlin Multiplatform 的同步发行版。
对客户端项目中的用户进行身份验证。
打开同步 Realm
要打开Flexible Sync Realm,请将用户和一组 Realm 对象模式传递给SyncConfiguration.Builder() 。接下来,使用 initialSubscriptions()
构建器方法创建一组初始订阅。最后,将配置传递给Realm.open()以打开 Realm 的实例:
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 打开同步 Realm 时,您可以在打开该 Realm 之前使用.waitForInitialRemoteData()函数从应用程序下载变更集。设置此项会阻止 Realm 在所有数据下载完成之前打开。如果设备处于离线状态,则会阻止打开 Realm。由于初始数据下载可能是一个耗时的操作,因此您应该在后台线程上使用此设置打开一个 Realm。
此函数接受超时 持续时间 。当下载超过超时持续时间时,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,但前提是用户之前已在线登录。
仅当您不要求客户端应用程序在打开 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()