!str - 18916 - Source.file and Sink.file

* Removes `Synchronous` from the names and descriptions of File I/O as it leaks impl details
* Removes the factries for FileSource and FileSink and puts them in Source and Sink respectively

akka-docs-dev/rst/java/code/docs/MigrationsJava.java

@@ -6,11 +6,14 @@ import akka.japi.Pair;
 import akka.japi.function.Function;
 import akka.stream.*;
 import akka.stream.javadsl.*;
+import akka.util.ByteString;
 import scala.Option;
+import scala.concurrent.Future;
 import scala.concurrent.duration.FiniteDuration;
 import scala.concurrent.Promise;
 import scala.runtime.BoxedUnit;
 
+import java.io.File;
 import java.util.concurrent.TimeUnit;
 import java.nio.charset.Charset;
 
@@ -146,6 +149,17 @@ public class MigrationsJava {
         //#query-param
         final akka.japi.Option<String> aQueryParam = uri.query().get("a");
         //#query-param
+
+        //#file-source-sink
+        final Source<ByteString, Future<Long>> fileSrc =
+          Source.file(new File("."));
+
+        final Source<ByteString, Future<Long>> otherFileSrc =
+          Source.file(new File("."), 1024);
+
+        final Sink<ByteString, Future<Long>> fileSink =
+          Sink.file(new File("."));
+        //#file-source-sink
     }
 
 }

akka-docs-dev/rst/java/migration-guide-1.0-2.x-java.rst

@@ -420,3 +420,39 @@ And use of query parameters from ``Uri`` that looked like this:
 should be replaced by:
 
 .. includecode:: code/docs/MigrationsJava.java#query-param
+
+SynchronousFileSource and SynchronousFileSink
+============================================
+
+Both have been replaced by `Source.file(…)` and `Sink.file(…)` due to discoverability issues
+paired with names which leaked internal implementation details.
+
+Update procedure
+----------------
+
+Replace `SynchronousFileSource.create(` with `Source.file(`
+
+Replace `SynchronousFileSink.create(` with `Sink.file(`
+
+Replace `SynchronousFileSink.appendTo(f)` with `Sink.file(f, true)`
+
+Example
+^^^^^^^
+
+::
+
+      // This no longer works!
+      final Source<ByteString, Future<java.lang.Long>> src =
+        SynchronousFileSource.create(new File("."));
+
+      // This no longer works!
+      final Source<ByteString, Future<java.lang.Long>> src =
+        SynchronousFileSource.create(new File("."), 1024);
+
+      // This no longer works!
+      final Sink<ByteString, Future<java.lang.Long>> sink =
+              `SynchronousFileSink.appendTo(new File("."));
+
+should be replaced by
+
+.. includecode:: code/docs/MigrationsJava.java#file-source-sink

akka-docs-dev/rst/java/stream-io.rst

@@ -110,7 +110,7 @@ on files.
   Once Akka is free to require JDK8 (from ``2.4.x``) these implementations will be updated to make use of the
   new NIO APIs (i.e. :class:`AsynchronousFileChannel`).
 
-Streaming data from a file is as easy as defining a `SynchronousFileSource` given a target file, and an optional
+Streaming data from a file is as easy as creating a `Source.file` given a target file, and an optional
 ``chunkSize`` which determines the buffer size determined as one "element" in such stream:
 
 .. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/io/StreamFileDocTest.java#file-source