Docs Menu
Docs Home
/ /
Atlas Device SDK
/ /

Realm の構成とオープン - Kotlin SDK

項目一覧

  • Realm ファイル
  • 移動ファイル
  • Realm を開く
  • デフォルトの Realm を開く
  • インメモリ Realm のオープン
  • Realm 構成のカスタマイズ
  • Realm への初期データの追加
  • Realm ファイル パスの検索
  • Realm を閉じる
  • 新しいRealmへのデータのコピー

このページでは、Realm ファイルと、ローカルにのみデータを保持するRealmの構成、開き、閉じる方法について説明します。 Device Sync を使用して Atlas とデータを同期する 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 を開くときに定義できます。

Tip

Realm Studio での 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 の詳細を定義するRealmConfigurationオブジェクトを作成します。 次に、結果のRealmConfigurationRealm.open() に渡します。

デフォルト構成値を使用して Realm を開くことも、追加の構成オプションを使用してRealmConfigurationを構築することもできます。 ただし、Realm で使用するすべての オブジェクト クラス を含む スキーマ パラメーターを渡す 必要 があります。

必要な構成で Realm を開き、定義されたスキーマに基づいてデータの読み取りと書き込みが可能になります。

このページの例では、次の Realm オブジェクトを参照します。

class Frog : RealmObject {
@PrimaryKey
var _id: ObjectId = ObjectId()
var name: String = ""
}
class Person : RealmObject {
@PrimaryKey
var _id: ObjectId = ObjectId()
var name: String = ""
}

デフォルト構成値を使用してRealmを開くには、 RealmConfiguration.create()を使用します。 使用して複数のドキュメントを挿入できます。 必要なのは、オブジェクト クラスのセットを Realm スキーマとして定義する必要があるだけです。 次に、 RealmConfigurationRealm.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ファイルやそれに関連する予備ファイルは作成されません。 代わりに、SDK は Realm が開いている間にオブジェクトをメモリに保存し、すべての インスタンスが閉じられるとデータを破棄します。

ファイルに書き込まれずに実行されるRealmConfiguration Realm を開くには、 inMemory プロパティを使用して RealmConfiguration.Builder で を構築します。次に、結果のRealmConfigurationRealm.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 の詳細を制御するために、 RealmConfigurationに任意の引数を追加して、次のようなものを制御できます。

具体的な構成実装の詳細については、「 Realm ファイルの管理 - Kotlin SDK 」を参照してください。

デフォルト以外の値でRealmを構成するには、 RealmConfiguration.Builder.Build()を通じてRealmConfigurationを作成します と に、設定するプロパティを渡します。 次に、結果のRealmConfigurationRealm.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 ...

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.configuration.pathプロパティを使用します。

val realmPath = realm.configuration.path
Log.v("Realm path: $realmPath")

Realm.close()を使用して Realm を閉じます。 このメソッドは、Realm 上のすべての書込みトランザクションが完了するまでブロックします。

realm.close()

警告

メモリ リークを防ぐために Realm を閉じる

Realm インスタンスを閉じて リソースを解放することが重要です。 Realm を閉じるのに失敗すると、 OutOfMemoryErrorが発生する可能性があります。

既存の 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()
}

戻る

Device Sync によるモデルデータ