Docs Menu
Docs Home
/ /
Realm

직렬화 - 코틀린 SDK (Kotlin SDK)

Realm 코틀린 SDK (Kotlin SDK)는 코틀린 (Kotlin) 직렬화를 지원합니다. 안정적인 직렬 변환기를 사용하여 특정 Realm 데이터 유형을 직렬화하거나 실험적인 전체 문서 직렬화 API를 사용하여 사용자 정의 클래스를 직렬화할 수 있습니다.

Realm 코틀린 SDK (Kotlin SDK)는 KSerializer에 대해 다음 데이터 유형에 대한 직렬 변환기를 제공합니다.

Realm 데이터 유형
유형별 KSerializer

MutableRealmInt

MutableRealmIntKSerializer::class

RealmAny

RealmAnyKSerializer::class

RealmDictionary

RealmDictionaryKSerializer::class

RealmInstant

RealmInstantKSerializer::class

RealmList

RealmListKSerializer::class

RealmSet

RealmSetKSerializer::class

RealmUUID

RealmUUIDKSerializer::class

직렬 변환기는 io.realm.kotlin.serializers 에 있습니다.

Realm 이 다양한 데이터 유형을 직렬화하는 방법에 대한 예시는 직렬화 출력 예시를 참조하세요.

Realm 데이터 유형을 역직렬화하면 관리되지 않는 데이터 인스턴스가 생성됩니다.

특정 속성에 대한 직렬 변환기를 등록할 수 있습니다. @Serializable 주석을 사용하여 특정 Realm 데이터 유형 직렬 변환기에 바인딩합니다.

class Frog : RealmObject {
var name: String = ""
@Serializable(RealmListKSerializer::class)
var favoritePonds: RealmList<String> = realmListOf()
}

파일 상단에 선언을 추가하여 파일 내에서 해당 유형이 모든 항목에 대해 직렬 변환기를 등록할 수 있습니다.

@file:UseSerializers(RealmSetKSerializer::class)
import io.realm.kotlin.ext.realmSetOf
import io.realm.kotlin.serializers.RealmSetKSerializer
import io.realm.kotlin.types.RealmSet
import kotlinx.serialization.UseSerializers

그러면 파일 내에서 해당 유형의 속성이 있는 모든 객체가 직렬 변환기를 개별적으로 등록하지 않고도 사용할 수 있습니다.

// These objects have RealmSet properties that get serializers
// from declaring `@file:UseSerializers(RealmSetKSerializer::class)`.
// No need to individually declare them on every `RealmSet` property in the file.
class Movie : RealmObject {
var movieTitle: String = ""
var actors: RealmSet<String> = realmSetOf()
}
class TVSeries : RealmObject {
var seriesTitle: String = ""
var episodeTitles: RealmSet<String> = realmSetOf()
}

모든 Realm 유형을 자동으로 직렬 변환기에 바인딩하려면 모든 직렬 변환기가 포함된 스니펫을 파일 상단에 추가하면 됩니다.

@file:UseSerializers(
MutableRealmIntKSerializer::class,
RealmAnyKSerializer::class,
RealmDictionaryKSerializer::class,
RealmInstantKSerializer::class,
RealmListKSerializer::class,
RealmSetKSerializer::class,
RealmUUIDKSerializer::class
)

다음 예제는 JSON 인코더를 사용하여 다양한 Realm 데이터 유형을 직렬화하는 방법을 보여줍니다.

Realm 데이터 유형
직렬화 유형 및 예제

MutableRealmInt

Serializes using a regular integer value.

MutableRealmInt.create(35) serializes to 35

RealmAny

Serializes using a map containing a union of all values and its type.

RealmAny.create("hello world") serializes to {"type": "STRING", "string": "hello world"}

RealmAny.create(20) serializes to {"type": "INT", "int": 20}

RealmDictionary

Serializes using a generic list.

realmDictionaryOf("hello" to "world") serializes to {"hello": "world"}

RealmInstant

Serializes as a BsonDateTime.

RealmInstant.now() serializes to {"$date": {"$numberLong": "<millis>"}}

RealmList

Serializes using a generic list.

realmListOf("hello", world) serializes to ["hello", "world"]

RealmSet

Serializes using a generic list.

realmSetOf("hello", world) serializes to ["hello", "world"]

BsonObjectId 또는 ObjectId

Serializes as a BsonObjectId.

ObjectId.create() serializes to {"$oid": <ObjectId bytes as 24-character, big-endian hex string>}

RealmUUID

Serializes as a BsonBinary.

RealmUUID.random() serializes to { "$binary": {"base64": "<payload>", "subType": "<t>"}}

