public abstract class SerializerWithStringManifest extends java.lang.Object implements Serializer
For serialization of data that need to evolve over time the SerializerWithStringManifest
is recommended instead
of Serializer
because the manifest (type hint) is a String
instead of a Class
. That means
that the class can be moved/removed and the serializer can still deserialize old data by matching
on the String
. This is especially useful for Akka Persistence.
The manifest string can also encode a version number that can be used in fromBinary
to
deserialize in different ways to migrate old data to new domain objects.
If the data was originally serialized with Serializer
and in a later version of the
system you change to SerializerWithStringManifest
the manifest string will be the full class name if
you used includeManifest=true
, otherwise it will be the empty string.
Serializers are loaded using reflection during ActorSystem
start-up, where two constructors are tried in order:
ExtendedActorSystem
;
this should be the preferred one because all reflective loading of classes
during deserialization should use ExtendedActorSystem.dynamicAccess (see
DynamicAccess
), and
Be sure to always use the DynamicAccess
for loading classes! This is necessary to
avoid strange match errors and inequalities which arise from different class loaders loading
the same class.
Constructor and Description |
---|
SerializerWithStringManifest() |
Modifier and Type | Method and Description |
---|---|
java.lang.Object |
fromBinary(byte[] bytes,
scala.Option<java.lang.Class<?>> manifest)
Produces an object from an array of bytes, with an optional type-hint;
the class should be loaded using ActorSystem.dynamicAccess.
|
abstract java.lang.Object |
fromBinary(byte[] bytes,
java.lang.String manifest)
Produces an object from an array of bytes, with an optional type-hint;
the class should be loaded using ActorSystem.dynamicAccess.
|
abstract int |
identifier()
Completely unique value to identify this implementation of Serializer, used to optimize network traffic.
|
boolean |
includeManifest()
Returns whether this serializer needs a manifest in the fromBinary method
|
abstract java.lang.String |
manifest(java.lang.Object o)
Return the manifest (type hint) that will be provided in the fromBinary method.
|
abstract byte[] |
toBinary(java.lang.Object o)
Serializes the given object into an Array of Byte
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
fromBinary, fromBinary
public abstract int identifier()
identifier
in interface Serializer
public final boolean includeManifest()
Serializer
includeManifest
in interface Serializer
public abstract java.lang.String manifest(java.lang.Object o)
""
if manifest is not needed.o
- (undocumented)public abstract byte[] toBinary(java.lang.Object o)
toBinary
in interface Serializer
o
- (undocumented)public abstract java.lang.Object fromBinary(byte[] bytes, java.lang.String manifest)
It's recommended to throw java.io.NotSerializableException
in fromBinary
if the manifest is unknown. This makes it possible to introduce new message
types and send them to nodes that don't know about them. This is typically
needed when performing rolling upgrades, i.e. running a cluster with mixed
versions for while. NotSerializableException
is treated as a transient
problem in the TCP based remoting layer. The problem will be logged
and message is dropped. Other exceptions will tear down the TCP connection
because it can be an indication of corrupt bytes from the underlying transport.
bytes
- (undocumented)manifest
- (undocumented)public final java.lang.Object fromBinary(byte[] bytes, scala.Option<java.lang.Class<?>> manifest)
Serializer
fromBinary
in interface Serializer
bytes
- (undocumented)manifest
- (undocumented)