Docs Menu
Docs Home
/ /
Atlas Device SDK
/ /

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

이 페이지의 내용

  • Realm 데이터 유형 직렬 변환기
  • 속성에 대한 직렬 변환기 등록
  • 파일의 모든 어커런스에 대한 직렬 변환기 등록
  • Realm 유형을 직렬 변환기에 자동으로 바인딩
  • 직렬화 출력 예제
  • Atlas용 EJSON 인코딩
  • 프로젝트에 KSerialization 추가
  • 스테이블 인코더
  • 함수 호출
  • 사용자 지정 함수 자격 증명
  • 사용자 프로필 및 사용자 지정 데이터
  • 전체 문서 인코더
  • 필수 가져오기
  • 직렬 변환기 정의
  • 실험적 옵트인
  • 함수 호출
  • 사용자 지정 함수 자격 증명
  • 사용자 프로필 및 사용자 지정 데이터
  • 기타 직렬화 라이브러리

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 코틀린 SDK (Kotlin SDK)의 EJSON 직렬화 지원은 공식 코틀린 (Kotlin) 직렬화 라이브러리에 따라 달라집니다.Kotlin 직렬화 를 추가해야 합니다. 프로젝트에 추가합니다. Realm 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()

돌아가기

변경 사항에 대한 반응