From ca911038ebb73d87014d87eb96692825f8fc40e9 Mon Sep 17 00:00:00 2001 From: Viktor Klang Date: Fri, 30 Dec 2011 20:46:04 +0100 Subject: [PATCH] Adding Scala reST docs for Serialization --- .../serialization/SerializationDocSpec.scala | 134 ++++++++++++++++++ akka-docs/scala/serialization.rst | 53 ++++++- 2 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 akka-docs/scala/code/akka/docs/serialization/SerializationDocSpec.scala diff --git a/akka-docs/scala/code/akka/docs/serialization/SerializationDocSpec.scala b/akka-docs/scala/code/akka/docs/serialization/SerializationDocSpec.scala new file mode 100644 index 0000000000..487f2e52b9 --- /dev/null +++ b/akka-docs/scala/code/akka/docs/serialization/SerializationDocSpec.scala @@ -0,0 +1,134 @@ +/** + * Copyright (C) 2009-2011 Typesafe Inc. + */ +package akka.docs.serialization + +import org.scalatest.matchers.MustMatchers +import akka.testkit._ +import akka.actor.ActorSystem +import com.typesafe.config.ConfigFactory + +//#imports +import akka.serialization._ + +//#imports + +object SerializationDocSpec { + +} + +//#my-own-serializer +class MyOwnSerializer extends Serializer { + + // This is whether "fromBinary" requires a "clazz" or not + def includeManifest: Boolean = false + + // Pick a unique identifier for your Serializer, + // you've got a couple of billions to choose from, + // 0 - 16 is reserved by Akka itself + def identifier = 1234567: Serializer.Identifier + + // "toBinary" serializes the given object to an Array of Bytes + def toBinary(obj: AnyRef): Array[Byte] = { + // Put the code that serializes the object here + //#... + Array[Byte]() + //#... + } + + // "fromBinary" deserializes the given array, + // using the type hint (if any, see "includeManifest" above) + // into the optionally provided classLoader. + def fromBinary(bytes: Array[Byte], + clazz: Option[Class[_]], + classLoader: Option[ClassLoader] = None): AnyRef = { + // Put your code that deserializes here + //#... + null + //#... + } +} +//#my-own-serializer + +class SerializationDocSpec extends AkkaSpec { + "demonstrate configuration of serialize messages" in { + //#serialize-messages-config + val config = ConfigFactory.parseString(""" + akka { + actor { + serialize-messages = on + } + } + """) + //#serialize-messages-config + val a = ActorSystem("system", config) + a.settings.SerializeAllMessages must be(true) + a.shutdown() + } + + "demonstrate configuration of serialize creators" in { + //#serialize-creators-config + val config = ConfigFactory.parseString(""" + akka { + actor { + serialize-creators = on + } + } + """) + //#serialize-creators-config + val a = ActorSystem("system", config) + a.settings.SerializeAllCreators must be(true) + a.shutdown() + } + + "demonstrate configuration of serializers" in { + //#serialize-serializers-config + val config = ConfigFactory.parseString(""" + akka { + actor { + serializers { + default = "akka.serialization.JavaSerializer" + + myown = "akka.docs.serialization.MyOwnSerializer" + } + } + } + """) + //#serialize-serializers-config + val a = ActorSystem("system", config) + SerializationExtension(a).serializers("default").getClass.getName must equal("akka.serialization.JavaSerializer") + SerializationExtension(a).serializers("myown").getClass.getName must equal("akka.docs.serialization.MyOwnSerializer") + a.shutdown() + } + + "demonstrate configuration of serialization-bindings" in { + //#serialization-bindings-config + val config = ConfigFactory.parseString(""" + akka { + actor { + serializers { + default = "akka.serialization.JavaSerializer" + java = "akka.serialization.JavaSerializer" + myown = "akka.docs.serialization.MyOwnSerializer" + } + + serialization-bindings { + java = ["java.lang.String", + "app.my.Customer"] + myown = ["my.own.BusinessObject", + "something.equally.Awesome", + "java.lang.Boolean"] + } + } + } + """) + //#serialization-bindings-config + val a = ActorSystem("system", config) + SerializationExtension(a).serializers("default").getClass.getName must equal("akka.serialization.JavaSerializer") + SerializationExtension(a).serializers("java").getClass.getName must equal("akka.serialization.JavaSerializer") + SerializationExtension(a).serializers("myown").getClass.getName must equal("akka.docs.serialization.MyOwnSerializer") + SerializationExtension(a).serializerFor(classOf[String]).getClass.getName must equal("akka.serialization.JavaSerializer") + SerializationExtension(a).serializerFor(classOf[java.lang.Boolean]).getClass.getName must equal("akka.docs.serialization.MyOwnSerializer") + a.shutdown() + } +} diff --git a/akka-docs/scala/serialization.rst b/akka-docs/scala/serialization.rst index 3f5f30669d..2c71020cb8 100644 --- a/akka-docs/scala/serialization.rst +++ b/akka-docs/scala/serialization.rst @@ -21,14 +21,65 @@ Usage Configuration ------------- +For Akka to know which ``Serializer`` to use for what, you need edit your Akka Configuration, +in the "akka.actor.serializers"-section you bind names to implementations of the ``akka.serialization.Serializer`` +you wish to use, like this: + +.. includecode:: code/akka/docs/serialization/SerializationDocSpec.scala#serialize-serializers-config + +.. note:: + + The name ``default`` is special in the sense that the ``Serializer`` + mapped to it will be used as default. + +After you've bound names to different implementations of ``Serializer`` you need to wire which classes +should be serialized using which ``Serializer``, this is done in the "akka.actor.serialization-bindings"-section: + +.. includecode:: code/akka/docs/serialization/SerializationDocSpec.scala#serialization-bindings-config + +.. note:: + + Akka currently only checks for absolute equality of Classes, i.e. it does not yet check ``isAssignableFrom``, + this means that you'll need to list the specific classes. + +Verification +------------ + +If you want to verify that your messages are serializable you can enable the following config option: + +.. includecode:: code/akka/docs/serialization/SerializationDocSpec.scala#serialize-messages-config + +.. warning:: + + We only recommend using the config option turned on when you're running tests. + It is completely pointless to have it turned on in other scenarios. + +If you want to verify that your ``Props`` are serializable you can enable the following config option: + +.. includecode:: code/akka/docs/serialization/SerializationDocSpec.scala#serialize-creators-config + +.. warning:: + + We only recommend using the config option turned on when you're running tests. + It is completely pointless to have it turned on in other scenarios. + Programmatic ------------ Customization ============= +So, lets say that you want to create your own ``Serializer``, +you saw the ``akka.docs.serialization.MyOwnSerializer`` in the config example above? + Creating new Serializers ------------------------ +First you need to create a class definition of your ``Serializer`` like so: -* `Serializers `_ \ No newline at end of file +.. includecode:: code/akka/docs/serialization/SerializationDocSpec.scala + :include: imports,my-own-serializer + :exclude: ... + +Then you only need to fill in the blanks, bind it to a name in your Akka Configuration and then +list which classes that should be serialized using it. \ No newline at end of file