Adding Scala reST docs for Serialization

akka-docs/scala/code/akka/docs/serialization/SerializationDocSpec.scala

@@ -0,0 +1,134 @@
+/**
+ * Copyright (C) 2009-2011 Typesafe Inc. <http://www.typesafe.com>
+ */
+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()
+  }
+}

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 <https://github.com/jboner/akka/blob/master/akka-actor/src/main/resources/reference.conf#L180>`_
+.. 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.