RealmObject

사용자가 정의한 다형성 설정을 사용하여 직렬화합니다. 직렬 변환기 모듈을 통해 이 작업을 수행하세요.

val json = Json {
serializersModule = SerializersModule {
polymorphic(RealmObject::class) {
subclass(SerializableSample::class)
}
}
}

버전 1.9.0의 새로운 기능

MongoDB Atlas와 직접 통신하는 Realm Kotlin SDK API는 EJSON 인코딩을 사용합니다. SDK는 두 가지 유형의 EJSON 인코더를 제공합니다.

  • 제한적이지만 안정적인 엔코더

  • 전체 문서 직렬화를 제공하는 실험적 인코더

이러한 인코더를 사용하는 API는 다음과 같습니다.

Realm 코틀린 (Kotlin) SDK (Kotlin SDK)의 EJSON 직렬화 지원 공식 코틀린 (Kotlin) 직렬화 라이브러리에 따라 달라집니다. 프로젝트 에 코틀린 (Kotlin) 직렬화 를 추가해야 합니다. Realm 코틀린 SDK (Kotlin SDK) 버전에 사용된 것과 동일한 버전을 사용하세요. 각 버전의 지원되는 종속성에 대한 자세한 내용은 realm-kotlin GitHub 리포지토리 의 버전 호환성 매트릭스를 참조하세요.

다음 예시의 @Serializable 어노테이션은 Kotlin 직렬화 프레임워크에서 가져왔습니다.

안정적인 인코더는 사용자 정의 클래스를 지원하지 않습니다. 안정적인 인코더에서 다음과 같은 인수 유형을 사용할 수 있습니다.

  • Primitives

  • BSON

  • MutableRealmInt

  • RealmUUID

  • ObjectId

  • RealmInstant

  • RealmAny

  • 배열

  • 컬렉션

  • Map

collection이나 지도를 반환하려면 BsonArray 또는 BsonDocument 을 사용할 수 있습니다.

유효한 인수 유형을 가진 안정적인 인코더를 사용하여 함수를 호출 하고 결과를 역직렬화할 수 있습니다.

이 예제에서는 두 개의 문자열 인수를 사용하여 getMailingAddress 함수를 호출하고 결과를 BsonDocument 로 얻습니다.

// The `getMailingAddress` function takes a first name and last name and returns an address as a BsonDocument
val address = user.functions.call<BsonDocument>("getMailingAddress", "Bob", "Smith")
assertEquals(address["street"], BsonString("123 Any Street"))

안정적인 인코더를 맵 또는 BsonDocument 으로 사용하여 사용자 지정 함수 인증 에 사용할 Credential 을(를) 만들 수 있습니다.

val credentials = Credentials.customFunction(
mapOf(
"userId" to 500,
"password" to "securePassword"
)
)
val bsonCredentials = Credentials.customFunction(
BsonDocument(
mapOf(
"userId" to BsonInt32(500),
"password" to BsonString("securePassword")
)
)
)
app.login(credentials)

안정적인 인코더를 BsonDocument 으)로 사용하여 사용자 프로필이나 사용자 지정 사용자 데이터 에 액세스할 수 있습니다.

val user = app.currentUser!!
val userProfile = user.profileAsBsonDocument()
assertEquals(userProfile["email"], BsonString("my.email@example.com"))
val user = app.currentUser!!
val customUserData = user.customDataAsBsonDocument()
assertEquals(BsonString("blue"), customUserData?.get("favoriteColor"))

전체 문서 인코더를 사용하면 사용자 정의 클래스를 직렬화 및 역직렬화할 수 있습니다. EJSON 인코딩을 사용하여 MongoDB Atlas와 직접 통신하는 Atlas 기능으로 해당 유형에 대한 사용자 지정 KSerializer를 정의하고 사용할 수 있습니다. 전체 문서 인코더는 상황에 맞는 직렬 변환기를 지원합니다.

중요

이는 실험적입니다.

전체 문서 직렬화의 현재 구현 실험적입니다. 프로젝트 에서 Realm의 종속성과 다른 버전의 코틀린 (Kotlin) 직렬화 사용할 때 이러한 API를 호출하면 정의되지 않은 동작이 발생합니다. 각 버전의 지원되는 종속성에 대한 자세한 내용은Realm-kotlin Github 리포지토리 의 버전 매트릭스 를 참조하세요.

이 기능을 사용하려면 다음 가져오기 중 하나 이상을 관련 파일에 추가합니다.

import kotlinx.serialization.Serializable
import io.realm.kotlin.annotations.ExperimentalRealmSerializerApi
import org.mongodb.kbson.ExperimentalKBsonSerializerApi
import kotlinx.serialization.modules.SerializersModule
import io.realm.kotlin.serializers.RealmListKSerializer

