From f4e16dcc55c5cd5e4f2b9b47d73a997fb749643b Mon Sep 17 00:00:00 2001 From: Konrad Malawski Date: Fri, 30 Sep 2016 16:04:22 +0200 Subject: [PATCH] +doc removing java serialization in java ref docs (#21603) --- akka-docs/rst/java/remoting.rst | 71 ++++++++++++++++++++++++++++++-- akka-docs/rst/scala/remoting.rst | 7 +++- 2 files changed, 73 insertions(+), 5 deletions(-) diff --git a/akka-docs/rst/java/remoting.rst b/akka-docs/rst/java/remoting.rst index 6666617888..84813d8605 100644 --- a/akka-docs/rst/java/remoting.rst +++ b/akka-docs/rst/java/remoting.rst @@ -1,8 +1,7 @@ .. _remoting-java: -##################### - Remoting -##################### +Remoting +######## For an introduction of remoting capabilities of Akka please see :ref:`remoting`. @@ -260,6 +259,72 @@ those actors are serializable. Failing to do so will cause the system to behave For more information please see :ref:`serialization-java`. +Disabling the Java Serializer +----------------------------- + +Since the ``2.4.11`` release of Akka it is possible to entirely disable the default Java Serialization mechanism. +Please note that :ref:`new remoting implementation (codename Artery) ` does not use Java +serialization for internal messages by default. For compatibility reasons, the current remoting still uses Java +serialization for some classes, however you can disable it in this remoting implementation as well by following +the steps below. + +Java serialization is known to be slow and prone to attacks of various kinds - it never was designed for high +throughput messaging after all. However it is very convenient to use, thus it remained the default serialization +mechanism that Akka used to serialize user messages as well as some of its internal messages in previous versions. +Since the release of Artery, Akka internals do not rely on Java serialization anymore (one exception being ``java.lang.Throwable``). + +.. note:: + When using the new remoting implementation (codename Artery), Akka does not use Java Serialization for any of it's internal messages. + It is highly encouraged to disable java serialization, so please plan to do so at the earliest possibility you have in your project. + + One may think that network bandwidth and latency limit the performance of remote messaging, but serialization is a more typical bottleneck. + +For user messages, the default serializer, implemented using Java serialization, remains available and enabled in Artery. +We do however recommend to disable it entirely and utilise a proper serialization library instead in order effectively utilise +the improved performance and ability for rolling deployments using Artery. Libraries that we recommend to use include, +but are not limited to, `Kryo`_ by using the `akka-kryo-serialization`_ library or `Google Protocol Buffers`_ if you want +more control over the schema evolution of your messages. + +In order to completely disable Java Serialization in your Actor system you need to add the following configuration to +your ``application.conf``: + +.. code-block:: ruby + + akka { + actor { + serialization-bindings { + "java.io.Serializable" = none + } + } + } + +Please note that this means that you will have to configure different serializers which will able to handle all of your +remote messages. Please refer to the :ref:`serialization-scala` documentation as well as :ref:`ByteBuffer based serialization ` to learn how to do this. + +.. warning:: + Please note that when enabling the additional-serialization-bindings when using the old remoting, + you must do so on all nodes participating in a cluster, otherwise the mis-aligned serialization + configurations will cause deserialization errors on the receiving nodes. + +You can also easily enable additional serialization bindings that are provided by Akka that are not using Java serialization: + +.. code-block: ruby + akka.actor { + # Set this to on to enable serialization-bindings define in + # additional-serialization-bindings. Those are by default not included + # for backwards compatibility reasons. They are enabled by default if + # akka.remote.artery.enabled=on. + enable-additional-serialization-bindings = on + } + +The reason these are not enabled by default is wire-level compatibility between any 2.4.x Actor Systems. +If you roll out a new cluster, all on the same Akka version that can enable these serializers it is recommended to +enable this setting. When using :ref:`remoting-artery-scala` these serializers are enabled by default. + +.. _Kryo: https://github.com/EsotericSoftware/kryo +.. _akka-kryo-serialization: https://github.com/romix/akka-kryo-serialization +.. _Google Protocol Buffers: https://developers.google.com/protocol-buffers/ + Routers with Remote Destinations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/akka-docs/rst/scala/remoting.rst b/akka-docs/rst/scala/remoting.rst index 14aa975cb7..594005ce6d 100644 --- a/akka-docs/rst/scala/remoting.rst +++ b/akka-docs/rst/scala/remoting.rst @@ -265,10 +265,13 @@ those actors are serializable. Failing to do so will cause the system to behave For more information please see :ref:`serialization-scala`. Disabling the Java Serializer -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- Since the ``2.4.11`` release of Akka it is possible to entirely disable the default Java Serialization mechanism. -The :ref:`new remoting implementation (codename Artery) ` +Please note that :ref:`new remoting implementation (codename Artery) ` does not use Java +serialization for internal messages by default. For compatibility reasons, the current remoting still uses Java +serialization for some classes, however you can disable it in this remoting implementation as well by following +the steps below. Java serialization is known to be slow and prone to attacks of various kinds - it never was designed for high throughput messaging after all. However it is very convenient to use, thus it remained the default serialization