0
# Type-Safe Extensions
1

2
Reified extension functions that eliminate the need for explicit type references and provide compile-time type safety for all ObjectMapper operations.
3

4
## Capabilities
5

6
### Type Reference Creation
7

8
Create TypeReference instances using reified generics for type-safe Jackson operations.
9

10
```kotlin { .api }
11
/**
12
 * Create a TypeReference for reified type T
13
 * @return TypeReference<T> for use with Jackson operations
14
 */
15
inline fun <reified T> jacksonTypeRef(): TypeReference<T>
16
```
17

18
**Usage Examples:**
19

20
```kotlin
21
import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
22

23
// Create type references for complex types
24
val listTypeRef = jacksonTypeRef<List<String>>()
25
val mapTypeRef = jacksonTypeRef<Map<String, User>>()
26

27
// Use with ObjectMapper directly
28
val users: List<User> = mapper.readValue(json, jacksonTypeRef<List<User>>())
29
```
30

31
### ObjectMapper ReadValue Extensions
32

33
Type-safe readValue operations with automatic type inference from various input sources.
34

35
```kotlin { .api }
36
/**
37
 * Read value from JsonParser with type inference
38
 * @param jp JsonParser to read from
39
 * @return Deserialized object of type T
40
 * @throws RuntimeJsonMappingException if T is non-null and value is null
41
 */
42
inline fun <reified T> ObjectMapper.readValue(jp: JsonParser): T
43

44
/**
45
 * Read value from File with type inference
46
 * @param src File to read from
47
 * @return Deserialized object of type T
48
 */
49
inline fun <reified T> ObjectMapper.readValue(src: File): T
50

51
/**
52
 * Read value from URL with type inference
53
 * @param src URL to read from
54
 * @return Deserialized object of type T
55
 */
56
inline fun <reified T> ObjectMapper.readValue(src: URL): T
57

58
/**
59
 * Read value from String with type inference
60
 * @param content JSON string to parse
61
 * @return Deserialized object of type T
62
 */
63
inline fun <reified T> ObjectMapper.readValue(content: String): T
64

65
/**
66
 * Read value from Reader with type inference
67
 * @param src Reader to read from
68
 * @return Deserialized object of type T
69
 */
70
inline fun <reified T> ObjectMapper.readValue(src: Reader): T
71

72
/**
73
 * Read value from InputStream with type inference
74
 * @param src InputStream to read from
75
 * @return Deserialized object of type T
76
 */
77
inline fun <reified T> ObjectMapper.readValue(src: InputStream): T
78

79
/**
80
 * Read value from ByteArray with type inference
81
 * @param src ByteArray to parse
82
 * @return Deserialized object of type T
83
 */
84
inline fun <reified T> ObjectMapper.readValue(src: ByteArray): T
85
```
86

87
**Usage Examples:**
88

89
```kotlin
90
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
91
import com.fasterxml.jackson.module.kotlin.readValue
92
import java.io.File
93

94
data class User(val name: String, val age: Int)
95

96
val mapper = jacksonObjectMapper()
97

98
// Read from different sources with type inference
99
val user1 = mapper.readValue<User>("""{"name":"Alice","age":30}""")
100
val user2: User = mapper.readValue("""{"name":"Bob","age":25}""")
101
val user3 = mapper.readValue<User>(File("user.json"))
102
val user4 = mapper.readValue<User>(userInputStream)
103

104
// Complex types
105
val users = mapper.readValue<List<User>>(usersJson)
106
val userMap = mapper.readValue<Map<String, User>>(userMapJson)
107
```
108

109
### Multiple Values Reading
110

111
Type-safe readValues operation for reading multiple objects from a single input.
112

113
```kotlin { .api }
114
/**
115
 * Read multiple values from JsonParser with type inference
116
 * @param jp JsonParser to read from
117
 * @return MappingIterator<T> for iterating over values
118
 * @throws RuntimeJsonMappingException if T is non-null and any value is null
119
 */
120
inline fun <reified T> ObjectMapper.readValues(jp: JsonParser): MappingIterator<T>
121
```
122

123
**Usage Examples:**
124

125
```kotlin
126
import com.fasterxml.jackson.module.kotlin.readValues
127

128
// Read multiple JSON objects from a stream
129
val parser = mapper.factory.createParser(jsonStream)
130
val userIterator = mapper.readValues<User>(parser)
131

132
for (user in userIterator) {
133
    println("User: ${user.name}, Age: ${user.age}")
134
}
135
```
136

137
### Tree and Conversion Operations
138

139
Type-safe tree-to-value and object conversion operations.
140

141
```kotlin { .api }
142
/**
143
 * Convert TreeNode to typed value
144
 * @param n TreeNode to convert
145
 * @return Converted object of type T
146
 */
147
inline fun <reified T> ObjectMapper.treeToValue(n: TreeNode): T
148

149
/**
150
 * Convert any object to typed value
151
 * @param from Source object to convert
152
 * @return Converted object of type T
153
 */
154
inline fun <reified T> ObjectMapper.convertValue(from: Any?): T
155
```
156

