0
# Advanced Configuration
1

2
Akka Serialization Jackson provides comprehensive configuration options for fine-tuning serialization behavior, performance, security, and compatibility. The configuration system supports both global settings and binding-specific overrides.
3

4
## Configuration Structure
5

6
### Base Configuration Path
7

8
All configuration is under the `akka.serialization.jackson` section:
9

10
```hocon
11
akka.serialization.jackson {
12
  # Global configuration options
13
  verbose-debug-logging = off
14
  type-in-manifest = on
15
  
16
  # Binding-specific configuration
17
  my-binding {
18
    # Override global settings for this binding
19
  }
20
}
21
```
22

23
### Binding-Specific Configuration
24

25
```hocon { .api }
26
# Configuration hierarchy:
27
# 1. akka.serialization.jackson.<binding-name> (most specific)
28
# 2. akka.serialization.jackson (fallback)
29

30
akka.serialization.jackson {
31
  # Global defaults
32
  compression.algorithm = off
33
  
34
  jackson-json {
35
    # JSON-specific settings
36
    compression.algorithm = gzip
37
    compression.compress-larger-than = 32 KiB
38
  }
39
  
40
  jackson-cbor {
41
    # CBOR-specific settings  
42
    compression.algorithm = lz4
43
    compression.compress-larger-than = 1 KiB
44
  }
45
}
46
```
47

48
## Jackson Feature Configuration
49

50
### Serialization Features
51

52
Control Jackson's SerializationFeature settings:
53

54
```hocon
55
akka.serialization.jackson {
56
  serialization-features {
57
    # Date/time format
58
    WRITE_DATES_AS_TIMESTAMPS = off          # Use ISO-8601 format
59
    WRITE_DURATIONS_AS_TIMESTAMPS = off      # Use ISO-8601 duration format
60
    
61
    # Object handling
62
    FAIL_ON_EMPTY_BEANS = off                # Allow empty objects
63
    INDENT_OUTPUT = off                      # Compact JSON output
64
    
65
    # Number formatting
66
    WRITE_BIGDECIMAL_AS_PLAIN = off          # Scientific notation allowed
67
    WRITE_CHAR_ARRAYS_AS_JSON_ARRAYS = off   # String representation for char[]
68
    
69
    # Collection handling
70
    WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED = off # Always use array format
71
  }
72
}
73
```
74

75
### Deserialization Features
76

77
Control Jackson's DeserializationFeature settings:
78

79
```hocon
80
akka.serialization.jackson {
81
  deserialization-features {
82
    # Property handling
83
    FAIL_ON_UNKNOWN_PROPERTIES = off         # Ignore unknown JSON properties
84
    FAIL_ON_NULL_FOR_PRIMITIVES = off        # Allow null for primitives
85
    FAIL_ON_NUMBERS_FOR_ENUMS = off          # Allow numeric enum values
86
    
87
    # Collection handling
88
    ACCEPT_EMPTY_STRING_AS_NULL_OBJECT = off # Treat "" as null
89
    ACCEPT_SINGLE_VALUE_AS_ARRAY = off       # Single values as one-element arrays
90
    
91
    # Type handling
92
    FAIL_ON_INVALID_SUBTYPE = on             # Strict subtype validation
93
    UNWRAP_SINGLE_VALUE_ARRAYS = off         # Keep array format
94
  }
95
}
96
```
97

98
### Mapper Features
99

100
Control Jackson's MapperFeature settings:
101

102
```hocon
103
akka.serialization.jackson {
104
  mapper-features {
105
    # Property ordering
106
    SORT_PROPERTIES_ALPHABETICALLY = off     # Preserve declaration order
107
    
108
    # Duplicate handling
109
    ALLOW_FINAL_FIELDS_AS_MUTATORS = off     # Respect final field immutability
110
    
111
    # Visibility
112
    AUTO_DETECT_CREATORS = on                # Auto-detect constructors
113
    AUTO_DETECT_FIELDS = on                  # Auto-detect field access
114
    AUTO_DETECT_GETTERS = on                 # Auto-detect getter methods
115
    
116
    # Type handling
117
    USE_ANNOTATIONS = on                     # Process Jackson annotations
118
    USE_GETTERS_AS_SETTERS = on             # Use getters for collection mutation
119
  }
120
}
121
```
122

