add migration guides for Scala and Java

also fix missing includes and wrong file locations

akka-docs/rst/java/stream/migration-guide-2.0-2.4-java.rst

@@ -0,0 +1,75 @@
+.. _migration-streams-2.0-2.4-java:
+
+##############################
+Migration Guide 2.0.x to 2.4.x
+##############################
+
+General notes
+=============
+
+akka.Done and akka.NotUsed replacing Unit and BoxedUnit
+-------------------------------------------------------
+
+To provide more clear signatures and have a unified API for both
+Java and Scala two new types have been introduced:
+
+``akka.NotUsed`` is meant to be used instead of ``Unit`` in Scala
+and ``BoxedUnit`` in Java to signify that the type parameter is required
+but not actually used. This is commonly the case with ``Source``, ``Flow`` and ``Sink``
+that do not materialize into any value.
+
+``akka.Done`` is added for the use case where it is boxed inside another object to signify
+completion but there is no actual value attached to the completion. It is used to replace
+occurrences of ``Future<BoxedUnit>`` with ``Future<Done>`` in Java and ``Future[Unit]`` with
+``Future[Done]`` in Scala.
+
+All previous usage of ``Unit`` and ``BoxedUnit`` for these two cases in the akka streams APIs
+has been updated.
+
+This means that Java code like this::
+
+    Source<String, BoxedUnit> source = Source.from(Arrays.asList("1", "2", "3"));
+    Sink<String, Future<BoxedUnit>> sink = Sink.ignore();
+
+needs to be changed into::
+
+    Source<String, NotUsed> source = Source.from(Arrays.asList("1", "2", "3"));
+    Sink<String, Future<Done>> sink = Sink.ignore();
+
+These changes apply to all the places where streams are used, which means that signatures
+in the persistent query APIs also are affected.
+
+Changed Operators
+=================
+
+``expand()`` is now based on an Iterator
+----------------------------------------
+
+Previously the ``expand`` combinator required two functions as input: the first
+one lifted incoming values into an extrapolation state and the second one
+extracted values from that, possibly evolving that state. This has been
+simplified into a single function that turns the incoming element into an
+Iterator.
+
+The most prominent use-case previously was to just repeat the previously received value::
+
+    // This no longer works!
+    Flow.of(Integer.class).expand(i -> i)(i -> new Pair<>(i, i)); 
+
+In Akka 2.4.x this is simplified to:
+
+.. includecode:: ../code/docs/stream/MigrationsJava.java#expand-continually
+
+If state needs to be be kept during the expansion process then this state will
+need to be managed by the Iterator. The example of counting the number of
+expansions might previously have looked like::
+
+    // This no longer works!
+    Flow.of(Integer.class).expand(i -> new Pair<>(i, 0))(
+      pair -> new Pair<>(new Pair<>(pair.first(), pair.second()),
+                         new Pair<>(pair.first(), pair.second() + 1)));
+
+In Akka 2.4.x this is formulated like so:
+
+.. includecode:: ../code/docs/stream/MigrationsJava.java#expand-state
+