or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

akka-types.mdconfiguration.mdindex.mdmigration.mdobject-mapper.md
tile.json

tessl/maven-com-typesafe-akka--akka-serialization-jackson

Jackson-based JSON and CBOR serialization capabilities for the Akka toolkit, enabling efficient serialization and deserialization of Akka messages and persistent events.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.typesafe.akka/akka-serialization-jackson_2.13@2.8.x

To install, run

npx @tessl/cli install tessl/maven-com-typesafe-akka--akka-serialization-jackson@2.8.0

index.mddocs/

Akka Serialization Jackson

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.

Package Information

Maven Coordinates:

<dependency>
  <groupId>com.typesafe.akka</groupId>
  <artifactId>akka-serialization-jackson_2.13</artifactId>
  <version>2.8.8</version>
</dependency>

SBT:

libraryDependencies += "com.typesafe.akka" %% "akka-serialization-jackson" % "2.8.8"

Core Imports

import akka.serialization.jackson.JacksonObjectMapperProvider
import akka.serialization.jackson.JacksonObjectMapperProviderSetup
import akka.serialization.jackson.JacksonObjectMapperFactory  
import akka.serialization.jackson.JacksonMigration
import akka.serialization.jackson.AkkaJacksonModule

Basic Usage

Configuration-Based Serialization

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

akka.actor.serialization-bindings {
  "com.example.MyMessage" = jackson-json
  "com.example.MyEvent" = jackson-cbor
}

Programmatic ObjectMapper Access

import akka.actor.ActorSystem
import akka.serialization.jackson.JacksonObjectMapperProvider
import com.fasterxml.jackson.dataformat.cbor.CBORFactory

val system = ActorSystem("MySystem")
val provider = JacksonObjectMapperProvider(system)

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

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

Custom ObjectMapper Setup

import akka.actor.ActorSystem
import akka.actor.setup.ActorSystemSetup
import akka.serialization.jackson.{JacksonObjectMapperProviderSetup, JacksonObjectMapperFactory}

// Create custom factory
class MyObjectMapperFactory extends JacksonObjectMapperFactory {
  // Override methods to customize ObjectMapper creation
}

val customFactory = new MyObjectMapperFactory()
val setup = JacksonObjectMapperProviderSetup(customFactory)
val actorSystemSetup = ActorSystemSetup(setup)
val system = ActorSystem("MySystem", actorSystemSetup)

Architecture

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

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

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

Serializer Classes

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

// Automatically configured serializers (internal API, configured via akka.actor.serializers)
class JacksonJsonSerializer(system: ExtendedActorSystem, bindingName: String) extends JacksonSerializer
class JacksonCborSerializer(system: ExtendedActorSystem, bindingName: String) extends JacksonSerializer

// Base serializer class  
abstract class JacksonSerializer(system: ExtendedActorSystem, bindingName: String, objectMapper: ObjectMapper) 
  extends SerializerWithStringManifest {
  def toBinary(obj: AnyRef): Array[Byte]
  def fromBinary(bytes: Array[Byte], manifest: String): AnyRef
  def manifest(obj: AnyRef): String
}

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

Core Capabilities

ObjectMapper Management

Centralized creation and configuration of Jackson ObjectMapper instances with support for multiple bindings and custom factories.

final class JacksonObjectMapperProvider(system: ExtendedActorSystem) extends Extension {
  // Scala API
  def getOrCreate(bindingName: String, jsonFactory: Option[JsonFactory]): ObjectMapper
  def create(bindingName: String, jsonFactory: Option[JsonFactory]): ObjectMapper
  
  // Java API
  def getOrCreate(bindingName: String, jsonFactory: Optional[JsonFactory]): ObjectMapper
  def create(bindingName: String, jsonFactory: Optional[JsonFactory]): ObjectMapper
}

object JacksonObjectMapperProvider extends ExtensionId[JacksonObjectMapperProvider] {
  def get(system: ActorSystem): JacksonObjectMapperProvider
  def get(system: ClassicActorSystemProvider): JacksonObjectMapperProvider
  def configForBinding(bindingName: String, systemConfig: Config): Config
}

ObjectMapper Management

Data Migration

Schema evolution support for handling changes to serialized data structures over time.

abstract class JacksonMigration {
  def currentVersion: Int
  def supportedForwardVersion: Int  
  def transform(fromVersion: Int, json: JsonNode): JsonNode
  def transformClassName(fromVersion: Int, className: String): String
}

Data Migration

Akka Type Serialization

Built-in serialization support for Akka-specific types including ActorRef, typed ActorRef, Address, FiniteDuration, and StreamRef.

class AkkaJacksonModule extends JacksonModule 
  with ActorRefModule with AddressModule with FiniteDurationModule

class AkkaTypedJacksonModule extends JacksonModule with TypedActorRefModule
class AkkaStreamJacksonModule extends JacksonModule with StreamRefModule

Akka Type Serialization

Advanced Configuration

Comprehensive configuration options for Jackson features, compression, security, and serialization behavior.

class JacksonObjectMapperFactory {
  def newObjectMapper(bindingName: String, jsonFactory: JsonFactory): ObjectMapper
  def overrideConfiguredModules(bindingName: String, modules: immutable.Seq[Module]): immutable.Seq[Module]
  def overrideConfiguredSerializationFeatures(bindingName: String, features: immutable.Seq[(SerializationFeature, Boolean)]): immutable.Seq[(SerializationFeature, Boolean)]
  def overrideConfiguredDeserializationFeatures(bindingName: String, features: immutable.Seq[(DeserializationFeature, Boolean)]): immutable.Seq[(DeserializationFeature, Boolean)]
  def overrideConfiguredMapperFeatures(bindingName: String, features: immutable.Seq[(MapperFeature, Boolean)]): immutable.Seq[(MapperFeature, Boolean)]
  // ... other feature override methods
}

final class JacksonObjectMapperProviderSetup(val factory: JacksonObjectMapperFactory) extends Setup

object JacksonObjectMapperProviderSetup {
  def apply(factory: JacksonObjectMapperFactory): JacksonObjectMapperProviderSetup
  def create(factory: JacksonObjectMapperFactory): JacksonObjectMapperProviderSetup // Java API
}

Advanced Configuration

Key Features

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

Common Use Cases

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