0
# Akka Serialization Jackson
1

2
Akka Serialization Jackson provides comprehensive Jackson-based JSON and CBOR serialization capabilities for the Akka toolkit. This library enables efficient serialization and deserialization of Akka messages, persistent events, and distributed data with built-in support for Akka-specific types, data migration, compression, and security features.
3

4
## Package Information
5

6
**Maven Coordinates:**
7
```xml
8
<dependency>
9
  <groupId>com.typesafe.akka</groupId>
10
  <artifactId>akka-serialization-jackson_2.13</artifactId>
11
  <version>2.8.8</version>
12
</dependency>
13
```
14

15
**SBT:**
16
```scala
17
libraryDependencies += "com.typesafe.akka" %% "akka-serialization-jackson" % "2.8.8"
18
```
19

20
## Core Imports
21

22
```scala { .api }
23
import akka.serialization.jackson.JacksonObjectMapperProvider
24
import akka.serialization.jackson.JacksonObjectMapperProviderSetup
25
import akka.serialization.jackson.JacksonObjectMapperFactory  
26
import akka.serialization.jackson.JacksonMigration
27
import akka.serialization.jackson.AkkaJacksonModule
28
```
29

30
## Basic Usage
31

32
### Configuration-Based Serialization
33

34
The most common usage is through Akka's serialization configuration:
35

36
```hocon
37
akka.actor.serialization-bindings {
38
  "com.example.MyMessage" = jackson-json
39
  "com.example.MyEvent" = jackson-cbor
40
}
41
```
42

43
### Programmatic ObjectMapper Access
44

45
```scala { .api }
46
import akka.actor.ActorSystem
47
import akka.serialization.jackson.JacksonObjectMapperProvider
48
import com.fasterxml.jackson.dataformat.cbor.CBORFactory
49

50
val system = ActorSystem("MySystem")
51
val provider = JacksonObjectMapperProvider(system)
52

53
// Get ObjectMapper for JSON
54
val jsonMapper = provider.getOrCreate("jackson-json", None)
55

56
// Get ObjectMapper for CBOR  
57
val cborMapper = provider.getOrCreate("jackson-cbor", Some(new CBORFactory()))
58
```
59

60
### Custom ObjectMapper Setup
61

62
```scala { .api }
63
import akka.actor.ActorSystem
64
import akka.actor.setup.ActorSystemSetup
65
import akka.serialization.jackson.{JacksonObjectMapperProviderSetup, JacksonObjectMapperFactory}
66

67
// Create custom factory
68
class MyObjectMapperFactory extends JacksonObjectMapperFactory {
69
  // Override methods to customize ObjectMapper creation
70
}
71

72
val customFactory = new MyObjectMapperFactory()
73
val setup = JacksonObjectMapperProviderSetup(customFactory)
74
val actorSystemSetup = ActorSystemSetup(setup)
75
val system = ActorSystem("MySystem", actorSystemSetup)
76
```
77

78
## Architecture
79

80
Akka Serialization Jackson follows a modular architecture designed for high-performance distributed systems:
81

82
- **Serializers**: `JacksonJsonSerializer` and `JacksonCborSerializer` handle the actual serialization work
83
- **ObjectMapper Provider**: Centralized registry for configured ObjectMapper instances with caching
84
- **Jackson Modules**: Specialized modules for Akka types (ActorRef, Address, FiniteDuration, etc.)
85
- **Migration System**: Schema evolution support through configurable transformation classes
86
- **Compression Layer**: Built-in gzip and LZ4 compression for large payloads
87
- **Security Layer**: Comprehensive class filtering and deserialization attack prevention
88

89
The library integrates seamlessly with Akka's serialization extension and can be configured per-binding for fine-grained control over serialization behavior.
90

91
### Serializer Classes
92

93
The following serializer classes are configured in Akka's actor system:
94

95
```scala { .api }
96
// Automatically configured serializers (internal API, configured via akka.actor.serializers)
97
class JacksonJsonSerializer(system: ExtendedActorSystem, bindingName: String) extends JacksonSerializer
98
class JacksonCborSerializer(system: ExtendedActorSystem, bindingName: String) extends JacksonSerializer
99

100
// Base serializer class  
101
abstract class JacksonSerializer(system: ExtendedActorSystem, bindingName: String, objectMapper: ObjectMapper) 
102
  extends SerializerWithStringManifest {
103
  def toBinary(obj: AnyRef): Array[Byte]
104
  def fromBinary(bytes: Array[Byte], manifest: String): AnyRef
105
  def manifest(obj: AnyRef): String
106
}
107
```
108

109
**Note**: These serializers are typically not instantiated directly but configured through Akka's serialization bindings.
110

111
## Core Capabilities
112

