Merged with master

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

@@ -7,7 +7,6 @@ import org.junit.Test;
 import static org.junit.Assert.*;
 //#imports
 import akka.actor.*;
-import akka.remote.RemoteActorRefProvider;
 import akka.serialization.*;
 
 //#imports
@@ -58,20 +57,10 @@ public class SerializationDocTestBase {
     //#actorref-serializer
     // Serialize
     // (beneath toBinary)
-    final Address transportAddress =
-      Serialization.currentTransportAddress().value();
-    String identifier;
+    String identifier = Serialization.serializedActorPath(theActorRef);
 
-    // 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().toSerializationFormat();
-    else identifier = theActorRef.path().toSerializationFormatWithAddress(transportAddress);
     // Then just serialize the identifier however you like
 
-
     // Deserialize
     // (beneath fromBinary)
     final ActorRef deserializedActorRef = theActorSystem.actorFor(identifier);
@@ -118,16 +107,20 @@ public class SerializationDocTestBase {
   }
 
   //#external-address
-
-  public void demonstrateExternalAddress() {
-    // this is not meant to be run, only to be compiled
+  static
+  //#external-address
+  public class ExternalAddressExample {
+    //#external-address
     final ActorSystem system = ActorSystem.create();
-    final Address remoteAddr = new Address("", "");
-    // #external-address
-    final Address addr = ExternalAddress.ID.get(system).getAddressFor(remoteAddr);
-    // #external-address
+    //#external-address
+    public String serializeTo(ActorRef ref, Address remote) {
+      return ref.path().toSerializationFormatWithAddress(
+          ExternalAddress.ID.get(system).getAddressFor(remote));
+    }
   }
 
+  //#external-address
+
   static
   //#external-address-default
   public class DefaultAddressExt implements Extension {

akka-docs/rst/java/serialization.rst

@@ -109,8 +109,11 @@ 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:
+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.
+In the general case, the local address to be used depends on the type of remote
+address which shall be the recipient of the serialized information. Use
+:meth:`Serialization.serializedActorPath(actorRef)` like this:
 
 .. includecode:: code/docs/serialization/SerializationDocTestBase.java
    :include: imports
@@ -118,6 +121,22 @@ you might want to know how to serialize and deserialize them properly, here's th
 .. includecode:: code/docs/serialization/SerializationDocTestBase.java
    :include: actorref-serializer
 
+This assumes that serialization happens in the context of sending a message
+through the remote transport. There are other uses of serialization, though,
+e.g. storing actor references outside of an actor application (database,
+durable mailbox, etc.). In this case, it is important to keep in mind that the
+address part of an actor’s path determines how that actor is communicated with.
+Storing a local actor path might be the right choice if the retrieval happens
+in the same logical context, but it is not enough when deserializing it on a
+different network host: for that it would need to include the system’s remote
+transport address. An actor system is not limited to having just one remote
+transport per se, which makes this question a bit more interesting. To find out
+the appropriate address to use when sending to ``remoteAddr`` you can use
+:meth:`ActorRefProvider.getExternalAddressFor(remoteAddr)` like this:
+
+.. includecode:: code/docs/serialization/SerializationDocTestBase.java
+   :include: external-address
+
 .. note::
   
   ``ActorPath.toSerializationFormatWithAddress`` differs from ``toString`` if the
@@ -132,25 +151,6 @@ you might want to know how to serialize and deserialize them properly, here's th
   include the unique id.
 
 
-This assumes that serialization happens in the context of sending a message
-through the remote transport. There are other uses of serialization, though,
-e.g. storing actor references outside of an actor application (database,
-durable mailbox, etc.). In this case, it is important to keep in mind that the
-address part of an actor’s path determines how that actor is communicated with.
-Storing a local actor path might be the right choice if the retrieval happens
-in the same logical context, but it is not enough when deserializing it on a
-different network host: for that it would need to include the system’s remote
-transport address. An actor system is not limited to having just one remote
-transport per se, which makes this question a bit more interesting.
-
-In the general case, the local address to be used depends on the type of remote
-address which shall be the recipient of the serialized information. Use
-:meth:`ActorRefProvider.getExternalAddressFor(remoteAddr)` to query the system
-for the appropriate address to use when sending to ``remoteAddr``:
-
-.. includecode:: code/docs/serialization/SerializationDocTestBase.java
-   :include: external-address
-
 This requires that you know at least which type of address will be supported by
 the system which will deserialize the resulting actor reference; if you have no
 concrete address handy you can create a dummy one for the right protocol using