#1885 - Adding section on serializing ActorRefs

akka-docs/java/code/akka/docs/serialization/SerializationDocTestBase.java

@@ -3,17 +3,11 @@
  */
 package akka.docs.serialization;
 
-import akka.japi.Option;
-import akka.serialization.JSerializer;
-import akka.serialization.Serialization;
-import akka.serialization.SerializationExtension;
-import akka.serialization.Serializer;
 import org.junit.Test;
 import static org.junit.Assert.*;
 //#imports
-
+import akka.actor.*;
 import akka.serialization.*;
-import akka.actor.ActorSystem;
 import com.typesafe.config.*;
 
 //#imports
@@ -54,6 +48,37 @@ public class SerializationDocTestBase {
     }
 //#my-own-serializer
 
+    @Test public void serializeActorRefs() {
+        final ActorSystem theActorSystem =
+                ActorSystem.create("whatever");
+        final ActorRef theActorRef =
+                theActorSystem.deadLetters(); // Of course this should be you
+
+        //#actorref-serializer
+        // Serialize
+        // (beneath toBinary)
+        final Address transportAddress =
+                Serialization.currentTransportAddress().value();
+        String identifier;
+
+        // If there is no transportAddress,
+        // it means that either this Serializer isn't called
+        // within a piece of code that sets it,
+        // so either you need to supply your own,
+        // or simply use the local path.
+        if (transportAddress == null) identifier = theActorRef.path().toString();
+        else identifier = theActorRef.path().toStringWithAddress(transportAddress);
+        // Then just serialize the identifier however you like
+
+
+        // Deserialize
+        // (beneath fromBinary)
+        final ActorRef deserializedActorRef = theActorSystem.actorFor(identifier);
+        // Then just use the ActorRef
+        //#actorref-serializer
+        theActorSystem.shutdown();
+    }
+
 
     @Test public void demonstrateTheProgrammaticAPI() {
       //#programmatic

akka-docs/java/serialization.rst

@@ -104,6 +104,15 @@ which is done by extending ``akka.serialization.JSerializer``, like this:
 Then you only need to fill in the blanks, bind it to a name in your :ref:`configuration` and then
 list which classes that should be serialized using it.
 
+Serializing ActorRefs
+---------------------
+
+All ActorRefs are serializable using JavaSerializer, but in case you are writing your own serializer,
+you might want to know how to serialize and deserialize them properly, here's the magic incantation:
+
+.. includecode:: code/akka/docs/serialization/SerializationDocTestBase.java
+   :include: imports,actorref-serializer
+
 A Word About Java Serialization
 ===============================
 

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

@@ -5,8 +5,9 @@ package akka.docs.serialization
 
 import org.scalatest.matchers.MustMatchers
 import akka.testkit._
+import akka.actor.{ ActorRef, ActorSystem }
+
 //#imports
-import akka.actor.ActorSystem
 import akka.serialization._
 import com.typesafe.config.ConfigFactory
 
@@ -150,4 +151,30 @@ class SerializationDocSpec extends AkkaSpec {
     //#programmatic
     system.shutdown()
   }
+
+  "demonstrate serialization of ActorRefs" in {
+    val theActorRef: ActorRef = system.deadLetters
+    val theActorSystem: ActorSystem = system
+
+    //#actorref-serializer
+    // Serialize
+    // (beneath toBinary)
+
+    // If there is no transportAddress,
+    // it means that either this Serializer isn't called
+    // within a piece of code that sets it,
+    // so either you need to supply your own,
+    // or simply use the local path.
+    val identifier: String = Serialization.currentTransportAddress.value match {
+      case null    ⇒ theActorRef.path.toString
+      case address ⇒ theActorRef.path.toStringWithAddress(address)
+    }
+    // Then just serialize the identifier however you like
+
+    // Deserialize
+    // (beneath fromBinary)
+    val deserializedActorRef = theActorSystem actorFor identifier
+    // Then just use the ActorRef
+    //#actorref-serializer
+  }
 }

akka-docs/scala/serialization.rst

@@ -102,6 +102,15 @@ First you need to create a class definition of your ``Serializer`` like so:
 Then you only need to fill in the blanks, bind it to a name in your :ref:`configuration` and then
 list which classes that should be serialized using it.
 
+Serializing ActorRefs
+---------------------
+
+All ActorRefs are serializable using JavaSerializer, but in case you are writing your own serializer,
+you might want to know how to serialize and deserialize them properly, here's the magic incantation:
+
+.. includecode:: code/akka/docs/serialization/SerializationDocSpec.scala
+   :include: imports,actorref-serializer
+
 A Word About Java Serialization
 ===============================