123
### JSON Parser Features
124

125
Control Jackson's JsonParser.Feature settings:
126

127
```hocon
128
akka.serialization.jackson {
129
  json-parser-features {
130
    # Comment support
131
    ALLOW_COMMENTS = off                     # Disallow // and /* */ comments
132
    
133
    # Quote handling
134
    ALLOW_SINGLE_QUOTES = off                # Require double quotes
135
    ALLOW_UNQUOTED_FIELD_NAMES = off         # Require quoted field names
136
    
137
    # Value handling
138
    ALLOW_NUMERIC_LEADING_ZEROS = off        # Strict numeric format
139
    ALLOW_NON_NUMERIC_NUMBERS = off          # Disallow NaN, Infinity
140
    
141
    # Control characters
142
    ALLOW_UNESCAPED_CONTROL_CHARS = off      # Require escaped control chars
143
  }
144
}
145
```
146

147
### JSON Generator Features
148

149
Control Jackson's JsonGenerator.Feature settings:
150

151
```hocon
152
akka.serialization.jackson {
153
  json-generator-features {
154
    # Quote handling
155
    QUOTE_FIELD_NAMES = on                   # Always quote field names
156
    QUOTE_NON_NUMERIC_NUMBERS = on           # Quote NaN, Infinity
157
    
158
    # Number formatting
159
    WRITE_NUMBERS_AS_STRINGS = off           # Use numeric representation
160
    
161
    # Character handling
162
    ESCAPE_NON_ASCII = off                   # Allow UTF-8 characters
163
  }
164
}
165
```
166

167
### Stream Features
168

169
Control JsonFactory stream features:
170

171
```hocon
172
akka.serialization.jackson {
173
  # Stream read features
174
  stream-read-features {
175
    STRICT_DUPLICATE_DETECTION = off         # Allow duplicate keys
176
    USE_FAST_DOUBLE_PARSER = on             # Optimized double parsing
177
  }
178
  
179
  # Stream write features  
180
  stream-write-features {
181
    WRITE_BIGDECIMAL_AS_PLAIN = off          # Use scientific notation
182
    USE_FAST_DOUBLE_WRITER = on             # Optimized double writing
183
  }
184
  
185
  # JSON-specific read features
186
  json-read-features {
187
    ALLOW_JAVA_COMMENTS = off                # Disallow Java-style comments
188
    ALLOW_YAML_COMMENTS = off                # Disallow YAML-style comments
189
    ALLOW_SINGLE_QUOTES = off                # Require double quotes
190
    ALLOW_UNQUOTED_FIELD_NAMES = off         # Require quoted field names
191
    ALLOW_TRAILING_COMMA = off               # Disallow trailing commas
192
  }
193
  
194
  # JSON-specific write features
195
  json-write-features {
196
    QUOTE_FIELD_NAMES = on                   # Always quote field names
197
    WRITE_NAN_AS_STRINGS = on               # Write NaN as "NaN"
198
    ESCAPE_NON_ASCII = off                   # Allow UTF-8 output
199
  }
200
}
201
```
202

203
## Visibility Configuration
204

205
Control property visibility for serialization:
206

207
```hocon
208
akka.serialization.jackson {
209
  visibility {
210
    # Field visibility (default: ANY - all fields including private)
211
    FIELD = ANY                              # PUBLIC_ONLY, PROTECTED_AND_PUBLIC, etc.
212
    
213
    # Other accessors default to Jackson's default behavior (not explicitly set)
214
    # GETTER = default                       # Getter method visibility
215
    # SETTER = default                       # Setter method visibility  
216
    # CREATOR = default                      # Constructor visibility
217
    # IS_GETTER = default                    # Is-getter method visibility
218
  }
219
}
220
```
221

222
## Compression Configuration
223

224
### Compression Algorithms
225

