0
# Kotlin Parcelize Runtime
1

2
The Kotlin Parcelize Runtime provides essential annotations and utilities for the Kotlin Parcelize compiler plugin. It enables automatic generation of Android Parcelable implementations through annotations, eliminating boilerplate code while maintaining type safety and performance for Android development.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlin:kotlin-parcelize-runtime
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  - Gradle: `implementation("org.jetbrains.kotlin:kotlin-parcelize-runtime:2.2.0")`
11
  - Maven:
12
    ```xml
13
    <dependency>
14
        <groupId>org.jetbrains.kotlin</groupId>
15
        <artifactId>kotlin-parcelize-runtime</artifactId>
16
        <version>2.2.0</version>
17
    </dependency>
18
    ```
19

20
## Core Imports
21

22
```kotlin
23
import kotlinx.parcelize.Parcelize
24
import kotlinx.parcelize.IgnoredOnParcel
25
import kotlinx.parcelize.RawValue
26
import kotlinx.parcelize.WriteWith
27
import kotlinx.parcelize.TypeParceler
28
import kotlinx.parcelize.Parceler
29
import kotlinx.parcelize.parcelableCreator
30
import kotlinx.parcelize.DataClass
31
import android.os.Parcel // Required for custom Parceler implementations
32
```
33

34
## Basic Usage
35

36
```kotlin
37
import android.os.Parcelable
38
import kotlinx.parcelize.Parcelize
39
import kotlinx.parcelize.IgnoredOnParcel
40

41
@Parcelize
42
data class User(
43
    val id: String,
44
    val name: String,
45
    val email: String,
46
    @IgnoredOnParcel val password: String = ""
47
) : Parcelable
48

49
// Usage
50
val user = User("123", "John Doe", "john@example.com")
51
// writeToParcel(), describeContents(), and CREATOR are automatically generated
52
```
53

54
## Capabilities
55

56
### Basic Parcelize Annotation
57

58
The core annotation that instructs the Kotlin compiler to generate Parcelable implementation automatically.
59

60
```kotlin { .api }
61
@Target(AnnotationTarget.CLASS)
62
@Retention(AnnotationRetention.BINARY)
63
annotation class Parcelize
64
```
65

66
Used on classes that implement `android.os.Parcelable` to automatically generate:
67
- `writeToParcel()` method
68
- `describeContents()` method  
69
- `CREATOR` factory class
70

71
Only primary constructor properties are serialized.
72

73
### Property Exclusion
74

75
Exclude specific properties from parcel serialization.
76

77
```kotlin { .api }
78
@Target(AnnotationTarget.PROPERTY)
79
@Retention(AnnotationRetention.SOURCE)
80
annotation class IgnoredOnParcel
81
```
82

83
Properties annotated with `@IgnoredOnParcel` will not be stored in the parcel during serialization.
84

85
### Raw Value Serialization
86

87
Handle complex types using raw value serialization.
88

89
```kotlin { .api }
90
@Target(AnnotationTarget.TYPE)
91
@Retention(AnnotationRetention.BINARY)
92
annotation class RawValue
93
```
94

95
Writes property values using `android.os.Parcel.writeValue()`. Serialization may fail at runtime depending on the actual property value type.
96

97
Usage example:
98
```kotlin
99
@Parcelize
100
data class ComplexData(
101
    val regularField: String,
102
    val complexField: @RawValue Any
103
) : Parcelable
104
```
105

106
### Custom Parceler Integration
107

108
Specify custom parcelers for type-specific serialization.
109

110
```kotlin { .api }
111
@Retention(AnnotationRetention.SOURCE)
112
@Target(AnnotationTarget.TYPE)
113
annotation class WriteWith<P : Parceler<*>>
114
```
115

116
```kotlin { .api }
117
@Retention(AnnotationRetention.SOURCE)
118
@Repeatable
119
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
120
annotation class TypeParceler<T, P : Parceler<in T>>
121
```
122

123
- `@WriteWith`: Specifies parceler for the annotated type
124
- `@TypeParceler`: Specifies parceler for a particular type T, can be repeated
125

126
### Custom Parceler Interface
127

128
Implement custom serialization logic for complex types.
129

130
```kotlin { .api }
131
interface Parceler<T> {
132
    /**
133
     * Writes the [T] instance state to the [parcel].
134
     */
135
    fun T.write(parcel: Parcel, flags: Int)
136

137
    /**
138
     * Reads the [T] instance state from the [parcel], constructs the new [T] instance and returns it.
139
     */
140
    fun create(parcel: Parcel): T
141

142
    /**
143
     * Returns a new [Array]<T> with the given array [size].
144
     */
145
    fun newArray(size: Int): Array<T>
146
}
147
```
148

149
Usage example:
150
```kotlin
151
object DateParceler : Parceler<Date> {
152
    override fun Date.write(parcel: Parcel, flags: Int) {
153
        parcel.writeLong(time)
154
    }
155

156
    override fun create(parcel: Parcel): Date {
157
        return Date(parcel.readLong())
158
    }
159

160
    override fun newArray(size: Int): Array<Date> {
161
        throw NotImplementedError("Generated by Android Extensions automatically")
162
    }
163
}
164

165
@Parcelize
166
@TypeParceler<Date, DateParceler>
167
data class Event(
168
    val name: String,
169
    val date: Date
170
) : Parcelable
171
```
172

173
### Parcelable Creator Access
174

175
Programmatically access the CREATOR field of Parcelable classes.
176

177
```kotlin { .api }
178
inline fun <reified T : Parcelable> parcelableCreator(): Parcelable.Creator<T>
179
```
180

181
Reads the CREATOR field of the given Parcelable class with direct field access optimization.
182

183
**Throws**: `IllegalArgumentException` with message "Could not access CREATOR field in class {ClassName}" if CREATOR field cannot be accessed.
184

185
Usage example:
186
```kotlin
187
val creator = parcelableCreator<User>()
188
val userFromParcel = creator.createFromParcel(parcel)
189
```
190

191
### Experimental Data Class Serialization
192

193
Enable serialization of non-Parcelable data classes (experimental feature).
194

195
```kotlin { .api }
196
@Target(AnnotationTarget.TYPE)
197
@Retention(AnnotationRetention.SOURCE)
198
@Experimental
199
annotation class DataClass
200
```
201

202
```kotlin { .api }
203
@RequiresOptIn("This feature is experimental and requires explicit opt-in")
204
annotation class Experimental
205
```
206

207
When a type is annotated with `@DataClass`, data classes contained inside it will be serialized even if they are not Parcelable. The serialization format is equivalent to what would be generated if the data class was annotated with `@Parcelize`.
208

209
Usage example:
210
```kotlin
211
data class NonParcelableData(val value: String)
212

213
@Parcelize
214
data class Container(
215
    val data: @DataClass NonParcelableData
216
) : Parcelable
217
```
218

219
### Internal Compiler Utilities
220

221
```kotlin { .api }
222
object DirectInitializerMarker
223
```
224

225
Internal marker object used by the compiler for optimization purposes. Not intended for direct use in application code.
226

227
## Error Handling
228

229
- **IllegalArgumentException**: Thrown by `parcelableCreator()` when CREATOR field cannot be accessed
230
- **NotImplementedError**: Thrown by default `Parceler.newArray()` implementation
231
- **Runtime serialization failures**: May occur with `@RawValue` depending on actual property value types
232

233
## Dependencies
234

235
- **kotlin-stdlib**: Core Kotlin standard library
236
- **com.google.android:android**: Android framework (compile-only dependency)