Realm の構成とオープン - Kotlin SDK
項目一覧
このページでは、Realm ファイルと、ローカルにのみデータを保持するRealmの構成、開き、閉じる方法について説明します。 Device Sync を使用して Atlas とデータを同期する Realm を開くには、「 同期された Realm の開き方 」を参照してください。
Realmは、Realm 内のデータを整理するために使用される主要データ構造です。 各 Realm は、Realm オブジェクトのコレクションです。つまり、アプリケーション内で使用するオブジェクトと、それらのオブジェクトを記述する追加のメタデータです。 各 Realm オブジェクトタイプには、定義したオブジェクトモデルに基づくオブジェクトスキーマがあります。
Realm スキーマは、Realm に含めることができる有効なオブジェクト スキーマのリストです。 Realm を開くときにスキーマを指定します。 Realm を開くときにすでにデータが含まれている場合、Realm は各オブジェクトを検証して、そのタイプにオブジェクト スキーマが提供されていること、およびスキーマで指定された制約をすべて満たしていることを確認します。
Realm ファイル
Realm stores a binary-encoded version of every object and type in a realm in a single .realm
file. Realm を開くと、Realm により.realm
ファイルがまだ存在しない場合はそれが作成されます。 ファイルは特定のパスにあり、Realm を開くときに定義できます。
.realm
ファイルまたはそれに関連する予備ファイルを作成しない場合は、インメモリ レルムを開くことができます。 詳細については、「 インメモリ Realm を開く」セクションを参照してください。
移動ファイル
Realm は、次のように Realm ごとに追加のファイルを作成します。
Realm ファイルの拡張子は「realm」。例:
default.realm
: オブジェクト データが含まれています。ロックファイル、"lock" の拡張子を持つファイル。例:
default.realm.lock
: Realm 内のどのバージョンのデータがアクティブに使用されているかを追跡する。 これにより、クライアント アプリケーションによってまだ使用されているストレージ領域が Realm により再利用されるのを防止します。メモ ファイルの拡張子は "note" で、例:
default.realm.note
: スレッド間通知とプロセス間通知を有効にします。管理ファイル、"management" で呼び出されるファイル。例:
default.realm.management
: 内部状態マネジメント。
これらのファイルの削除は重要な影響を与えます。 .realm
または予備ファイルの削除の詳細については、「 Realm の削除 」を参照してください。
Realm を開く
Realm を開くには、Realm の詳細を定義するRealmConfigurationオブジェクトを作成します。 次に、結果のRealmConfiguration
をRealm.open() に渡します。
デフォルト構成値を使用して Realm を開くことも、追加の構成オプションを使用してRealmConfiguration
を構築することもできます。 ただし、Realm で使用するすべての オブジェクト クラス を含む スキーマ パラメーターを渡す 必要 があります。
必要な構成で Realm を開き、定義されたスキーマに基づいてデータの読み取りと書き込みが可能になります。
このページの例では、次の Realm オブジェクトを参照します。
class Frog : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" } class Person : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" }
デフォルトの Realm を開く
デフォルト構成値を使用してRealmを開くには、 RealmConfiguration.create()を使用します。 使用して複数のドキュメントを挿入できます。 必要なのは、オブジェクト クラスのセットを Realm スキーマとして定義する必要があるだけです。 次に、 RealmConfiguration
をRealm.open() に渡します。
次の例では、default.realm
クラスと クラスを含むスキーマを含むデフォルトFrog
パス内のPerson
ファイルを開きます。
// Creates a realm with default configuration values val config = RealmConfiguration.create( // Pass object classes for the realm schema schema = setOf(Frog::class, Person::class) ) // Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // ... use the open realm ...
デフォルトのロケーション ファイル
Realm ファイルのディレクトリを定義しない場合、プラットフォームのデフォルトのアプリ ストレージ ロケーションが使用されます。 プラットフォームのデフォルトのディレクトリは次のとおりです。
Android:
Context.getFiles()
JVM:
System.getProperty("user.dir")
macOS:
platform.Foundation.NSFileManager.defaultManager.currentDirectoryPath
iOS:
NSFileManager.defaultManager.URLForDirectory( NSDocumentDirectory, NSUserDomainMask, null, true, null )
インメモリ Realm のオープン
メモリ内でRealm全体を開くことができます。この場合、 .realm
ファイルやそれに関連する予備ファイルは作成されません。 代わりに、SDK は Realm が開いている間にオブジェクトをメモリに保存し、すべての インスタンスが閉じられるとデータを破棄します。
ファイルに書き込まれずに実行されるRealmConfiguration
Realm を開くには、 inMemory プロパティを使用して RealmConfiguration.Builder で を構築します。次に、結果のRealmConfiguration
をRealm.open() に渡します。
// Create the in-memory realm configuration val config = RealmConfiguration.Builder( schema = setOf(Frog::class, Person::class) ) .inMemory() .build() // Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened an in-memory realm") // ... use the open realm ...
注意
インメモリ Realm は永続的ではない
インメモリ Realm は永続化されないため、データにアクセスする限り、Realm のオープンなインスタンスが少なくとも 1 つあることを確認してください。 インメモリ Realm の最後のインスタンスを閉じると、データは使用できなくなります。
Realm 構成のカスタマイズ
オープンする Realm の詳細を制御するために、 RealmConfiguration
に任意の引数を追加して、次のようなものを制御できます。
カスタムファイル名とファイルパスの定義
暗号化キーを渡してRealmを暗号化
Realm を圧縮してファイル サイズを縮小
スキーマ変更を行う際にスキーマのバージョンまたは移行ブロックを指定する
移行が必要な場合、Realm が Realmファイルを削除するかどうかのフラグメント化
具体的な構成実装の詳細については、「 Realm ファイルの管理 - Kotlin SDK 」を参照してください。
デフォルト以外の値でRealmを構成するには、 RealmConfiguration.Builder.Build()を通じてRealmConfiguration
を作成します と に、設定するプロパティを渡します。 次に、結果のRealmConfiguration
をRealm.open() に渡します。
次の例では、 RealmConfiguration
はカスタム名とディレクトリ("my-directory-path/myRealmName.realm")と暗号化キーを指定します。
// Create a realm configuration with configuration builder // and pass all optional arguments val config = RealmConfiguration.Builder( schema = setOf(Frog::class, Person::class) ) .name("myRealmName.realm") .directory("my-directory-path") .encryptionKey(myEncryptionKey) .build() // Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // ... use the open realm ...
Realm への初期データの追加
MongoDB Realm に初期データを追加するには、 initialDataCallbackを使用します。 コールバックは、Realm が初めて開かれたときにトリガーされます。
val config = RealmConfiguration.Builder( schema = setOf(Frog::class, Person::class) ) .initialData { copyToRealm(Frog().apply { name = "Kermit" }) copyToRealm(Person().apply { name = "Jim Henson" }) } .build() val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // Opened realm includes the initial data val initialFrog = realm.query<Frog>().find().first() val initialPerson = realm.query<Person>().find().first() Log.v("Realm initialized with: ${initialFrog.name} and ${initialPerson.name}")
Realm ファイル パスの検索
.realm
ファイルのファイルパスを見つけるには、 Realm.configuration.pathプロパティを使用します。
val realmPath = realm.configuration.path Log.v("Realm path: $realmPath")
Realm を閉じる
Realm.close()を使用して Realm を閉じます。 このメソッドは、Realm 上のすべての書込みトランザクションが完了するまでブロックします。
realm.close()
警告
メモリ リークを防ぐために Realm を閉じる
Realm インスタンスを閉じて リソースを解放することが重要です。 Realm を閉じるのに失敗すると、 OutOfMemoryError
が発生する可能性があります。
新しいRealmへのデータのコピー
既存の Realm から異なる構成オプションを持つ新しい Realm にデータをコピーするには、新しい構成をRealm.writeCopyTo() メソッドに 使用して複数のドキュメントを挿入できます。 たとえば、ローカル Realm をバックアップしたり、同期された Realm をローカル Realm に変換する方法としてデータをコピーできます。
同じ構成を使用する Realm にデータをコピーできます。
ローカルRealmからローカルRealmへ
インメモリRealmからインメモリRealmへ
同期されたRealmから同期されたRealm
さまざまな同期構成を使用する Realm にデータをコピーできます。
ローカルRealmからパーティションベースの同期Realm
ローカル Realm への同期済み Realm
同期されたRealmから別のユーザーの同期されたRealm
警告
ローカル Realm から Flexible Sync Realm にデータをコピーすることはできません。 パーティションベースの同期から Flexible Sync へなど、異なる同期構成タイプ間ではコピーできません。
構成の変更を組み合わせることもできます。 たとえば、暗号化されていない、メモリ内に同期された Realm から暗号化されたローカル Realm にデータをコピーできます。
Realm.writeCopyTo()
を使用する際に注意する必要がある追加の考慮事項がいくつかあります。
宛先ファイルがすでに存在することはできません。
書込みトランザクション内または移行中は、Realm をコピーできません。
Device Syncを使用する場合は、コピーが書き込まれる前に、すべてのローカル変更をサーバーと同期する必要があります。 これにより、そのファイルは新しくインストールされたアプリケーションの開始点として使用できるようになります。 保留中のアップロードがある場合、Realm はエラーをスローします。
すべての同期プロセスが完了するようにするには、 updateAllLogs()とDownloadAllServerchanges()を使用できます。
例
Flexible Sync Realm からローカル Realm へのデータのコピー
// Instantiate the synced realm with your App ID val app = App.create(YOUR_APP_ID) runBlocking { val user = app.login(credentials) // Create the synced realm configuration val syncConfig = SyncConfiguration.Builder(user, setOf(Frog::class)) .initialSubscriptions { realm -> add(realm.query<Frog>(),"all-frogs") } .build() // Open the synced realm and add data to it val syncRealm = Realm.open(syncConfig) Log.v("Successfully opened realm: ${syncRealm.configuration.name}") syncRealm.write { this.copyToRealm(Frog().apply { name = "Kermit" }) } // Wait for write to sync syncRealm.syncSession.uploadAllLocalChanges(30.seconds) // Create the local realm val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local.realm") .build() // Copy data from synced realm to the new realm syncRealm.writeCopyTo(localConfig) // Close the synced realm when you're done copying syncRealm.close() // Open the new local realm val localRealm = Realm.open(localConfig) // Copied Frog object is available in the new realm val frog = localRealm.query<Frog>().find().first() Log.v("Copied Frog: ${frog.name}") localRealm.close() }
また、コピーされた Realm の構成に新しい暗号化キーを含めたり、新しい構成から暗号化キーを削除したりすることもできます。
例
暗号化されていない Realm から暗号化された Realm へのデータのコピー
runBlocking { // Create the unencrypted realm val unencryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("unencrypted.realm") .build() // Open the realm and add data to it val unencryptedRealm = Realm.open(unencryptedConfig) unencryptedRealm.write { this.copyToRealm(Frog().apply { name = "Kermit" }) } // ... Generate encryption key ... // Create the encrypted realm val encryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("encrypted.realm") .encryptionKey(encryptionKey) .build() // Copy data from `unencryptedRealm` to the new realm // Data is encrypted as part of the copy process unencryptedRealm.writeCopyTo(encryptedConfig) // Close the original realm when you're done copying unencryptedRealm.close() // Open the new encrypted realm val encryptedRealm = Realm.open(encryptedConfig) // Copied Frog object is available in the new realm val frog = encryptedRealm.query<Frog>().find().first() Log.v("Copied Frog: ${frog.name}") encryptedRealm.close() }
例
インメモリからローカル Realm へのデータのコピー
runBlocking { // Create the in-memory realm val inMemoryConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("inMemory.realm") .inMemory() .build() // Open the realm and add data to it val inMemoryRealm = Realm.open(inMemoryConfig) inMemoryRealm.write { this.copyToRealm(Frog().apply { name = "Kermit" }) } // Create the local realm val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local.realm") .build() // Copy data from `inMemoryRealm` to the new realm inMemoryRealm.writeCopyTo(localConfig) // Close the original realm when you're done copying inMemoryRealm.close() // Open the new local realm val localRealm = Realm.open(localConfig) // Copied Frog object is available in the new realm val frog = localRealm.query<Frog>().find().first() Log.v("Copied Frog: ${frog.name}") localRealm.close() }