Realm オブジェクトの作成 - Kotlin SDK
項目一覧
- 書込みトランザクション (write transaction)
- 管理対象オブジェクトと非管理オブジェクト
- Realm オブジェクトの作成
- Realm オブジェクトの作成
- 埋め込みオブジェクトの作成
- 非対称オブジェクトの作成
- Realm プロパティの作成
- Realmインスタンス(タイムスタンプ)プロパティの作成
- MutableRealmInt(counter)プロパティの作成
- RealmAny(混合)プロパティの作成
- コレクション プロパティを作成
- RealmList の作成
- RealmSet プロパティの作成
- 辞書プロパティの作成
- 関係プロパティの作成
- To-1 の関係の作成
- ToMany 関係の作成
- 逆の関係の作成
- Realm オブジェクトまたはコレクションの非管理コピーの作成
This page describes the concepts of write transactions and managed objects in a realm, then explains how to create and persist a new object to a local or synced realm using the Kotlin SDK. Realm オブジェクトとその定義方法について詳しくは、「 Realm オブジェクト 」を参照してください。
Realm を開くと、Realm スキーマに含まれるオブジェクト タイプのオブジェクトを作成できます。 詳細については、「 Realm のオープン 」または「 同期された Realm のオープン」を参照してください。
注意
同期された Realm への書き込み
新しいオブジェクトを Realm に書き込む構文は、ローカル Realm または同期された Realm で同じです。 ただし、同期された Realm での書込み (write) 操作が成功するかどうかを判断する追加の考慮事項があります。 詳細については、「 同期された Realm へのデータの書き込み - Kotlin SDK 」を参照してください。
書込みトランザクション (write transaction)
Realm はトランザクション単位で書込みを処理します。 すべての書込み (write) はトランザクション内で発生する必要があります。 トランザクションは 、Realm が単一の不可分的な操作として扱う読み取り操作と書込み (write) 操作のリストです。すべての操作が成功するか、トランザクション内のどの操作が有効になりません。
Realm は、各トランザクションを 0 個以上の読み取りおよび書込み (write) 操作を含むコールバック関数として表します。 トランザクションを実行するには、トランザクション コールバックを定義し、Realm の write()またはwriteBlocking()メソッドに渡します。 このコールバック内でMutableRealmインスタンスにアクセスし、Realm 内のオブジェクトの作成、読み取り、更新、および削除を行うことができます。 ミューテーション可能なRealm は、Realm ファイルの書込み可能な状態を表します。 ミューテーション可能な Realm は、 realm.write
またはrealm.writeBlocking
メソッドによって自動的に提供および管理されます。
Realm では一度に 1 つの書込みトランザクションのみが許可されます。 Realm は、可変 Realm で開いているトランザクションが完了するまで、他のスレッドへの他の書込みをブロックします。 その結果、トランザクション内で Realm から値を読み取るときに競合状態は発生しません。
トランザクションが完了すると、Realm はトランザクションをコミットまたはキャンセルします。
Realm がトランザクションをコミットすると、Realm はすべての変更をディスクに書込みます。 同期された Realm の場合、SDK はバックエンドとの同期のために変更をキューに入れます。
Realm が書込みトランザクションをキャンセルするか、トランザクション内の操作によってエラーが発生すると、すべての変更は破棄されます。
注意
凍結されたオブジェクト
書込み (write) トランザクションが完了すると、書込み (write) クローニングから返されたオブジェクトは固定オブジェクトになります。 詳細については、 「 凍結されたアーキテクチャ - Kotlin SDK 」を参照してください。
管理対象オブジェクトと非管理オブジェクト
Realm API は、管理対象または未管理のオブジェクトを参照する場合があります。 Kotlin SDK を使用して Realm オブジェクトを作成すると、Realm にコピーされるまで管理されません。これにより、管理対象のインスタンスが作成されます。
管理対象オブジェクトは、Realm に永続する Realm オブジェクトです。 マネージド オブジェクトには、オープン レルムからのみアクセスできます。 Realm が開いている限り、書込みトランザクション (write transaction) 内の変更で更新されます。 管理対象オブジェクトは、管理対象オブジェクトが生成された Realm インスタンスに関連付けられており、別の Realm に書き込むことはできません。
管理対象のオブジェクトでは Realm API を使用できます。 たとえば、管理対象のオブジェクトは他のオブジェクトとの関係を持ち、変更を監視できます。 また、管理対象オブジェクトの管理されていないコピーを作成することもできます。このページの「 Realm オブジェクトまたはコレクションの非管理コピーの作成 」セクションを参照してください。
管理されていないオブジェクトは、通常の Kotlin オブジェクトと同様に動作する Realm オブジェクトのインスタンスですが、Realm に永続化されていません。 すべての Realm オブジェクトは、書込みトランザクション内の Realm にコピーするまで管理されません。 管理されていないオブジェクトでは Realm API を使用したり、変更を監視したりすることはできません。
Tip
isManaged()メソッドを使用して、オブジェクトが管理されているかどうかを確認できます。
Realm オブジェクトの作成
新しいオブジェクトを作成し、Realm に永続化する前に、 新しいオブジェクトタイプを定義する必要があります。 次に、Realm を開くときにそのオブジェクトタイプを Realm スキーマに含めます。
重要
オブジェクト タイプはスキーマ内になければなりません
Realm スキーマに含まれるオブジェクトタイプのみを書込みできます。 スキーマにないオブジェクトタイプのオブジェクトを参照または書込みしようとすると、Realm はスキーマ検証エラーを返します。
新しいオブジェクトを作成し、Realm に永続化するには:
Realm.write()を使用して書込みトランザクションを開きます またはRealm.writeBlocking() の
クラスコンストラクターを使用して、管理されていないオブジェクトインスタンスをインスタンス化します。 適用ブロック を使用できます 複数のプロパティを一度に構成します。
管理されていないオブジェクト インスタンスをcopyToRealm()に渡して、オブジェクト データを Realm に永続化します。 このメソッドは、 オブジェクトのライブマネージドインスタンスを返します。
重要
非対称オブジェクトは Insert() を使用する
非対称オブジェクトは、Realm に永続しない特殊な書込み専用オブジェクトです。
copyToRealm()
は使用されません。 代わりに、書込みトランザクション内で非対称オブジェクト インスタンスをinsert()
拡張メソッドに渡します。 詳細については、このページの「 非対称オブジェクトの作成」セクションを参照してください。返された インスタンスを通じて永続化された Realm オブジェクトを操作します。 ライブ オブジェクトには、書込みトランザクションが完了するまでアクセスできます。 これは、書込み専用でRealmに永続しない非対称オブジェクトには適用されないことに注意してください。
特定の基準を使用して、Realm にアップサートを実行することもできます。 詳細については、「 Realm オブジェクトのアップサート 」を参照してください。
Realm オブジェクトの作成
新しいRealmObject
インスタンスを作成するには、 Realm オブジェクトタイプの新しいオブジェクトをインスタンス化します。
次の例では、 realm.write()
ブロックでFrog
オブジェクトをインスタンス化し、インスタンス化されたオブジェクトをcopyToRealm()
に渡して管理対象インスタンスを返します。
// Open a write transaction realm.write { // Instantiate a new unmanaged Frog object val unmanagedFrog = Frog().apply { name = "Kermit" age = 42 owner = "Jim Henson" } assertFalse(unmanagedFrog.isManaged()) // Copy the object to realm to return a managed instance val managedFrog = copyToRealm(unmanagedFrog) assertTrue(managedFrog.isManaged()) // Work with the managed object ... }
埋め込みオブジェクトの作成
新しいEmbeddedRealmObject
インスタンスを作成するには、埋め込みオブジェクトタイプのインスタンスを親オブジェクトの プロパティに割り当てます。 これは、親オブジェクトタイプ内で埋め込みオブジェクトをどのように定義したかに応じて、1 対 1、1 対多、またはその逆の関係になる場合があります。 詳細については、「 埋め込みオブジェクトの定義 」を参照してください。
注意
埋め込みオブジェクトは親オブジェクト内に作成する必要があります
埋め込みオブジェクトには親オブジェクトが必要であり、独立した Realm オブジェクトとして存在することはできません。
埋め込みオブジェクトは親オブジェクトに対する厳密な所有権を持ちます。 埋め込みオブジェクトを作成した後は、それを別の親オブジェクトに再度割り当てたり、複数の親オブジェクト間で共有したりすることはできません。
次の例では、埋め込みAddress
を含む新しいContact
オブジェクトをインスタンス化します。このオブジェクトにはContact
オブジェクトと埋め込みCountry
オブジェクトが含まれます。
realm.write { // Instantiate a parent object with one embedded address val contact = Contact().apply { name = "Kermit" address = EmbeddedAddress().apply { propertyOwner = Contact().apply { name = "Mr. Frog" } street = "123 Pond St" country = EmbeddedCountry().apply { name = "United States" } } } // Copy all objects to the realm to return managed instances copyToRealm(contact) }
また、埋め込みAddress
オブジェクトのリストを使用して、新しいBusiness
オブジェクトをインスタンス化します。このオブジェクトには、 Contact
オブジェクトと埋め込みCountry
オブジェクトも含まれます。
realm.write { // Instantiate a parent object with multiple embedded addresses val localOffice = EmbeddedAddress().apply { propertyOwner = Contact().apply { name = "Michigan J. Frog" } street = "456 Lily Pad Ln" country = EmbeddedCountry().apply { name = "United States" } } val remoteOffice = EmbeddedAddress().apply { propertyOwner = Contact().apply { name = "Mr. Toad" } street = "789 Leaping Frog Ave" country = EmbeddedCountry().apply { name = "Ireland" } } val business = Business().apply { name = "Big Frog Corp." addresses = realmListOf(localOffice, remoteOffice) } // Copy all objects to the realm to return managed instances copyToRealm(business) }
非対称オブジェクトの作成
バージョン 1.10.0 の新機能。
他の Realm オブジェクトとは異なり、作成にcopyToRealm()
メソッドを使用することはありません。 これは、非対称オブジェクトが書込み専用であるためです。これらは Realm に永続化されていないためです。 代わりに、特別なinsert()
拡張メソッドを使用して Realm に挿入します。
新しいAsymmetricRealmObject
インスタンスを作成するには、 insert() を使用して、 非対称オブジェクトタイプ の新しいオブジェクトをインスタンス化します。
次の例では、新しいWeatherSensor
オブジェクトをインスタンス化し、書込みトランザクション内でinsert()
に渡します。
// Open a write transaction realm.write { // Create a new asymmetric object val weatherSensor = WeatherSensor().apply { deviceId = "WX1278UIT" temperatureInFarenheit = 6.7F barometricPressureInHg = 29.65F windSpeedInMph = 2 } // Insert the object into the realm with the insert() extension method insert(weatherSensor) // WeatherSensor object is inserted into the realm, then synced to the // App Services backend. You CANNOT access the object locally because it's // deleted from the local realm after sync is complete. }
挿入が行われると、非対称オブジェクトは App Services バックエンドとリンクされた Atlas データベースに同期します。 管理されているデータにローカルにアクセスしたり、Realm に追加したり削除したり、クエリを実行したりすることはできません。 アプリケーションで非対称オブジェクトを使用する方法の詳細については、「 Atlas へのデータのストリーム - Kotlin SDK 」を参照してください。
Realm プロパティの作成
オブジェクトタイプの定義方法によっては、 Realm 固有の特別なタイプであるプロパティがある場合があります。
次の例では、複数の Realm プロパティを持つFrog
オブジェクトタイプがあります。
class Frog : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" var birthdate: RealmInstant? = null var fliesEaten: MutableRealmInt? = null var favoriteThings: RealmList<RealmAny?> = realmListOf() }
Realmインスタンス(タイムスタンプ)プロパティの作成
Realmインスタンス プロパティを持つ新しいオブジェクト インスタンスを作成するには、オブジェクトをインスタンス化し、次のいずれかを使用して初期値をRealmInstant
プロパティに渡します。
Realmインスタンス.from() : UNIXエポック からの エポックセカンダリ と ナノ秒
Realmインスタンス.now() : UNIXエポックから現在までの oplogSeconds と ナノ秒
RealmInstant
型の詳細については、 「 Realmインスタンス(タイムスタンプ) 」を参照してください。
次の例えでは、 birthdate
プロパティを持つ新しいFrog
オブジェクトをインスタンス化し、初期値をRealmInstant.from()
に渡します。
realm.write { // Instantiate a new unmanaged Frog object with a RealmInstant property val frog = Frog().apply { name = "Kermit" // Set an initial value with RealmInstant.from() or RealmInstant.now() birthdate = RealmInstant.from(1_577_996_800, 0) } // Copy the object to the realm to return a managed instance copyToRealm(frog) }
MutableRealmInt(counter)プロパティの作成
MutableRealmIntプロパティを持つ新しいオブジェクト インスタンスを作成するには、オブジェクトをインスタンス化し、 MutableRealmInt.create()を使用して初期値をMutableRealmInt
プロパティに渡します。 MutableRealmInt
型の詳細については、 「 MutableRealmInt(counter) 」を参照してください。
次の例えでは、 fliesEaten
プロパティを持つ新しいFrog
オブジェクトをインスタンス化し、初期値をMutableRealmInt.create()
に渡します。
realm.write { // Instantiate a new unmanaged Frog object with a MutableRealmInt property val frog = Frog().apply { name = "Michigan J. Frog" // Set an initial value with MutableRealmInt.create() fliesEaten = MutableRealmInt.create(200) } // Copy the object to the realm to return a managed instance copyToRealm(frog) }
RealmAny(混合)プロパティの作成
多形のRealmAnyプロパティを持つ新しいオブジェクト インスタンスを作成するには、オブジェクトをインスタンス化し、 RealmAny.create()を使用してサポートされているタイプの初期値をRealmAny
プロパティに渡します。 RealmAny
が保持できる値の型のリストについては、「 RealmAny(混合) 」を参照してください。
次の例では、 RealmAny
タイプのfavoriteThings
リストを持つ新しいFrog
オブジェクトをインスタンス化し、初期値をRealmAny.create()
に渡します。
realm.write { // Instantiate a new unmanaged Frog object with a RealmAny property val frog = Frog().apply { name = "Kermit" // Set initial values with RealmAny.create() favoriteThings = realmListOf( RealmAny.create(42), RealmAny.create("rainbows"), RealmAny.create(Frog().apply { name = "Kermit Jr." }) ) } // Copy the object to the realm to return a managed instance copyToRealm(frog) }
オブジェクトを作成した後、 RealmAny
プロパティを操作するために保存される値の型を知っている必要があります。 オブジェクトの作成後にRealmAny
プロパティを更新する方法については、「 RealmAny(混合)プロパティの更新 」を参照してください。
コレクション プロパティを作成
オブジェクトタイプの定義方法によっては、サポートされている次のコレクション タイプのいずれかとして定義されるプロパティがある場合があります。
RealmList
RealmSet
RealmDictionary
詳細については、「コレクション プロパティの定義 」を参照してください。
コレクションは可変です。書込みトランザクション内でコレクション内の要素を追加および削除できます。
コレクションには、マネージド オブジェクトとマネージド オブジェクトの両方を含めることができます。 コレクションを Realm にコピーすると、コレクションとコレクション内のすべての要素の管理対象インスタンスが作成されます。これには管理されていない要素も含まれます。 管理されていないコレクションは、対応する Kotlin クラスと同様に動作し、Realm に永続化しません。
Tip
作成されたコレクションへの変更のリッスン
コレクションを作成したら、変更をリッスンするための通知ハンドラーを登録できます。 詳細については、「 コレクション変更リスナーの登録 」を参照してください。
RealmList の作成
RealmListプロパティを持つ新しいオブジェクト インスタンスを作成するには、オブジェクトをインスタンス化し、サポートされているタイプの値をRealmList
プロパティに渡します。 RealmList
が保持できる値の型のリストについては、 RealmList を参照してください。
RealmListOf() を使用して非管理リストをインスタンス化するか、 list.add ()を使用して要素をリストに渡すことができます。 list.addAll() 、またはlist.set() 。 リストは、Realm にコピーするまで管理されません。
次の例では、複数のRealmList
プロパティの初期値を持つ新しいFrog
オブジェクトをインスタンス化します。
realm.write { // Instantiate a new unmanaged Frog object with a RealmList property val frog = Frog().apply { name = "Kermit" // Set values for each unmanaged list favoritePonds.addAll(realmListOf( Pond().apply { name = "Picnic Pond" }, Pond().apply { name = "Big Pond" } )) favoriteForests.add(EmbeddedForest().apply { name = "Hundred Acre Wood" }) favoriteWeather = realmListOf("rain", "snow") } // Copy all objects to the realm to return managed instances copyToRealm(frog) }
RealmSet プロパティの作成
RealmSetプロパティを持つ新しいオブジェクト インスタンスを作成するには、オブジェクトをインスタンス化し、サポートされているタイプの値をRealmSet
プロパティに渡します。 RealmSet
が保持できる有効なタイプのリストについては、 RealmSet を参照してください。
RealmSetOf()を使用して非管理セットをインスタンス化するか、 set.add()またはset.addAll( ) を使用してセットに要素を渡すことができます。 セットは、Realm にコピーするまで管理されません。
次の例では、 favoriteSnacks
とfavoriteWeather
が設定したプロパティの初期値を持つ新しいFrog
オブジェクトをインスタンス化します。
realm.write { // Instantiate a new unmanaged Frog object with RealmSet properties val frog = Frog().apply { name = "Kermit" // Set initial values to each unmanaged set favoriteSnacks.addAll(setOf( Snack().apply { name = "flies" }, Snack().apply { name = "crickets" }, Snack().apply { name = "worms" } )) favoriteWeather.add("rain") } // Copy all objects to the realm to return managed instances copyToRealm(frog) }
辞書プロパティの作成
RealmDictionaryプロパティを持つ新しいオブジェクト インスタンスを作成するには、オブジェクトをインスタンス化し、サポートされているタイプのキーと値のペアをRealmDictionary
プロパティに渡します。 RealmDictionary
はString
キーのみを受け入れますが、値は文字列以外の型になる可能性があります。 有効なタイプのリストについては、 RealmMap/RealmDictionary を参照してください。
RealmDictionaryOf()またはRealmDictionaryEntryOf( ) を使用して、管理されていない辞書をインスタンス化できます。 または、 put()またはputAll()を使用してキー値を渡すこともできます。 辞書は、Realm にコピーするまで管理されません。
次の例では、複数の辞書プロパティの初期キー値を持つ新しいFrog
オブジェクトをインスタンス化します。
realm.write { val frog = Frog().apply { name = "Kermit" // Set initial key-values to each unmanaged dictionary favoriteFriendsByPond = realmDictionaryOf( "Picnic Pond" to Frog().apply { name = "Froggy Jay" }, "Big Pond" to Frog().apply { name = "Mr. Toad" } ) favoriteTreesInForest["Maple"] = EmbeddedForest().apply { name = "Hundred Acre Wood" } favoritePondsByForest.putAll( mapOf( "Silver Pond" to "Big Forest", "Big Lake" to "Elm Wood", "Trout Pond" to "Sunny Wood" ) ) } // Copy all objects to the realm to return managed instances copyToRealm(frog) }
Realm では、マップキーに.
または$
文字を使用できません。 パーセント エンコーディングとデコーディング を使用して、これらの許可されていない文字の 1 つを含むマップキーを保存できます。
// Percent encode . or $ characters to use them in map keys val mapKey = "Hundred Acre Wood.Northeast" val encodedMapKey = "Hundred Acre Wood%2ENortheast"
関係プロパティの作成
オブジェクトタイプの定義方法によっては、別の Realm オブジェクトを参照するプロパティがある場合があります。 これは 1 対 1、対多、または 逆の関係にすることができます。 オブジェクトモデルで関係を定義する方法の詳細については、「関係の定義 」を参照してください。
また、ある Realm オブジェクトを別の Realm オブジェクトに直接埋め込み、 EmbeddedRealmObject
タイプのネストされたデータ構造を作成することもできます。 埋め込みオブジェクトとの関係を作成するには、このページの「 埋め込みオブジェクトの作成」セクションを参照してください。
To-1 の関係の作成
対1 の関係プロパティを持つ新しいオブジェクト インスタンスを作成するには、両方のオブジェクトをインスタンス化し、参照されたオブジェクトを関係プロパティに渡します。
次の例では、 Pond
オブジェクトを参照するfavoritePond
プロパティと、別のFrog
オブジェクトを参照するbestFriend
プロパティを持つ新しいFrog
オブジェクトをインスタンス化します。
realm.write { // Instantiate a new unmanaged Frog object with to-one // relationship with a Realm object val frog = Frog().apply { name = "Kermit" age = 12 favoritePond = Pond().apply { name = "Picnic Pond" } bestFriend = Frog().apply { name = "Froggy Jay" } } // Copy all objects to the realm to return managed instances copyToRealm(frog) }
ToMany 関係の作成
対多の関係プロパティを持つ新しいオブジェクト インスタンスを作成するには、すべてのオブジェクトをインスタンス化し、参照されるオブジェクトを関係コレクション プロパティに渡します。
次の例では、 Frog
オブジェクトのセットを参照するfrogsThatLiveHere
プロパティと、 Pond
オブジェクトのリストを参照するnearByPonds
プロパティを持つ新しいForest
オブジェクトをインスタンス化します。
realm.write { // Instantiate a new unmanaged Forest object with to-many // relationship with multiple Realm objects val forest = Forest().apply { name = "Froggy Forest" frogsThatLiveHere = realmSetOf( Frog().apply { name = "Kermit" }, Frog().apply { name = "Froggy Jay" } ) nearbyPonds = realmListOf( Pond().apply { name = "Small Picnic Pond" }, Pond().apply { name = "Big Pond" } ) } // Copy all objects to the realm to return managed instances copyToRealm(forest) }
逆の関係の作成
逆の関係プロパティを持つ新しいオブジェクト インスタンスを作成するには、親オブジェクトをインスタンス化し、参照された子オブジェクトをバックリンク コレクション プロパティに渡します。
次の例では、 Post
オブジェクトのリストを参照するバックリンクposts
プロパティを使用して、新しいUser
オブジェクトをインスタンス化します。
realm.write { // Instantiate a new unmanaged User object with to-many // relationship with multiple Realm objects val post1 = Post().apply { title = "Forest Life" } val post2 = Post().apply { title = "Top Ponds of the Year!" } val user = User().apply { name = "Kermit" posts = realmListOf(post1, post2) } // Copy all objects to the realm to return managed instances copyToRealm(user) }
オブジェクトを作成した後、 backlinks コレクション プロパティにアクセスして子オブジェクトを取得できますが、バックリンク自体を直接変更することはできません。 詳細については、「 逆の関係の更新 」を参照してください。
Realm オブジェクトまたはコレクションの非管理コピーの作成
管理対象のオブジェクトまたはコレクションの管理されていないコピーは、 copyFromRealm()に渡すことで作成できます。 このメソッドは、オブジェクトまたはコレクションの管理されていないメモリ内のコピーを返します。 コレクションの場合、指定されたdepth
までのすべての参照オブジェクトを含むディープ コピーです。
次の例では、2 つのFrog
オブジェクトのリストを含む既存の管理対象Pond
オブジェクトの管理されていないコピーを作成します。 Realm からオブジェクトをコピーした後、コピーが管理されておらず、参照されたFrog
オブジェクトの両方が含まれていることを確認します。
realm.writeBlocking { // Fetch the managed object you want to copy val managedPond = query<Pond>("name == $0", "Big Pond").find().first() assertTrue(managedPond.isManaged()) // Create an unmanaged copy of the object val unmanagedPond = copyFromRealm(managedPond) assertFalse(unmanagedPond.isManaged()) Log.v("Unmanaged pond name: ${unmanagedPond.name}") // Confirm the unmanaged copy contains all elements // in the copied object's RealmList val unmanagedFrogs = unmanagedPond.frogsThatLiveHere assertFalse(unmanagedFrogs[0].isManaged()) assertFalse(unmanagedFrogs[1].isManaged()) assertEquals(2, unmanagedFrogs.size) Log.v("Unmanaged frogs: ${unmanagedFrogs[0].name}, ${unmanagedFrogs[1].name}") }
Unmanaged pond name: Big Pond Unmanaged frogs: Kermit, Froggy Jay