Realm 코틀린 SDK (Kotlin SDK)에서 직렬화를 사용할 때 다음 두 가지 방법 중 하나로 직렬 변환기를 정의할 수 있습니다.

  • 클래스에 @Serializable 주석 추가

  • 해당 유형에 대한 사용자 지정 KSerializer를 정의하고 관련 API에 전달합니다.

@Serializable
class Person(
val firstName: String,
val lastName: String
)

상황에 맞는 직렬 변환기를 사용하려는 경우와 같이 AppConfiguration 에서 앱에 대한 사용자 지정 EJSON 직렬 변환기를 설정할 수 있습니다.

@Serializable
class Frogger(
val name: String,
@Contextual
val date: LocalDateTime
)
AppConfiguration.Builder(FLEXIBLE_APP_ID)
.ejson(
EJson(
serializersModule = SerializersModule {
contextual(DateAsIntsSerializer)
}
)
)
.build()

전체 문서 직렬화 API는 실험적이므로 사용하는 API에 대해 관련 @OptIn 주석을 추가해야 합니다.

@OptIn(ExperimentalRealmSerializerApi::class)

사용자 지정 직렬 변환기를 사용하는 인수 또는 반환 유형과 함께 실험적 API를 사용하여 함수를 호출 할 수 있습니다.

이 예제에서는 직렬화된 Person 객체를 사용하여 getMailingAddressForPerson 함수를 호출하고 결과를 역직렬화된 Address 객체로 얻습니다.

@Serializable
class Address(
val street: String,
val city: String,
val state: String,
val country: String,
val postalCode: String
)
@Serializable
class Person(
val firstName: String,
val lastName: String
)
// The `getMailingAddressForPerson` function takes a Person object and returns an Address object using the experimental serializer
val address = user.functions.call<Address>("getMailingAddressForPerson"){
add(Person("Bob", "Smith"))
}
assertEquals(address.street, "123 Any Street")

안정적인 직렬 변환기와 실험적 API 직렬 변환기에 대한 Realm 함수 호출은 동일한 메서드 이름을 공유합니다. 매개변수 없이 함수를 호출하는 경우 실험적 API에 대한 지침에 빈 블록을 제공해야 합니다.

val color = user.functions.call<PersonalFavorites>("favouriteColor") {}

실험적 API를 사용하여 사용자 지정 함수 인증 을 위한 사용자 지정 직렬 변환기를 정의할 수 있습니다.

@Serializable
class CustomUserCredential(
val userId: Int,
val password: String
)

사용자 지정 함수 자격 증명을 만들 때 사용합니다.

val credentials = Credentials.customFunction(
CustomUserCredential(
userId = 500,
password = "securePassword"
)
)
app.login(credentials)

사용자 프로필 또는 사용자 지정 데이터에 대한 사용자 지정 직렬 변환기를 정의합니다.

@Serializable
class UserProfile(
val email: String
)
@Serializable
class UserCustomData(
val favoriteColor: String
)

사용자 프로필이나 사용자 지정 사용자 데이터에 액세스할 때는 사용자 지정 직렬 변환기를 사용하세요.

val user = app.currentUser!!
val userProfile = user.profile<UserProfile>()
assertEquals(userProfile.email, "my.email@example.com")
val user = app.currentUser!!
val customUserData = user.customData<UserCustomData>()
assertEquals("blue", customUserData!!.favoriteColor)

GSON 과 같이 리플렉션에 의존하는 라이브러리에서 사용하는 직렬화 메서드는 기본값 으로 SDK에서 작동하지 않습니다.

이는 SDK 컴파일러 플러그인이 접두사가 io_realm_kotlin_ 인 숨겨진 필드를 객체 모델에 삽입하기 때문입니다. SDK는 이 숨겨진 필드를 사용하여 내부 객체 상태를 managed합니다. 게터와 세터 대신 필드에 의존하는 모든 라이브러리는 이 숨겨진 필드를 무시해야 합니다.

GSON과 같은 외부 라이브러리와 함께 SDK를 사용하려면 접두사 일치를 사용하여 숨겨진 필드를 직렬화에서 제외하세요.

var gson: Gson = GsonBuilder()
.setExclusionStrategies(object: ExclusionStrategy {
override fun shouldSkipField(f: FieldAttributes?): Boolean =
f?.name?.startsWith("io_realm_kotlin_") ?: false
override fun shouldSkipClass(clazz: Class<*>?): Boolean =
false
})
.create()

돌아가기

변경 사항에 대한 반응