157
**Usage Examples:**
158

159
```kotlin
160
import com.fasterxml.jackson.module.kotlin.convertValue
161
import com.fasterxml.jackson.module.kotlin.treeToValue
162

163
// Convert between different object types
164
val userMap = mapOf("name" to "Charlie", "age" to 35)
165
val user = mapper.convertValue<User>(userMap)
166

167
// Convert JSON tree to typed object
168
val jsonNode = mapper.readTree(json)
169
val user2 = mapper.treeToValue<User>(jsonNode)
170

171
// Convert with complex types
172
val userList = mapper.convertValue<List<User>>(listOfMaps)
173
```
174

175
### Configuration Extensions
176

177
Type-safe configuration methods using reified generics.
178

179
```kotlin { .api }
180
/**
181
 * Get configuration override for reified type
182
 * @return MutableConfigOverride for type T
183
 */
184
inline fun <reified T : Any> ObjectMapper.configOverride(): MutableConfigOverride
185

186
/**
187
 * Add mix-in annotation for reified types
188
 * @return ObjectMapper for method chaining
189
 */
190
inline fun <reified T, reified U> ObjectMapper.addMixIn(): ObjectMapper
191
```
192

193
**Usage Examples:**
194

195
```kotlin
196
import com.fasterxml.jackson.module.kotlin.addMixIn
197
import com.fasterxml.jackson.module.kotlin.configOverride
198

199
// Configure specific type behavior
200
mapper.configOverride<User>()
201
    .setInclude(JsonInclude.Value.construct(JsonInclude.Include.NON_NULL, null))
202

203
// Add mix-in annotations
204
mapper.addMixIn<User, UserMixin>()
205

206
interface UserMixin {
207
    @get:JsonProperty("full_name")
208
    val name: String
209
}
210
```
211

212
## ObjectReader Extensions
213

214
Type-safe extensions for ObjectReader operations.
215

216
### ObjectReader ReadValue Extensions
217

218
```kotlin { .api }
219
/**
220
 * Type-safe ObjectReader.readValue
221
 * @param jp JsonParser to read from
222
 * @return Deserialized object of type T
223
 */
224
inline fun <reified T> ObjectReader.readValueTyped(jp: JsonParser): T
225

226
/**
227
 * Type-safe ObjectReader.readValues
228
 * @param jp JsonParser to read from
229
 * @return Iterator<T> for reading multiple values
230
 */
231
inline fun <reified T> ObjectReader.readValuesTyped(jp: JsonParser): Iterator<T>
232

233
/**
234
 * Convert TreeNode to typed value using ObjectReader
235
 * @param n TreeNode to convert
236
 * @return Converted object of type T or null
237
 */
238
inline fun <reified T> ObjectReader.treeToValue(n: TreeNode): T?
239
```
240

241
**Usage Examples:**
242

243
```kotlin
244
import com.fasterxml.jackson.module.kotlin.readValueTyped
245
import com.fasterxml.jackson.module.kotlin.readValuesTyped
246

247
// Create reader for specific type
248
val userReader = mapper.readerFor(User::class.java)
249

250
// Use type-safe reader operations
251
val parser = mapper.factory.createParser(json)
252
val user = userReader.readValueTyped<User>(parser)
253

254
// Read multiple values
255
val usersIterator = userReader.readValuesTyped<User>(parser)
256
```
257

258
## JsonMapper Builder Extensions
259

260
Type-safe extensions for JsonMapper.Builder configuration.
261

262
```kotlin { .api }
263
/**
264
 * Add mix-in annotation for JsonMapper builder
265
 * @return JsonMapper.Builder for method chaining
266
 */
267
inline fun <reified T, reified U> JsonMapper.Builder.addMixIn(): JsonMapper.Builder
268
```
269

270
**Usage Examples:**
271

272
```kotlin
273
import com.fasterxml.jackson.module.kotlin.addMixIn
274
import com.fasterxml.jackson.module.kotlin.jsonMapper
275
import com.fasterxml.jackson.module.kotlin.kotlinModule
276

277
val mapper = jsonMapper {
278
    addModule(kotlinModule())
279
    addMixIn<User, UserMixin>()
280
}
281
```
282

283
## Module Setup Context Extensions
284

285
Type-safe configuration within module setup contexts.
286

287
```kotlin { .api }
288
/**
289
 * Get configuration override in setup context
290
 * @return MutableConfigOverride for type T
291
 */
292
inline fun <reified T : Any> Module.SetupContext.configOverride(): MutableConfigOverride
293
```
294

295
**Usage Examples:**
296

297
```kotlin
298
import com.fasterxml.jackson.module.kotlin.configOverride
299

300
class CustomModule : SimpleModule() {
301
    override fun setupModule(context: SetupContext) {
302
        super.setupModule(context)
303
        
304
        // Configure specific types during module setup
305
        context.configOverride<User>()
306
            .setInclude(JsonInclude.Value.construct(JsonInclude.Include.NON_EMPTY, null))
307
    }
308
}
309
```