基于分区的同步 — Java SDK

在此页面上

分区值

打开同步 Realm
在线时打开同步 Realm
离线时打开同步 Realm
从基于分区的同步迁移到 Flexible Sync
迁移后更新客户端代码

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

基于分区的同步是将 Atlas Device Sync 与 Realm Java SDK 结合使用的一种较旧模式。我们建议对新应用使用Flexible Sync 。此页面上的信息适用于仍在使用基于分区的同步的用户。

提示

Realm Java SDK v 10.16.0及更高版本能力从基于分区的同步迁移到 Flexible Sync。有关更多信息，请参阅：从基于分区的同步迁移到 Flexible Sync。

有关基于分区的同步以及如何在Atlas App Services中配置该同步的更多信息，请参阅App Services文档中的基于分区的同步。

分区值

当您为后端应用配置选择基于分区的同步时，您的客户端实施必须包含分区值。这是您在配置基于分区的同步时选择的分区键字段的值。

分区值决定客户端应用程序可以访问哪些数据。

您可以在打开同步 Realm 时传入分区值。

打开同步 Realm

要配置 Realm 的设置，请使用 SyncConfiguration.Builder 创建SyncConfiguration 。

以下示例将同步 Realm 配置为：

基于分区的同步
用户界面线程上显式允许的同步读取
用户界面线程上显式允许的同步写入
在返回开放 Realm 之前，显式等待所有后端更改同步到设备
启动 Realm 时自动压缩，节省文件空间

警告

生产应用程序应处理客户端重置

生产环境中使用的应用程序应处理客户端重置错误。要了解更多信息，请参阅重置客户端 Realm。

SyncConfiguration config = new SyncConfiguration.Builder(app.currentUser(), PARTITION)
        .allowQueriesOnUiThread(true)
        .allowWritesOnUiThread(true)
        .waitForInitialRemoteData(500, TimeUnit.MILLISECONDS)
        .compactOnLaunch()
        .build();
Realm.getInstanceAsync(config, new Realm.Callback() {
    @Override
    public void onSuccess(Realm realm) {
        Log.v("EXAMPLE", "Successfully opened a realm.");
    }
});

val config =
    SyncConfiguration.Builder(app.currentUser(), PARTITION)
        .allowQueriesOnUiThread(true)
        .allowWritesOnUiThread(true)
        .waitForInitialRemoteData(500, TimeUnit.MILLISECONDS)
        .compactOnLaunch()
        .build()
Realm.getInstanceAsync(config, object : Realm.Callback() {
    override fun onSuccess(realm: Realm) {
        Log.v("EXAMPLE", "Successfully opened a realm.")
    }
})

重要

UI 线程上的同步读写

默认情况下，您只能使用异步事务在应用程序的 UI 线程中读取或写入 Realm。也就是说，除非您明确允许使用同步方法，否则您只能在 Android 应用程序的主线程中使用名称以单词Async结尾的 Realm方法。

此限制是为了应用程序用户的利益：在 UI 线程上执行读写操作，可能导致 UI 交互无响应或速度缓慢，所以通常来说，最好以异步方式或在后台线程中处理这些操作。但是，如果应用程序需要在 UI 线程上使用同步 Realm 读取或写入，则可以通过以下 SyncConfiguration 选项明确支持使用同步方法：

SyncConfiguration config = new SyncConfiguration.Builder(app.currentUser(), PARTITION)
        .allowQueriesOnUiThread(true)
        .allowWritesOnUiThread(true)
        .build();
Realm.getInstanceAsync(config, new Realm.Callback() {
    @Override
    public void onSuccess(Realm realm) {
        Log.v(
                "EXAMPLE",
                "Successfully opened a realm with reads and writes allowed on the UI thread."
        );
    }
});

val config = SyncConfiguration.Builder(app.currentUser(), PARTITION)
    .allowQueriesOnUiThread(true)
    .allowWritesOnUiThread(true)
    .build()
Realm.getInstanceAsync(config, object : Realm.Callback() {
    override fun onSuccess(realm: Realm) {
        Log.v("EXAMPLE", "Successfully opened a realm with reads and writes allowed on the UI thread.")
    }
})

在线时打开同步 Realm