113
### ObjectMapper Management
114
Centralized creation and configuration of Jackson ObjectMapper instances with support for multiple bindings and custom factories.
115

116
```scala { .api }
117
final class JacksonObjectMapperProvider(system: ExtendedActorSystem) extends Extension {
118
  // Scala API
119
  def getOrCreate(bindingName: String, jsonFactory: Option[JsonFactory]): ObjectMapper
120
  def create(bindingName: String, jsonFactory: Option[JsonFactory]): ObjectMapper
121
  
122
  // Java API
123
  def getOrCreate(bindingName: String, jsonFactory: Optional[JsonFactory]): ObjectMapper
124
  def create(bindingName: String, jsonFactory: Optional[JsonFactory]): ObjectMapper
125
}
126

127
object JacksonObjectMapperProvider extends ExtensionId[JacksonObjectMapperProvider] {
128
  def get(system: ActorSystem): JacksonObjectMapperProvider
129
  def get(system: ClassicActorSystemProvider): JacksonObjectMapperProvider
130
  def configForBinding(bindingName: String, systemConfig: Config): Config
131
}
132
```
133

134
[ObjectMapper Management](./object-mapper.md)
135

136
### Data Migration
137
Schema evolution support for handling changes to serialized data structures over time.
138

139
```scala { .api }
140
abstract class JacksonMigration {
141
  def currentVersion: Int
142
  def supportedForwardVersion: Int  
143
  def transform(fromVersion: Int, json: JsonNode): JsonNode
144
  def transformClassName(fromVersion: Int, className: String): String
145
}
146
```
147

148
[Data Migration](./migration.md)
149

150
### Akka Type Serialization
151
Built-in serialization support for Akka-specific types including ActorRef, typed ActorRef, Address, FiniteDuration, and StreamRef.
152

153
```scala { .api }
154
class AkkaJacksonModule extends JacksonModule 
155
  with ActorRefModule with AddressModule with FiniteDurationModule
156

157
class AkkaTypedJacksonModule extends JacksonModule with TypedActorRefModule
158
class AkkaStreamJacksonModule extends JacksonModule with StreamRefModule  
159
```
160

161
[Akka Type Serialization](./akka-types.md)
162

163
### Advanced Configuration
164
Comprehensive configuration options for Jackson features, compression, security, and serialization behavior.
165

166
```scala { .api }
167
class JacksonObjectMapperFactory {
168
  def newObjectMapper(bindingName: String, jsonFactory: JsonFactory): ObjectMapper
169
  def overrideConfiguredModules(bindingName: String, modules: immutable.Seq[Module]): immutable.Seq[Module]
170
  def overrideConfiguredSerializationFeatures(bindingName: String, features: immutable.Seq[(SerializationFeature, Boolean)]): immutable.Seq[(SerializationFeature, Boolean)]
171
  def overrideConfiguredDeserializationFeatures(bindingName: String, features: immutable.Seq[(DeserializationFeature, Boolean)]): immutable.Seq[(DeserializationFeature, Boolean)]
172
  def overrideConfiguredMapperFeatures(bindingName: String, features: immutable.Seq[(MapperFeature, Boolean)]): immutable.Seq[(MapperFeature, Boolean)]
173
  // ... other feature override methods
174
}
175

176
final class JacksonObjectMapperProviderSetup(val factory: JacksonObjectMapperFactory) extends Setup
177

178
object JacksonObjectMapperProviderSetup {
179
  def apply(factory: JacksonObjectMapperFactory): JacksonObjectMapperProviderSetup
180
  def create(factory: JacksonObjectMapperFactory): JacksonObjectMapperProviderSetup // Java API
181
}
182
```
183

184
[Advanced Configuration](./configuration.md)
185

186
## Key Features
187

188
- **Multiple Formats**: JSON and CBOR serialization support
189
- **Akka Integration**: Native handling of ActorRef, Address, FiniteDuration, and StreamRef types
190
- **High Performance**: Optimized for distributed Akka applications with optional compression
191
- **Schema Evolution**: Data migration support for backwards and forwards compatibility  
192
- **Security**: Built-in protection against deserialization attacks with configurable class filtering
193
- **Flexibility**: Extensive configuration options and customization through ObjectMapper factories
194
- **Type Safety**: Comprehensive type definitions and manifest-based deserialization
195
- **Compression**: Built-in gzip and LZ4 compression for large payloads
196

197
## Common Use Cases
198

199
- **Message Serialization**: Serializing messages passed between actors in distributed systems
200
- **Event Persistence**: Storing and retrieving events in event-sourced applications
201
- **Cluster Communication**: Efficient serialization for Akka Cluster messaging
202
- **Data Migration**: Evolving schemas in production systems with zero downtime
203
- **Performance Optimization**: Using CBOR for binary efficiency or compression for large payloads