Serialization (Scala)

Module stability: SOLID

Serialization of ActorRef

An Actor can be serialized in two different ways:

  • Serializable RemoteActorRef - Serialized to an immutable, network-aware Actor reference that can be freely shared across the network. They "remember" and stay mapped to their original Actor instance and host node, and will always work as expected.
  • Serializable LocalActorRef - Serialized by doing a deep copy of both the ActorRef and the Actor instance itself. Can be used to physically move an Actor from one node to another and continue the execution there.

Both of these can be sent as messages over the network and/or store them to disk, in a persistent storage backend etc.

Actor serialization in Akka is implemented through a type class 'Format[T <: Actor]' which publishes the 'fromBinary' and 'toBinary' methods for serialization. Here's the complete definition of the type class:

 * Type class definition for Actor Serialization
trait FromBinary[T <: Actor] {
  def fromBinary(bytes: Array[Byte], act: T): T
trait ToBinary[T <: Actor] {
  def toBinary(t: T): Array[Byte]
// client needs to implement Format[] for the respective actor
trait Format[T <: Actor] extends FromBinary[T] with ToBinary[T]

Deep serialization of an Actor and ActorRef

You can serialize the whole actor deeply, e.g. both the 'ActorRef' and then instance of its 'Actor'. This can be useful if you want to move an actor from one node to another, or if you want to store away an actor, with its state, into a database.

Here is an example of how to serialize an Actor.

Step 1: Define the actor

class MyActor extends Actor {
  var count = 0
  def receive = {
    case "hello" =>
      count = count + 1
      self.reply("world " + count)

Step 2: Implement the type class for the actor

object BinaryFormatMyActor {
  implicit object MyActorFormat extends Format[MyActor] {
    def fromBinary(bytes: Array[Byte], act: MyActor) = {
      val p = Serializer.Protobuf.fromBinary(bytes, Some(classOf[ProtobufProtocol.Counter])).asInstanceOf[ProtobufProtocol.Counter]
      act.count = p.getCount
    def toBinary(ac: MyActor) =

Step 3: Import the type class module definition and serialize / de-serialize

it("should be able to serialize and de-serialize a stateful actor") {
  import BinaryFormatMyActor._
  val actor1 = actorOf[MyActor].start
  (actor1 !! "hello").getOrElse("_") should equal("world 1")
  (actor1 !! "hello").getOrElse("_") should equal("world 2")
  val bytes = toBinary(actor1)
  val actor2 = fromBinary(bytes)
  (actor2 !! "hello").getOrElse("_") should equal("world 3")

Helper Type Class for Stateless Actors

If your actor is stateless, then you can use the helper trait that Akka provides to serialize / de-serialize. Here's the definition:

trait StatelessActorFormat[T <: Actor] extends Format[T] {
  def fromBinary(bytes: Array[Byte], act: T) = act
  def toBinary(ac: T) = Array.empty[Byte]
Then you use it as follows:

class MyStatelessActor extends Actor {
  def receive = {
    case "hello" =>

Just create an object for the helper trait for your actor:

object BinaryFormatMyStatelessActor {
  implicit object MyStatelessActorFormat extends StatelessActorFormat[MyStatelessActor]

and use it for serialization:

it("should be able to serialize and de-serialize a stateless actor") {
  import BinaryFormatMyStatelessActor._
  val actor1 = actorOf[MyStatelessActor].start
  (actor1 !! "hello").getOrElse("_") should equal("world")
  (actor1 !! "hello").getOrElse("_") should equal("world")
  val bytes = toBinary(actor1)
  val actor2 = fromBinary(bytes)
  (actor2 !! "hello").getOrElse("_") should equal("world")

Helper Type Class for actors with external serializer

Use the trait 'SerializerBasedActorFormat' for specifying serializers.

trait SerializerBasedActorFormat[T <: Actor] extends Format[T] {
  val serializer: Serializer
  def fromBinary(bytes: Array[Byte], act: T) = serializer.fromBinary(bytes, Some(act.self.actorClass)).asInstanceOf[T]
  def toBinary(ac: T) = serializer.toBinary(ac)

For a Java serializable actor:

@serializable class MyJavaSerializableActor extends Actor {
  var count = 0
  def receive = {
    case "hello" =>
      count = count + 1
      self.reply("world " + count)

Create a module for the type class ..

object BinaryFormatMyJavaSerializableActor {
  implicit object MyJavaSerializableActorFormat extends SerializerBasedActorFormat[MyJavaSerializableActor] {
    val serializer = Serializer.Java
and serialize / de-serialize ..

it("should be able to serialize and de-serialize a stateful actor with a given serializer") {
  import BinaryFormatMyJavaSerializableActor._
  val actor1 = actorOf[MyJavaSerializableActor].start
  (actor1 !! "hello").getOrElse("_") should equal("world 1")
  (actor1 !! "hello").getOrElse("_") should equal("world 2")
  val bytes = toBinary(actor1)
  val actor2 = fromBinary(bytes)
  (actor2 !! "hello").getOrElse("_") should equal("world 3")

Serialization of a RemoteActorRef

You can serialize an 'ActorRef' to an immutable, network-aware Actor reference that can be freely shared across the network, a reference that "remembers" and stay mapped to its original Actor instance and host node, and will always work as expected.

The 'RemoteActorRef' serialization is based upon Protobuf (Google Protocol Buffers) and you don't need to do anything to use it, it works on any 'ActorRef' (as long as the actor has not implemented one of the 'SerializableActor' traits, since then deep serialization will happen).

Currently Akka will not autodetect an 'ActorRef' as part of your message and serialize it for you automatically, so you have to do that manually or as part of your custom serialization mechanisms.

Here is an example of how to serialize an Actor.

val actor1 = actorOf[MyActor]
val bytes = toBinary(actor1)

To deserialize the 'ActorRef' to a 'RemoteActorRef' you need to use the 'fromBinaryToRemoteActorRef(bytes: Array[Byte])' method on the 'ActorRef' companion object:

import RemoteActorSerialization._
val actor2 = fromBinaryToRemoteActorRef(bytes)

You can also pass in a class loader to load the 'ActorRef' class and dependencies from:
import RemoteActorSerialization._
val actor2 = fromBinaryToRemoteActorRef(bytes, classLoader)


Akka has a helper class for doing compression of binary data. This can be useful for example when storing data in one of the backing storages. It currently supports LZF which is a very fast compression algorithm suited for runtime dynamic compression.

Here is an example of how it can be used:
import se.scalablesolutions.akka.serialization.Compression
val bytes: Array[Byte] = ...
val compressBytes = Compression.LZF.compress(bytes)
val uncompressBytes = Compression.LZF.uncompress(compressBytes)

Using the Serializable trait and Serializer class for custom serialization

If you are sending messages to a remote Actor/Active Object and these messages implement one of the predefined interfaces/traits in the 'se.scalablesolutions.akka.serialization.Serializable.*' object, then Akka will transparently detect which serialization format it should use as wire protocol and will automatically serialize and deserialize the message according to this protocol.

Each serialization interface/trait in
  • se.scalablesolutions.akka.serialization.Serializable.*
    has a matching serializer in
  • se.scalablesolutions.akka.serialization.Serializer.*

Note however that if you are using one of the Serializable interfaces then you don’t have to do anything else in regard to sending remote messages.

The ones currently supported are (besides the default which is regular Java serialization):
  • ScalaJON (Scala only)
  • JavaJSON (Java but some Scala structures)
  • SBinary (Scala only)
  • Protobuf (Scala and Java)

Apart from the above, Akka also supports Scala object serialization through SJSON that implements APIs similar to 'se.scalablesolutions.akka.serialization.Serializer.*'. See the section on SJSON below for details.


Akka supports using Google Protocol Buffers to serialize your objects. Protobuf is a very efficient network serialization protocol which is also used internally by Akka. The remote actors understand Protobuf messages so if you just send them as they are they will be correctly serialized and unserialized.

Here is an example.

Let's say you have this Protobuf message specification that you want to use as message between remote actors. First you need to compiled it with 'protoc' compiler.

message ProtobufPOJO {
  required uint64 id = 1;
  required string name = 2;
  required bool status = 3;

When you compile the spec you will among other things get a message builder. You then use this builder to create the messages to send over the wire:

val result = remoteActor !! ProtobufPOJO.newBuilder

The remote Actor can then receive the Protobuf message typed as-is:

class MyRemoteActor extends Actor {
  def receive = {
    case pojo: ProtobufPOJO =>
     val id = pojo.getId
     val status = pojo.getStatus
     val name = pojo.getName

JSON: Scala

Use the se.scalablesolutions.akka.serialization.Serialization.ScalaJSON base class with its toJSON method. Akka’s Scala JSON is based upon the SJSON library.

For your POJOs to be able to serialize themselves you have to extend the ScalaJSON trait.
import se.scalablesolutions.akka.serialization.Serializer
import se.scalablesolutions.akka.serialization.Serializable.ScalaJSON
import scala.reflect.BeanInfo
@BeanInfo case class MyMessage(val id: String, val value: Tuple2[String, Int]) extends ScalaJSON
val message = MyMessage("id", ("hello", 34))
val json = message.toJSON
val messageCopy =

Use se.scalablesolutions.akka.serialization.Serializer.ScalaJSON to do generic JSON serialization, e.g. serialize object that does not extend ScalaJSON using the JSON serializer.
import se.scalablesolutions.akka.serialization.Serializer
import scala.reflect.BeanInfo
@BeanInfo case class Foo(name: String) {
  def this() = this(null)  // default constructor is necessary for deserialization
val foo = new Foo("bar")
val json = Serializer.ScalaJSON.out(foo)
val fooCopy = // returns a JsObject as an AnyRef
val fooCopy2 = String(json)) // can also take a string as input
val fooCopy3 =[Foo](json).asInstanceOf[Foo]

Classes without a @BeanInfo annotation cannot be serialized as JSON.
So if you see something like that:
scala> Serializer.ScalaJSON.out(bar)
java.lang.UnsupportedOperationException: Class class Bar not supported for conversion
        at sjson.json.JsBean$class.toJSON(JsBean.scala:210)
        at sjson.json.Serializer$SJSON$.toJSON(Serializer.scala:107)
        at sjson.json.Serializer$SJSON$class.out(Serializer.scala:37)
        at sjson.json.Serializer$SJSON$.out(Serializer.scala:107)
        at se.scalablesolutions.akka.serialization.Serializer$ScalaJSON...
it means, that you haven't got a @BeanInfo annotation on your class.

You may also see this exception when trying to serialize a case class with out an attribute like this:
@BeanInfo case class Empty() // cannot be serialized

SJSON: Scala

SJSON supports serialization of Scala objects into JSON. It implements support for built in Scala structures like List, Map or String as well as custom objects. SJSON is available as an Apache 2 licensed project on Github here.

Example: I have a Scala object as ..
val addr = Address("Market Street", "San Francisco", "956871")

where Address is a custom class defined by the user. Using SJSON, I can store it as JSON and retrieve as plain old Scala object. Here’s the simple assertion that validates the invariant. Note that during de-serialziation, the class name is specified. Hence what it gives back is an instance of Address.
addr should equal([Address](serializer.out(addr)))
Note, that the class needs to have a default constructor. Otherwise the deserialization into the specified class will fail.

There are situations, particularly when writing generic persistence libraries in Akka, when the exact class is not known during de-serialization. Using SJSON I can get it as AnyRef or Nothing ..[AnyRef](serializer.out(addr))

or just as ..

What you get back from is a JsValue, an abstraction of the JSON object model. For details of JsValueimplementation, refer to dispatch-json that SJSON uses as the underlying JSON parser implementation. Once I have the JsValue model, I can use use extractors to get back individual attributes ..
val a =[AnyRef](serializer.out(addr))
// use extractors
val c = 'city ? str
val c(_city) = a
_city should equal("San Francisco")
val s = 'street ? str
val s(_street) = a
_street should equal("Market Street")
val z = 'zip ? str
val z(_zip) = a
_zip should equal("956871")

Serialization of Embedded Objects

SJSON supports serialization of Scala objects that have other embedded objects. Suppose you have the following Scala classes .. Here Contact has an embedded Address Map ..
case class Contact(name: String,
                   @(JSONTypeHint @field)(value = classOf[Address])
                   addresses: Map[String, Address]) {
  override def toString = "name = " + name + " addresses = " + => a._1 + ":" + a._2.toString).mkString(",")
case class Address(street: String, city: String, zip: String) {
  override def toString = "address = " + street + "/" + city + "/" + zip
With SJSON, I can do the following:

val a1 = Address("Market Street", "San Francisco", "956871")
val a2 = Address("Monroe Street", "Denver", "80231")
val a3 = Address("North Street", "Atlanta", "987671")
val c = Contact("Bob", Map("residence" -> a1, "office" -> a2, "club" -> a3))
val co = serializer.out(c)
// with class specified
c should equal([Contact](co))
// no class specified
val a =[AnyRef](co)
// extract name
val n = 'name ? str
val n(_name) = a
"Bob" should equal(_name)
// extract addresses
val addrs = 'addresses ? obj
val addrs(_addresses) = a
// extract residence from addresses
val res = 'residence ? obj
val res(_raddr) = _addresses
// make an Address bean out of _raddr
val address = JsBean.fromJSON(_raddr, Some(classOf[Address]))
a1 should equal(address)
object r { def ># [T](f: JsF[T]) = f(a.asInstanceOf[JsValue]) }
// still better: chain 'em up
"Market Street" should equal(
  (r ># { ('addresses ? obj) andThen ('residence ? obj) andThen ('street ? str) }))

Changing property names during serialization

case class Book(id: Number,
           title: String, @(JSONProperty @getter)(value = "ISBN") isbn: String) {
  override def toString = "id = " + id + " title = " + title + " isbn = " + isbn

When this will be serialized out, the property name will be changed.
val b = new Book(100, "A Beautiful Mind", "012-456372")
val jsBook = Js(JsBean.toJSON(b))
val expected_book_map = Map(
  JsString("id") -> JsNumber(100),
  JsString("title") -> JsString("A Beautiful Mind"),
  JsString("ISBN") -> JsString("012-456372")

Serialization with ignore properties

When serializing objects, some of the properties can be ignored declaratively. Consider the following class declaration:
case class Journal(id: BigDecimal,
                    title: String,
                    author: String,
                    @(JSONProperty @getter)(ignore = true) issn: String) {
override def toString =
    "Journal: " + id + "/" + title + "/" + author +
      (issn match {
          case null => ""
          case _ => "/" + issn

The annotation @JSONProperty can be used to selectively ignore fields. When I serialize a Journal object out and then back in, the content of issn field will be null.
it("should ignore issn field") {
    val j = Journal(100, "IEEE Computer", "Alex Payne", "012-456372")[Journal](serializer.out(j)).asInstanceOf[Journal].issn should equal(null)

Similarly, we can ignore properties of an object only if they are null and not ignore otherwise. Just specify the annotation @JSONProperty as @JSONProperty {val ignoreIfNull = true}.

Serialization with Type Hints for Generic Data Members

Consider the following Scala class:
case class Contact(name: String,
                   @(JSONTypeHint @field)(value = classOf[Address])
                   addresses: Map[String, Address]) {
  override def toString = "name = " + name + " addresses = " + => a._1 + ":" + a._2.toString).mkString(",")

Because of erasure, you need to add the type hint declaratively through the annotation @JSONTypeHint that
SJSON will pick up during serialization. No we can say:
val c = Contact("Bob", Map("residence" -> a1, "office" -> a2, "club" -> a3))
val co = serializer.out(c)
it("should give an instance of Contact") {
  c should equal([Contact](co))

With optional generic data members, we need to provide the hint to SJSON through another [email protected].
case class ContactWithOptionalAddr(name: String,
                              @(JSONTypeHint @field)(value = classOf[Address])
                              @(OptionTypeHint @field)(value = classOf[Map[_,_]])
                              addresses: Option[Map[String, Address]]) {
  override def toString = "name = " + name + " " +
    (addresses match {
      case None => ""
      case Some(ad) => " addresses = " + => a._1 + ":" + a._2.toString).mkString(",")

Serialization works ok with optional members annotated as above.
describe("Bean with optional bean member serialization") {
  it("should serialize with Option defined") {
    val c = new ContactWithOptionalAddr("Debasish Ghosh",
      Some(Map("primary" -> new Address("10 Market Street", "San Francisco, CA", "94111"),
          "secondary" -> new Address("3300 Tamarac Drive", "Denver, CO", "98301"))))
    c should equal([ContactWithOptionalAddr](serializer.out(c)))

You can also specify a custom ClassLoader while using SJSON serializer:
object SJSON {
  val classLoader = //.. specify a custom classloader
import SJSON._

Fighting Type Erasure

Because of type erasure, it's not always possible to infer the correct type during de-serialization of objects. Consider the following example:

abstract class A
@BeanInfo case class B(param1: String) extends A
@BeanInfo case class C(param1: String, param2: String) extends A
@BeanInfo case class D(@(JSONTypeHint @field)(value = classOf[A])param1: List[A])
and the serialization code like the following:

object TestSerialize{
 def main(args: Array[String]) {
   val test1 = new D(List(B("hello1")))
   val json = sjson.json.Serializer.SJSON.out(test1)
   val res =[D](json)
   val res1: D = res.asInstanceOf[D]
Note that the type hint on class D says A, but the actual instances that have been put into the object before serialization is one of the derived classes (B). During de-serialization, we have no idea of what can be inside D. The API will fail since all hint it has is for A, which is abstract. In such cases, we need to handle the de-serialization by using extractors over the underlying data structure that we use for storing JSON objects, which is JsValue. Here's an example:

val test1 = new D(List(B("hello1")))
val json = serializer.out(test1)
// create a JsValue from the string
val js = Js(new String(json))
// extract the named list argument
val m = (Symbol("param1") ? list)
val m(_m) = js
// extract the string within
val s = (Symbol("param1") ? str)
// form a list of B's
val result ={ e =>
  val s(_s) = e
// form a D
println("result = " + D(result))
The above snippet de-serializes correctly using extractors defined on JsValue. For more details on JsValue and the extractors, please refer to dispatch-json .


Serialization with SJSON is based on bean introspection. In the current version of Scala (2.8.0.Beta1 and 2.7.7) there is a bug where bean introspection does not work properly for classes enclosed within another class. Please ensure that the beans are the top level classes in your application. They can be within objects though. A ticket has been filed in the Scala Tracker and also fixed in the trunk. Here's the ticket .

Type class based Serialization

If type erasure hits you, reflection based serialization may not be the right option. In fact the last section shows some of the scenarios which may not be possible to handle using reflection based serialization of sjson. sjson also supports type class based serialization where you can provide a custom protocol for serialization as part of the type class implementation.

Here's a sample session at the REPL which shows the default serialization protocol of sjson:
scala> import sjson.json._
import sjson.json._
scala> import DefaultProtocol._
import DefaultProtocol._
scala> val str = "debasish"
str: java.lang.String = debasish
scala> import JsonSerialization._
import JsonSerialization._
scala> tojson(str)
res0: dispatch.json.JsValue = "debasish"
scala> fromjson[String](res0)
res1: String = debasish
You can use serialization of generic data types using the default protocol as well:
scala> val list = List(10, 12, 14, 18)
list: List[Int] = List(10, 12, 14, 18)
scala> tojson(list)
res2: dispatch.json.JsValue = [10, 12, 14, 18]
scala> fromjson[List[Int]](res2)
res3: List[Int] = List(10, 12, 14, 18)
You can also define your own custom protocol, which as to be an implementation of the following type class:
trait Writes[T] {
  def writes(o: T): JsValue
trait Reads[T] {
  def reads(json: JsValue): T
trait Format[T] extends Writes[T] with Reads[T]
Consider a case class and a custom protocol to serialize it into JSON. Here's the type class implementation:
object Protocols {
  case class Person(lastName: String, firstName: String, age: Int)
  object PersonProtocol extends DefaultProtocol {
    import dispatch.json._
    import JsonSerialization._
    implicit object PersonFormat extends Format[Person] {
      def reads(json: JsValue): Person = json match {
        case JsObject(m) =>
            fromjson[String](m(JsString("firstName"))), fromjson[Int](m(JsString("age"))))
        case _ => throw new RuntimeException("JsObject expected")
      def writes(p: Person): JsValue =
          (tojson("lastName").asInstanceOf[JsString], tojson(p.lastName)),
          (tojson("firstName").asInstanceOf[JsString], tojson(p.firstName)),
          (tojson("age").asInstanceOf[JsString], tojson(p.age)) ))
and the serialization in action in the REPL:
scala> import sjson.json._
import sjson.json._
scala> import Protocols._
import Protocols._
scala> import PersonProtocol._
import PersonProtocol._
scala> val p = Person("ghosh", "debasish", 20)
p: sjson.json.Protocols.Person = Person(ghosh,debasish,20)
scala> import JsonSerialization._
import JsonSerialization._
scala> tojson[Person](p)
res1: dispatch.json.JsValue = {"lastName" : "ghosh", "firstName" : "debasish", "age" : 20}
scala> fromjson[Person](res1)
res2: sjson.json.Protocols.Person = Person(ghosh,debasish,20)
There are other nifty ways to implement case class serialization using sjson. For more details, have a look at the wiki for sjson.

JSON: Java

Use the se.scalablesolutions.akka.serialization.Serialization.JavaJSON base class with its toJSONmethod. Akka’s Java JSON is based upon the Jackson library.

For your POJOs to be able to serialize themselves you have to extend the JavaJSON trait.
class MyMessage extends JavaJSON {
  private String name = null;
  public MyMessage(String name) { = name;
  public String getName() {
    return name;
MyMessage message = new MyMessage("json");
String json = message.toJSON();
SerializerFactory factory = new SerializerFactory();
MyMessage messageCopy = factory.getJavaJSON().in(json);

Use the se.scalablesolutions.akka.serialization.SerializerFactory.getJavaJSON to do generic JSONserialization, e.g. serialize object that does not extend JavaJSON using the JSON serializer.
Foo foo = new Foo();
SerializerFactory factory = new SerializerFactory();
String json = factory.getJavaJSON().out(foo);
Foo fooCopy = factory.getJavaJSON().in(json, Foo.class);

SBinary: Scala

To serialize Scala structures you can use SBinary serializer. SBinary can serialize all primitives and most default Scala datastructures; such as List, Tuple, Map, Set, BigInt etc.

Here is an example of using the se.scalablesolutions.akka.serialization.Serializer.SBinary serializer to serialize standard Scala library objects.
import se.scalablesolutions.akka.serialization.Serializer
import sbinary.DefaultProtocol._ // you always need to import these implicits
val users = List(("user1", "passwd1"), ("user2", "passwd2"), ("user3", "passwd3"))
val bytes = Serializer.SBinary.out(users)
val usersCopy =, Some(classOf[List[Tuple2[String,String]]]))

If you need to serialize your own user-defined objects then you have to do three things:
  1. Define an empty constructor
  2. Mix in the Serializable.SBinary[T] trait, and implement its methods:
    1. fromBytes(bytes: Array[Byte])[T]
    2. toBytes: Array[Byte]
  3. Create an implicit sbinary.Format[T] object for your class. Which means that you have to define its two methods:
    1. reads(in: Input): T; in which you read in all the fields in your object, using read[FieldType](in)and recreate it.
    2. writes(out: Output, value: T): Unit; in which you write out all the fields in your object, usingwrite[FieldType](out, value.field).

Here is an example:
case class User(val usernamePassword: Tuple2[String, String], val email: String, val age: Int)
  extends Serializable.SBinary[User] {
  import sbinary.DefaultProtocol._
  import sbinary.Operations._
  def this() = this(null, null, 0)
  implicit object UserFormat extends Format[User] {
    def reads(in : Input) = User(
      read[Tuple2[String, String]](in),
    def writes(out: Output, value: User) = {
      write[Tuple2[String, String]](out, value.usernamePassword)
      write[Int](out, value.age)
  def fromBytes(bytes: Array[Byte]) = fromByteArray[User](bytes)
  def toBytes: Array[Byte] = toByteArray(this)
Home Turn Off "Getting Started"