0
# Jackson Module Kotlin
1

2
Jackson Module Kotlin adds comprehensive support for serialization and deserialization of Kotlin classes and data classes without requiring default constructors. It enables automatic JSON property name inference from Kotlin constructor parameters using runtime type information, and supports single constructor classes, secondary constructors, and static factories.
3

4
## Package Information
5

6
- **Package Name**: jackson-module-kotlin
7
- **Package Type**: maven
8
- **Language**: Kotlin/Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>com.fasterxml.jackson.module</groupId>
13
      <artifactId>jackson-module-kotlin</artifactId>
14
      <version>2.19.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```kotlin
21
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
22
import com.fasterxml.jackson.module.kotlin.readValue
23
```
24

25
Alternative imports:
26

27
```kotlin
28
import com.fasterxml.jackson.module.kotlin.registerKotlinModule
29
import com.fasterxml.jackson.module.kotlin.jsonMapper
30
import com.fasterxml.jackson.module.kotlin.kotlinModule
31
```
32

33
## Basic Usage
34

35
```kotlin
36
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
37
import com.fasterxml.jackson.module.kotlin.readValue
38

39
data class User(val name: String, val age: Int)
40

41
// Create mapper with Kotlin support
42
val mapper = jacksonObjectMapper()
43

44
// Serialize to JSON
45
val user = User("Alice", 30)
46
val json = mapper.writeValueAsString(user)
47

48
// Deserialize from JSON with type inference
49
val deserializedUser = mapper.readValue<User>(json)
50
// or
51
val deserializedUser: User = mapper.readValue(json)
52
```
53

54
## Architecture
55

56
Jackson Module Kotlin integrates with the Jackson ecosystem through several key components:
57

58
- **KotlinModule**: Main module class that registers Kotlin support with Jackson
59
- **KotlinFeature**: Configuration enum for customizing module behavior
60
- **Extension Functions**: Type-safe, reified extension functions for ObjectMapper operations
61
- **Introspectors**: Kotlin-specific annotation and naming introspectors
62
- **Deserializers/Serializers**: Built-in support for Kotlin-specific types
63
- **Reflection Cache**: Optimized caching for Kotlin reflection operations
64

65
## Capabilities
66

67
### Module Configuration
68

69
Core module setup and configuration with extensive customization options through feature flags and builder patterns.
70

71
```kotlin { .api }
72
class KotlinModule private constructor(
73
    val reflectionCacheSize: Int = 512,
74
    val nullToEmptyCollection: Boolean = false,
75
    val nullToEmptyMap: Boolean = false,
76
    val nullIsSameAsDefault: Boolean = false,
77
    val singletonSupport: Boolean = false,
78
    val strictNullChecks: Boolean = false,
79
    val kotlinPropertyNameAsImplicitName: Boolean = false,
80
    val useJavaDurationConversion: Boolean = false
81
) : SimpleModule
82

83
enum class KotlinFeature {
84
    NullToEmptyCollection,
85
    NullToEmptyMap,
86
    NullIsSameAsDefault,
87
    SingletonSupport,
88
    StrictNullChecks,
89
    NewStrictNullChecks,
90
    KotlinPropertyNameAsImplicitName,
91
    UseJavaDurationConversion
92
}
93
```
94

95
[Module Configuration](./module-configuration.md)
96

97
### Factory Functions
98

99
Convenient factory functions for creating Jackson ObjectMappers and JsonMappers with Kotlin support enabled by default.
100

101
```kotlin { .api }
102
fun jacksonObjectMapper(): ObjectMapper
103
fun jacksonObjectMapper(initializer: KotlinModule.Builder.() -> Unit): ObjectMapper
104
fun jsonMapper(initializer: JsonMapper.Builder.() -> Unit = {}): JsonMapper
105
fun kotlinModule(initializer: KotlinModule.Builder.() -> Unit = {}): KotlinModule
106
```
107

108
[Factory Functions](./factory-functions.md)
109

110
### Type-Safe Extensions
111

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

114
```kotlin { .api }
115
inline fun <reified T> ObjectMapper.readValue(content: String): T
116
inline fun <reified T> ObjectMapper.readValue(src: File): T
117
inline fun <reified T> ObjectMapper.readValue(src: InputStream): T
118
inline fun <reified T> ObjectMapper.convertValue(from: Any?): T
119
inline fun <reified T> jacksonTypeRef(): TypeReference<T>
120
```
121

122
[Type-Safe Extensions](./type-safe-extensions.md)
123

124
### JSON Node Operations
125

126
Kotlin-style operator overloading for intuitive manipulation of Jackson's JSON tree model, enabling natural array and object operations.
127

128
```kotlin { .api }
129
operator fun ArrayNode.plus(element: String): Unit
130
operator fun ArrayNode.plusAssign(element: JsonNode): Unit
131
operator fun ObjectNode.minus(field: String): Unit
132
operator fun JsonNode.contains(field: String): Boolean
133
```
134

135
[JSON Node Operations](./json-node-operations.md)
136

137
### Built-in Type Support
138

139
Comprehensive serialization and deserialization support for Kotlin-specific types including unsigned numbers, sequences, and value classes.
140

141
```kotlin { .api }
142
object UByteSerializer : StdSerializer<UByte>
143
object SequenceDeserializer : StdDeserializer<Sequence<*>>
144
object RegexDeserializer : StdDeserializer<Regex>
145
object ValueClassUnboxSerializer : StdSerializer<Any>
146
```
147

148
[Built-in Type Support](./builtin-types.md)
149

150
## Types
151

152
### Core Types
153

154
```kotlin { .api }
155
class KotlinModule.Builder {
156
    fun withReflectionCacheSize(size: Int): Builder
157
    fun enable(feature: KotlinFeature): Builder
158
    fun disable(feature: KotlinFeature): Builder
159
    fun configure(feature: KotlinFeature, enabled: Boolean): Builder
160
    fun isEnabled(feature: KotlinFeature): Boolean
161
    fun build(): KotlinModule
162
}
163

164
class MissingKotlinParameterException(
165
    val parameter: KParameter,
166
    processor: JsonParser? = null,
167
    msg: String
168
) : InvalidNullException
169
```