Realm のバンドル - Kotlin SDK
項目一覧
Overview
バージョン 1.9.0 の新機能。
Realm Kotlin SDK は、アプリケーションとの Realm ファイルのバンドルをサポートしています。 これにより、アプリケーションのダウンロード時にデータベースにシード データを事前に入力できます。
Tip
初期データコールバックまたは初期サブスクリプションを検討する
プラットフォームごとの Realm ロケーションのアセット
Realm Kotlin SDK は、バンドルされたアセット/リソースの従来のロケーションに基づいて、シード データを含むアセット レルムを検索します。
Android :
android.content.res.AssetManager.open(assetFilename)
を通じてJVM :
Class<T>.javaClass.classLoader.getResource(assetFilename)
Darwin:
NSBundle.mainBundle.pathForResource(assetFilenameBase, assetFilenameExtension)
アセット レルムは、作成後、適切な場所に配置する必要があります。 Realm を初めて開くときにアセット Realm が見つからない場合は、 Realm.open() はIllegalArgumentException
で失敗します。
同期されていない Realm のバンドル
アセット Realm へのシードデータの入力
新しい一時プロジェクトを作成して、アセット邦土を作成し、シード データを入力します。 このプロジェクトは、本番アプリと同じRealm オブジェクト スキーマを使用します。
シードするデータを使って既存の Realm を開くか、新しい Realm を作成します。 アセット邦土に特定の名前を設定し、アプリの初期データソースとして名前で参照できるようにします。
本番アプリケーションに含めるシード データをアセット邦土に入力します。
// Open a local realm to use as the asset realm val config = RealmConfiguration.Builder(schema = setOf(Item::class)) .name("asset.realm") .build() val assetRealm = Realm.open(config) assetRealm.writeBlocking { // Add seed data to the asset realm copyToRealm(Item().apply { summary = "Write an awesome app" isComplete = false }) } // Verify the data in the existing realm // (this data should also be in the bundled realm we open later) val originalItems: RealmResults<Item> = assetRealm.query<Item>().find() for(item in originalItems) { Log.v("Item in the assetRealm: ${item.summary}") } // Get the path to the realm Log.v("Realm location: ${config.path}") assetRealm.close()
アセット邦土が用意できたら、それを本番アプリケーションに移動して使用できます。
Tip
Realm は SDK 間で互換性があります
同じファイル形式を使用する Realm ファイルは、SDK 間で互換性があります。 本番アプリケーションにバンドルするアセット レルムをプログラムで作成する必要がある場合は、 Node.js SDKを使用して CI パイプラインと簡単に統合できます。
SDK バージョンでサポートされているファイル形式は、SDK の変更ログで確認できます。 これは、「ファイル形式: ファイル形式 v23 の Realm を生成する」のようになります。
本番アプリケーションで Realm ファイルをバンドルして開きます
アセット Realm ファイルのコピーを本番アプリケーションに保存します。 このアセット ファイルは、アプリのプラットフォームに適した場所に配置する必要があります。 詳細については、 「 プラットフォーム別のアセット Realm ロケーション 」を参照してください。
本番アプリがアセット邦土を開くために使用できる構成を作成します。 この構成内の
initialRealmFile
プロパティをアセット邦土の名前に設定します。オプションとして、
initialRealmFile
にsha256checkSum
を指定すると、Realm ファイルを開くときに整合性を確認できます。 シード邦土を開くときにアセット ファイルの計算されたチェックサム値と一致しないチェックサム値を指定すると、Realm.open()
はIllegalArgumentException
とともに失敗します。この構成では、バンドルされているアセット邦土を開くことができます。 これには、コピーした時点でアセット邦土に存在していたデータが含まれています。
// The config should list the bundled asset realm as the initialRealmFile val bundledRealmConfig = RealmConfiguration.Builder(schema = setOf(Item::class)) .initialRealmFile("asset.realm") .build() // After moving the bundled realm to the appropriate location for your app's platform, // open and use the bundled realm as usual. val bundledRealm = Realm.open(bundledRealmConfig) val bundledItems: RealmResults<Item> = bundledRealm.query<Item>().find() for(item in bundledItems) { Log.v("Item in the bundledRealm: ${item.summary}") } bundledRealm.close()
同期された Realm のバンドル
同期された Realm をバンドルすると、同期された Realm を使用する際にユーザーが最初に開くときにダウンロードする必要があるデータのサイズは縮小されますが、アプリのダウンロード ファイル サイズは大きくなります。 アセット Realm をアプリケーションにバンドルする場合、Realm を開くときにダウンロードする必要があるデータは、アセット Realm の準備以降に発生したすべての変更です。
重要
同期された Realm のバンドル
バックエンド アプリケーションでFlexible Syncが使用されている場合、バンドルされている Realm ファイルを初めて開くときにクライアントがリセットされる可能性があります。 これは、クライアント最大オフライン時間が有効になっている場合に発生する可能性があります(クライアントの最大オフライン時間はデフォルトで有効になっています)。 ユーザーが最初に同期する前に、バンドルされた Realm ファイルがクライアントの最大オフライン時間設定で指定された日数を超えて生成された場合、ユーザーはクライアントをリセットします。
クライアントリセットを実行するアプリケーションは、アプリケーション バックエンドから Realm の完全な状態をダウンロードします。 これにより、Realm ファイルをバンドルする利点が得られません。 クライアントのリセットを防ぎ、Realm ファイルのバンドルの利点を維持するには、次の手順に従います。
同期された Realm をバンドルするアプリケーションでは、クライアントの最大オフライン時間を使用しないでください。
アプリケーションがクライアントの最大オフライン時間を使用する場合は、アプリケーションのダウンロードに最近同期された Realm ファイルが常に含まれていることを確認してください。 アプリケーション バージョンごとに新しい ファイルを生成し、クライアントの最大オフライン時間数を超えてどのバージョンも最新の状態に維持します。
アプリケーションがFlexible Syncを使用している場合は、同期されたアセット Realm をバンドルする代わりに 最初の同期サブスクリプション を使用してアプリケーションにデータを入力できます。 最初のサブスクリプションでは、クライアントの最大オフライン時間よりも古いデータを心配する必要はありません。 同期サブスクリプションの使用の詳細については、「サブスクリプション 」を参照してください。
同期された Realm をバンドルするには、次の手順を実行します。
アセット Realm へのシードデータの入力
新しい一時プロジェクトを作成して、アセット邦土を作成して入力します。 このプロジェクトは、本番アプリと同じRealm オブジェクト スキーマを使用します。
アセット レルムとして使用する同期された Realmを開きます。
本番アプリケーションに含めるシード データをアセット邦土に入力します。 すべてのローカル変更が Device Sync サーバーと同期されるまで待つ必要があります。 すべての同期プロセスが完了するようにするには、 updateAllLogs()とDownloadAllServerChecks()を使用します。
val app = App.create(yourFlexAppId) // Login with user that has the server-side permissions to // read and write the data you want in the asset realm val user = app.login(credentials) // Create a SyncConfiguration to open a synced realm to use as the asset realm val assetRealmConfig = SyncConfiguration.Builder(user, setOf(Item::class)) .name("asset.realm") // Add a subscription that matches the data being added // and your app's backend permissions .initialSubscriptions{ realm -> add( realm.query<Item>("isComplete == $0", false), "Incomplete Items") } .build() val assetRealm = Realm.open(assetRealmConfig) assetRealm.subscriptions.waitForSynchronization(10.seconds) assertEquals(SubscriptionSetState.COMPLETE, assetRealm.subscriptions.state) assetRealm.writeBlocking { // Add seed data to the synced realm copyToRealm(Item().apply { summary = "Make sure the app has the data it needs" isComplete = false }) } // Verify the data in the existing realm // (this data should also be in the bundled realm we open later) val assetItems: RealmResults<Item> = assetRealm.query<Item>().find() for(item in assetItems) { Log.v("Item in the assetRealm: ${item.summary}") } // IMPORTANT: Sync all changes with server before copying the synced realm assetRealm.syncSession.uploadAllLocalChanges(30.seconds) assetRealm.syncSession.downloadAllServerChanges(30.seconds)
アセット Realm のコピーの作成
本番アプリケーションにバンドルできる一時的なプロジェクトから、アセット邦土のコピーを作成する必要があります。
アプリがアセット邦土のコピーを開くために使用できるSyncConfigurationを作成します。 この構成内の
initialRealmFile
プロパティをアセット邦土の名前に設定します。オプションとして、
initialRealmFile
にsha256checkSum
を指定すると、Realm ファイルを開くときに整合性を確認できます。 シード邦土を開くときに計算されたチェックサム値と一致しないチェックサム値を指定すると、Realm.open()
はIllegalArgumentException
とともに失敗します。// Create a SyncConfiguration for the bundled copy. // The initialRealmFile value is the `name` property of the asset realm you're bundling. val copyConfig = SyncConfiguration.Builder(user, setOf(Item::class)) .initialRealmFile("asset.realm") .build() writeCopyTo()を使用して、同期された Realm の新しいバージョンを作成します。 同期された Realm をバンドルするには、
writeCopyTo()
を使用する必要があります。 このメソッドは、Realm をユーザーに関連付けるメタデータを削除するため、他のユーザーも Realm ファイルを開くことができます。Realm.configuration.path を使用して、コピーされた Realm ファイルへのパスを取得します。
// Copy the synced realm with writeCopyTo() assetRealm.writeCopyTo(copyConfig) // Get the path to the copy you just created. // You must move this file into the appropriate location for your app's platform. Log.v("Bundled realm location: ${copyConfig.path}") assetRealm.close()
アセット邦土のコピーが作成できたら、それを本番アプリケーションに移動して使用できます。
本番アプリケーションで同期された Realm ファイルをバンドルして開きます
アセット Realm ファイルのコピーを本番アプリケーションに保存します。 このアセット ファイルは、アプリのプラットフォームに適した場所に配置する必要があります。 詳細については、 「 プラットフォーム別のアセット Realm ロケーション 」を参照してください。
アプリにバンドルされたアセット Realm のコピーが用意できたら、作成したコピーした Realm 構成を使用してこのアプリを開くことができます。 これには、コピーした時点でアセット邦土に存在していたデータが含まれています。
// After moving the bundled realm to the appropriate location for your app's platform, // open and use the bundled realm as usual. val copiedRealm = Realm.open(copyConfig) // This should contain the same Items as in the asset realm val copiedItems: RealmResults<Item> = copiedRealm.query<Item>().find() for(item in copiedItems) { Log.v("Item in the copiedRealm: ${item.summary}") } copiedRealm.close()