직렬화 - 코틀린 SDK (Kotlin SDK)
이 페이지의 내용
Realm 코틀린 SDK (Kotlin SDK)는 코틀린 (Kotlin) 직렬화를 지원합니다. 안정적인 직렬 변환기를 사용하여 특정 Realm 데이터 유형을 직렬화하거나 실험적인 전체 문서 직렬화 API를 사용하여 사용자 정의 클래스를 직렬화할 수 있습니다.
Realm 데이터 유형 직렬 변환기
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 = "" var favoritePonds: RealmList<String> = realmListOf() }
파일의 모든 어커런스에 대한 직렬 변환기 등록
파일 상단에 선언을 추가하여 파일 내에서 해당 유형이 모든 항목에 대해 직렬 변환기를 등록할 수 있습니다.
class) (RealmSetKSerializer::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 유형을 직렬 변환기에 자동으로 바인딩
모든 Realm 유형을 자동으로 직렬 변환기에 바인딩하려면 모든 직렬 변환기가 포함된 스니펫을 파일 상단에 추가하면 됩니다.
( 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 | 사용자가 정의한 다형성 설정을 사용하여 직렬화합니다. 직렬 변환기 모듈을 통해 이 작업을 수행하세요.
|
Atlas용 EJSON 인코딩
버전 1.9.0의 새로운 기능
MongoDB Atlas와 직접 통신하는 Realm Kotlin SDK API는 EJSON 인코딩을 사용합니다. SDK는 두 가지 유형의 EJSON 인코더를 제공합니다.
제한적이지만 안정적인 엔코더
전체 문서 직렬화를 제공하는 실험적 인코더
이러한 인코더를 사용하는 API는 다음과 같습니다.
App Services 함수 호출
사용자 지정 함수 인증이 포함된 자격 증명
사용자 프로필 및 사용자 지정 사용자 데이터
프로젝트에 KSerialization 추가
Realm 코틀린 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에 전달합니다.
class Person( val firstName: String, val lastName: String )
상황에 맞는 직렬 변환기를 사용하려는 경우와 같이 AppConfiguration
에서 앱에 대한 사용자 지정 EJSON 직렬 변환기를 설정할 수 있습니다.
class Frogger( val name: String, val date: LocalDateTime ) AppConfiguration.Builder(FLEXIBLE_APP_ID) .ejson( EJson( serializersModule = SerializersModule { contextual(DateAsIntsSerializer) } ) ) .build()
실험적 옵트인
전체 문서 직렬화 API는 실험적이므로 사용하는 API에 대해 관련 @OptIn
주석을 추가해야 합니다.
함수 호출
사용자 지정 직렬 변환기를 사용하는 인수 또는 반환 유형과 함께 실험적 API를 사용하여 함수를 호출 할 수 있습니다.
이 예제에서는 직렬화된 Person
객체를 사용하여 getMailingAddressForPerson
함수를 호출하고 결과를 역직렬화된 Address
객체로 얻습니다.
class Address( val street: String, val city: String, val state: String, val country: String, val postalCode: String ) 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를 사용하여 사용자 지정 함수 인증 을 위한 사용자 지정 직렬 변환기를 정의할 수 있습니다.
class CustomUserCredential( val userId: Int, val password: String )
사용자 지정 함수 자격 증명을 만들 때 사용합니다.
val credentials = Credentials.customFunction( CustomUserCredential( userId = 500, password = "securePassword" ) ) app.login(credentials)
사용자 프로필 및 사용자 지정 데이터
사용자 프로필 또는 사용자 지정 데이터에 대한 사용자 지정 직렬 변환기를 정의합니다.
class UserProfile( val email: String )
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()