* 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:
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.
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``.
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.
To deserialize the ``ActorRef`` to a ``RemoteActorRef`` you need to use the ``fromBinaryToRemoteActorRef(bytes: Array[Byte])`` method on the ``ActorRef`` companion object:
Serialization of typed actors works almost the same way as untyped actors. You can serialize the whole actor deeply, e.g. both the 'proxied ActorRef' and the instance of its ``TypedActor``.
To deserialize the TypedActor to a ``RemoteTypedActorRef`` (an aspectwerkz proxy to a RemoteActorRef) you need to use the ``fromBinaryToRemoteTypedActorRef(bytes: Array[Byte])`` method on ``RemoteTypedActorSerialization`` object:
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:
..code-block:: scala
import 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 and these messages implement one of the predefined interfaces/traits in the ``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.
Apart from the above, Akka also supports Scala object serialization through `SJSON <http://github.com/debasishg/sjson/tree/master>`_ that implements APIs similar to ``akka.serialization.Serializer.*``. See the section on SJSON below for details.
Akka supports using `Google Protocol Buffers <http://code.google.com/p/protobuf>`_ 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.
..code-block:: scala
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:
..code-block:: scala
val result = remoteActor !! ProtobufPOJO.newBuilder
.setId(11)
.setStatus(true)
.setName("Coltrane")
.build
The remote Actor can then receive the Protobuf message typed as-is:
For your POJOs to be able to serialize themselves you have to extend the ScalaJSON[] trait as follows. JSON serialization is based on a type class protocol which you need to define for your own abstraction. The instance of the type class is defined as an implicit object which is used for serialization and de-serialization. You also need to implement the methods in terms of the APIs which sjson publishes.
it("should be able to serialize and de-serialize MyMessage") {
val s = MyMessage("Target", ("cooker", 120))
s.fromBytes(s.toBytes) should equal(s)
s.fromJSON(s.toJSON) should equal(s)
}
Use akka.serialization.Serializer.ScalaJSON to do generic JSON serialization, e.g. serialize object that does not extend ScalaJSON using the JSON serializer. Serialization using Serializer can be done in two ways :-
1. Type class based serialization (recommended)
2. Reflection based serialization
We will discuss both of these techniques in this section. For more details refer to the discussion in the next section SJSON: Scala.
Serializer API using type classes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here are the steps that you need to follow:
1. Define your class
..code-block:: scala
case class MyMessage(val id: String, val value: Tuple2[String, Int])
You can also use the Serializer abstraction to serialize using the reflection based serialization API of sjson. But we recommend using the type class based one, because reflection based serialization has limitations due to type erasure. Here's an example of reflection based serialization:
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 <http://github.com/debasishg/sjson/tree/master>`_.
Example: I have a Scala object as ..
..code-block:: scala
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.
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 ..
..code-block:: scala
serializer.in[AnyRef](serializer.out(addr))
or just as ..
..code-block:: scala
serializer.in(serializer.out(addr))
What you get back from is a JsValue, an abstraction of the JSON object model. For details of JsValueimplementation, refer to `dispatch-json <http://databinder.net/dispatch/About>`_ 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 ..
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 ..
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.
val j = Journal(100, "IEEE Computer", "Alex Payne", "012-456372")
serializer.in[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}.
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 serializer.in 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:
The above snippet de-serializes correctly using extractors defined on JsValue. For more details on JsValue and the extractors, please refer to `dispatch-json <http://databinder.net/dispatch/About>`_ .
**NOTE**: 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 <https://lampsvn.epfl.ch/trac/scala/ticket/3080>`_ .
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:
..code-block:: scala
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:
..code-block:: scala
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:
..code-block:: scala
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:
..code-block:: scala
object Protocols {
case class Person(lastName: String, firstName: String, age: Int)
There are other nifty ways to implement case class serialization using sjson. For more details, have a look at the `wiki <http://wiki.github.com/debasishg/sjson/typeclass-based-json-serialization>`_ for sjson.
Use the akka.serialization.SerializerFactory.getJavaJSON to do generic JSON serialization, e.g. serialize object that does not extend JavaJSON using the JSON serializer.