要打开同步域，请调用getInstanceAsync() ，并传入SyncConfiguration对象。以下代码演示了如何使用使用SyncConfiguration对象创建的特定同步设置来创建域：

SyncConfiguration config = new SyncConfiguration.Builder(app.currentUser(), PARTITION)
        .allowQueriesOnUiThread(true)
        .allowWritesOnUiThread(true)
        .build();
Realm.getInstanceAsync(config, new Realm.Callback() {
    @Override
    public void onSuccess(Realm realm) {
        Log.v(
                "EXAMPLE",
                "Successfully opened a realm with reads and writes allowed on the UI thread."
        );
    }
});

val config = SyncConfiguration.Builder(app.currentUser(), PARTITION)
    .allowQueriesOnUiThread(true)
    .allowWritesOnUiThread(true)
    .build()
Realm.getInstanceAsync(config, object : Realm.Callback() {
    override fun onSuccess(realm: Realm) {
        Log.v("EXAMPLE", "Successfully opened a realm with reads and writes allowed on the UI thread.")
    }
})

上面的代码展示了如何使用 getInstanceAsync() 异步打开 Realm。您还可以使用getInstance()同步打开一个 Realm，该方法会在同步来自后端的所有数据之前返回一个打开的 Realm。但是，这可能会导致下载远程数据时暂时出现数据不一致，一般不建议这样做。您可以使用waitForInitialRemoteData()配置选项，强制 SDK 在打开 Realm 之前获取远程数据，从而避免这些不一致。

分区值指定要同步的数据子集。这通常是应用程序中与当前用户特别相关的用户 ID、项目 ID、商店 ID 或其他类别标识符。

离线时打开同步 Realm

您可以使用与在线打开同步域完全相同的语法在离线时在线域。并非所有 SDK 都遵循这种模式，因此跨平台开发者应查阅每个 SDK 的文档以学习；了解更多信息。

从基于分区的同步迁移到 Flexible Sync

您可以将 App Services Device Sync 模式从基于分区的同步迁移到 Flexible Sync。迁移是一个自动过程，无需对应用程序代码进行任何更改。自动迁移需要 Realm Java SDK 版本 10.16.0 或更高版本。

通过迁移，您可以保留现有的 App Services 用户和身份验证配置。 Flexible Sync提供更通用的权限配置选项和更细粒度的数据同步。

有关如何将App Services App从基于分区的同步迁移到Flexible Sync的更多信息，请参阅迁移Device Sync模式。

迁移后更新客户端代码

从基于分区的同步自动迁移到Flexible Sync不需要对客户端代码进行任何更改。但是，为了支持此功能，Realm 会通过以下方式自动处理两种同步模式之间的差异：

自动为每个Realm 对象类型创建Flexible Sync订阅，其中partitionKey == partitionValue 。
将partitionKey字段注入到每个对象中（如果尚不存在）。这是自动Flexible Sync订阅所必需的。

如果您需要在迁移后更新客户端代码，请考虑更新客户端代码库以删除隐藏的迁移功能。在以下情况下，您可能需要更新客户端代码库：

您在客户端代码库中添加新模型或更改模型
添加或更改涉及读取或写入 Realm 对象的功能
您希望对同步的数据实施更细粒度的控制

进行以下更改，将基于分区的同步客户端代码转换为使用 Flexible Sync：

更新SyncConfiguration.Builder以使用Flexible Sync 。这包括删除partitionValue并根据需要添加一组初始订阅。
将相关属性添加到对象模型中，以便在 Flexible Sync 订阅中使用。例如，您可以添加ownerId属性，使用户能够仅同步自己的数据。
删除自动Flexible Sync订阅。如果您没有在SyncConfiguration.Builder中添加初始订阅，请手动创建相关订阅。

有关 Flexible Sync 权限策略的示例，包括如何为这些策略进行数据建模的示例，请参阅Device Sync权限指南。

删除和手动创建订阅

当您从基于分区的同步迁移到Flexible Sync时，Realm 会自动为您的应用创建隐藏的Flexible Sync订阅。下次添加或更改订阅时，我们建议您：

这样，您就可以在代码库中同时查看所有订阅逻辑，以便将来进行迭代和调试。

有关自动生成的Flexible Sync订阅的更多信息，请参阅将客户端应用程序迁移到Flexible Sync。

后退

后台同步

来年

测试与调试