226
```hocon
227
akka.serialization.jackson {
228
  compression {
229
    # Available algorithms: off, gzip, lz4
230
    algorithm = off
231
    
232
    # Compress only if payload is larger than this size
233
    compress-larger-than = 0 KiB
234
  }
235
  
236
  # Binding-specific compression  
237
  jackson-json {
238
    compression {
239
      algorithm = gzip                       # Default for JSON (good for text)
240
      compress-larger-than = 32 KiB         # Default threshold for JSON
241
    }
242
  }
243
  
244
  jackson-cbor {
245
    compression {
246
      algorithm = off                        # Default is off for CBOR
247
      compress-larger-than = 0 KiB          # Default threshold
248
    }
249
  }
250
}
251
```
252

253
### Compression Performance
254

255
```scala
256
// Compression effectiveness by algorithm:
257
// gzip: High compression ratio, moderate CPU usage
258
// lz4: Lower compression ratio, very fast CPU usage
259
// off: No compression, minimal CPU usage
260

261
// Size thresholds:
262
// < 1 KiB: Usually not worth compressing
263
// 1-32 KiB: LZ4 often optimal
264
// > 32 KiB: GZIP may provide better ratios
265
```
266

267
## Security Configuration
268

269
### Class Filtering
270

271
```hocon
272
akka.serialization.jackson {
273
  # Additional allowed class prefixes (beyond serialization-bindings)
274
  allowed-class-prefix = [
275
    "com.example.safe",                      # Allow com.example.safe.* classes
276
    "org.mycompany.dto"                      # Allow org.mycompany.dto.* classes
277
  ]
278
  
279
  # Deprecated - use allowed-class-prefix instead
280
  whitelist-class-prefix = []
281
}
282
```
283

284
### Type Manifest Configuration
285

286
```hocon
287
akka.serialization.jackson {
288
  # Include type information in serialization manifest
289
  type-in-manifest = on                      # Default: include type info
290
  
291
  # Override deserialization type (when type-in-manifest = off)
292
  deserialization-type = ""                  # Empty = auto-detect from bindings
293
  
294
  # Example: Force all data to deserialize as specific type
295
  # deserialization-type = "com.example.BaseMessage"
296
}
297
```
298

299
## Module Configuration
300

301
### Jackson Modules
302

303
```hocon
304
akka.serialization.jackson {
305
  jackson-modules = [
306
    # Core Akka modules
307
    "akka.serialization.jackson.AkkaJacksonModule",
308
    "akka.serialization.jackson.AkkaTypedJacksonModule",      # If akka-actor-typed available
309
    "akka.serialization.jackson.AkkaStreamJacksonModule",     # If akka-streams available
310
    
311
    # Standard Jackson modules
312
    "com.fasterxml.jackson.module.paramnames.ParameterNamesModule",
313
    "com.fasterxml.jackson.datatype.jdk8.Jdk8Module",
314
    "com.fasterxml.jackson.datatype.jsr310.JavaTimeModule",
315
    "com.fasterxml.jackson.module.scala.DefaultScalaModule",
316
    
317
    # Custom modules
318
    "com.example.MyCustomJacksonModule"
319
  ]
320
}
321
```
322

323
### Conditional Module Loading
324

325
Modules are automatically filtered based on classpath availability:
326

327
```scala
328
// Automatic filtering:
329
// - AkkaTypedJacksonModule: Only if akka.actor.typed.ActorRef is available
330
// - AkkaStreamJacksonModule: Only if akka.stream.Graph is available
331
// - Other modules: Always loaded if class is found
332
```
333

334
## Migration Configuration
335

336
### Migration Class Mapping
337

338
```hocon
339
akka.serialization.jackson {
340
  migrations {
341
    # Map class names to migration implementations
342
    "com.example.User" = "com.example.migrations.UserMigration"
343
    "com.example.Order" = "com.example.migrations.OrderMigration"
344
    
345
    # Support old class names
346
    "com.example.legacy.OldUser" = "com.example.migrations.UserMigration"
347
  }
348
}
349
```
350

351
## Debug and Monitoring
352

353
### Debug Logging
354

