+act #17576 Support serializer with string manifest

* useful when evolution is needed, e.g. Akka Persistence

* docs, comments, cluster-metrics and cluster-tools serializers

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

@@ -3,9 +3,14 @@
  */
 package docs.serialization;
 
+import java.io.UnsupportedEncodingException;
+
 import akka.testkit.JavaTestKit;
+
 import org.junit.Test;
 import static org.junit.Assert.*;
+import java.nio.charset.StandardCharsets;
+
 //#imports
 import akka.actor.*;
 import akka.serialization.*;
@@ -49,6 +54,79 @@ public class SerializationDocTest {
   }
 //#my-own-serializer
 
+  static class Customer {
+    public final String name;
+    
+    Customer(String name) {
+      this.name = name;
+    }
+  }
+  
+  static class User {
+    public final String name;
+    
+    User(String name) {
+      this.name = name;
+    }
+  }
+  
+  static
+  //#my-own-serializer2
+  public class MyOwnSerializer2 extends SerializerWithStringManifest {
+
+    private static final String CUSTOMER_MANIFEST = "customer";
+    private static final String USER_MANIFEST = "user";
+    private static final String UTF_8 = StandardCharsets.UTF_8.name();
+    
+    // Pick a unique identifier for your Serializer,
+    // you've got a couple of billions to choose from,
+    // 0 - 16 is reserved by Akka itself
+    @Override public int identifier() {
+      return 1234567;
+    }
+    
+    @Override public String manifest(Object obj) {
+      if (obj instanceof Customer)
+        return CUSTOMER_MANIFEST;
+      else if (obj instanceof User)
+        return USER_MANIFEST;
+      else 
+        throw new IllegalArgumentException("Unknow type: " + obj);
+    }
+
+    // "toBinary" serializes the given object to an Array of Bytes
+    @Override public byte[] toBinary(Object obj) {
+      // Put the real code that serializes the object here
+      try {
+        if (obj instanceof Customer)
+          return ((Customer) obj).name.getBytes(UTF_8);
+        else if (obj instanceof User)
+          return ((User) obj).name.getBytes(UTF_8);
+        else 
+          throw new IllegalArgumentException("Unknow type: " + obj);
+      } catch (UnsupportedEncodingException e) {
+        throw new RuntimeException(e.getMessage(), e);
+      }
+    }
+
+    // "fromBinary" deserializes the given array,
+    // using the type hint
+    @Override public Object fromBinary(byte[] bytes, String manifest) {
+      // Put the real code that deserializes here
+      try {
+        if (manifest.equals(CUSTOMER_MANIFEST))
+          return new Customer(new String(bytes, UTF_8));
+        else if (manifest.equals(USER_MANIFEST))
+          return new User(new String(bytes, UTF_8));
+        else 
+          throw new IllegalArgumentException("Unknow manifest: " + manifest);
+      } catch (UnsupportedEncodingException e) {
+        throw new RuntimeException(e.getMessage(), e);
+      }
+    }
+  }
+//#my-own-serializer2
+
   @Test public void serializeActorRefs() {
     final ExtendedActorSystem extendedSystem = (ExtendedActorSystem)
       ActorSystem.create("whatever");