355
```hocon
356
akka.serialization.jackson {
357
  # Enable detailed serialization logging (requires akka.loglevel = DEBUG)
358
  verbose-debug-logging = on
359
}
360

361
# Also set Akka log level
362
akka.loglevel = DEBUG
363
```
364

365
**Debug output includes:**
366
- Serialization/deserialization time in microseconds
367
- Payload sizes (compressed and uncompressed)
368
- Class names being serialized
369
- Migration version information
370

371
### Performance Monitoring
372

373
```scala
374
// Enable JMX monitoring for ObjectMapper metrics
375
import com.fasterxml.jackson.databind.ObjectMapper
376

377
// Custom ObjectMapper factory with metrics
378
class MonitoredObjectMapperFactory extends JacksonObjectMapperFactory {
379
  override def newObjectMapper(bindingName: String, jsonFactory: JsonFactory): ObjectMapper = {
380
    val mapper = super.newObjectMapper(bindingName, jsonFactory)
381
    // Add metrics collection
382
    registerMetrics(bindingName, mapper)
383
    mapper
384
  }
385
}
386
```
387

388
## Configuration Examples
389

390
### High-Performance Configuration
391

392
```hocon
393
akka.serialization.jackson {
394
  # Optimize for speed
395
  verbose-debug-logging = off
396
  
397
  serialization-features {
398
    INDENT_OUTPUT = off                      # Compact output
399
    WRITE_DATES_AS_TIMESTAMPS = on          # Faster than ISO format
400
  }
401
  
402
  mapper-features {
403
    SORT_PROPERTIES_ALPHABETICALLY = off     # Preserve order = faster
404
  }
405
  
406
  compression {
407
    algorithm = lz4                          # Fastest compression
408
    compress-larger-than = 1 KiB
409
  }
410
}
411
```
412

413
### Strict Compatibility Configuration
414

415
```hocon
416
akka.serialization.jackson {
417
  # Optimize for compatibility
418
  serialization-features {
419
    WRITE_DATES_AS_TIMESTAMPS = off          # ISO-8601 format
420
    FAIL_ON_EMPTY_BEANS = on                # Strict validation
421
  }
422
  
423
  deserialization-features {
424
    FAIL_ON_UNKNOWN_PROPERTIES = on         # Strict property validation
425
    FAIL_ON_INVALID_SUBTYPE = on           # Strict type validation
426
  }
427
  
428
  json-parser-features {
429
    ALLOW_COMMENTS = off                     # Strict JSON format
430
    ALLOW_SINGLE_QUOTES = off               # Standard JSON only
431
  }
432
}
433
```
434

435
### Development Configuration
436

437
```hocon
438
akka.serialization.jackson {
439
  # Optimize for debugging
440
  verbose-debug-logging = on
441
  
442
  serialization-features {
443
    INDENT_OUTPUT = on                       # Pretty-print JSON
444
  }
445
  
446
  deserialization-features {
447
    FAIL_ON_UNKNOWN_PROPERTIES = off        # Lenient parsing
448
  }
449
  
450
  compression {
451
    algorithm = off                          # No compression for debugging
452
  }
453
}
454
```
455

456
## Best Practices
457

458
### Configuration Management
459

460
1. **Use binding-specific settings** - Different serializers may need different configurations
461
2. **Test configuration changes** - Feature changes can break compatibility
462
3. **Document custom settings** - Explain why non-default values are used
463
4. **Version configurations** - Track configuration changes with code versions
464

465
### Security Considerations
466

467
1. **Restrict allowed classes** - Only allow known safe classes for deserialization
468
2. **Disable dangerous features** - Turn off features that might enable attacks
469
3. **Monitor deserialization** - Log and alert on unexpected class types
470
4. **Regular security updates** - Keep Jackson versions current
471

472
### Performance Tuning
473

474
1. **Profile before optimizing** - Measure actual performance impact
475
2. **Test compression effectiveness** - Different data may benefit from different algorithms
476
3. **Monitor memory usage** - Some features increase memory overhead
477
4. **Benchmark realistic payloads** - Use production-like data for testing