diff --git a/akka-docs/src/main/paradox/stream/operators/FileIO/fromFile.md b/akka-docs/src/main/paradox/stream/operators/FileIO/fromFile.md new file mode 100644 index 0000000000..67d2ccc384 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/FileIO/fromFile.md @@ -0,0 +1,25 @@ +# FileIO.fromFile + +Emits the contents of a file. + +@ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources) + +@@@ warning + +The `fromFile` operator has been deprecated, use @ref:[fromPath](./fromPath.md) instead. + +@@@ + +@@@div { .group-scala } + +## Signature + +@@signature [FileIO.scala](/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala) { #fromFile } + +@@@ + +## Description + +Emits the contents of a file, as `ByteString`s, materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with +a `IOResult` upon reaching the end of the file or if there is a failure. + diff --git a/akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md b/akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md index 174b62e9f1..ee2eac2223 100644 --- a/akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md +++ b/akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md @@ -1,6 +1,6 @@ # FileIO.fromPath -Emit the contents of a file. +Emits the contents of a file from the given path. @ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources) @@ -14,5 +14,14 @@ Emit the contents of a file. ## Description -Emit the contents of a file, as `ByteString`s, materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with +Emits the contents of a file from the given path, as `ByteString`s, materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a `IOResult` upon reaching the end of the file or if there is a failure. + +## Example + +Scala +: @@snip [StreamFileDocSpec.scala](/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala) { #file-source } + +Java +: @@snip [StreamFileDocTest.java](/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java) { #file-source } + diff --git a/akka-docs/src/main/paradox/stream/operators/FileIO/toFile.md b/akka-docs/src/main/paradox/stream/operators/FileIO/toFile.md new file mode 100644 index 0000000000..c53703320f --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/FileIO/toFile.md @@ -0,0 +1,24 @@ +# FileIO.toFile + +Create a sink which will write incoming `ByteString` s to a given file. + +@ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources) + +@@@ warning + +The `toFile` operator has been deprecated, use @ref:[toPath](./toPath.md) instead. + +@@@ + +@@@div { .group-scala } + +## Signature + +@@signature [FileIO.scala](/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala) { #toFile } + +@@@ + +## Description + +Creates a Sink which writes incoming `ByteString` elements to the given file path. Overwrites existing files by truncating their contents as default. +Materializes a @scala[`Future`] @java[`CompletionStage`] of `IOResult` that will be completed with the size of the file (in bytes) at the streams completion, and a possible exception if IO operation was not completed successfully. diff --git a/akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md b/akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md index b8bbfb2b16..07c4bb1588 100644 --- a/akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md +++ b/akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md @@ -14,4 +14,13 @@ Create a sink which will write incoming `ByteString` s to a given file path. ## Description -TODO: We would welcome help on contributing descriptions and examples, see: https://github.com/akka/akka/issues/25646 +Creates a Sink which writes incoming `ByteString` elements to the given file path. Overwrites existing files by truncating their contents as default. +Materializes a @scala[`Future`] @java[`CompletionStage`] of `IOResult` that will be completed with the size of the file (in bytes) at the streams completion, and a possible exception if IO operation was not completed successfully. + +## Example + +Scala +: @@snip [StreamFileDocSpec.scala](/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala) { #file-sink } + +Java +: @@snip [StreamFileDocTest.java](/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java) { #file-sink } diff --git a/akka-docs/src/main/paradox/stream/operators/index.md b/akka-docs/src/main/paradox/stream/operators/index.md index 370a3df8e5..c67034c23e 100644 --- a/akka-docs/src/main/paradox/stream/operators/index.md +++ b/akka-docs/src/main/paradox/stream/operators/index.md @@ -106,7 +106,9 @@ Sources and sinks for reading and writing files can be found on `FileIO`. | |Operator|Description| |--|--|--| -|FileIO|@ref[fromPath](FileIO/fromPath.md)|Emit the contents of a file.| +|FileIO|@ref[fromFile](FileIO/fromFile.md)|Emits the contents of a file.| +|FileIO|@ref[fromPath](FileIO/fromPath.md)|Emits the contents of a file from the given path.| +|FileIO|@ref[toFile](FileIO/toFile.md)|Create a sink which will write incoming `ByteString` s to a given file.| |FileIO|@ref[toPath](FileIO/toPath.md)|Create a sink which will write incoming `ByteString` s to a given file path.| ## Simple operators @@ -397,7 +399,9 @@ Operators meant for inter-operating between Akka Streams and Actors: * [javaCollectorParallelUnordered](StreamConverters/javaCollectorParallelUnordered.md) * [asJavaStream](StreamConverters/asJavaStream.md) * [fromJavaStream](StreamConverters/fromJavaStream.md) +* [fromFile](FileIO/fromFile.md) * [fromPath](FileIO/fromPath.md) +* [toFile](FileIO/toFile.md) * [toPath](FileIO/toPath.md) * [ask](ActorFlow/ask.md) * [actorRef](ActorSink/actorRef.md) diff --git a/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java b/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java index d92d8fa7e9..86fdce22c4 100644 --- a/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java +++ b/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java @@ -11,10 +11,12 @@ import java.io.IOException; import java.util.concurrent.CompletionStage; import akka.Done; +import akka.NotUsed; import akka.actor.ActorSystem; import akka.stream.ActorAttributes; import akka.stream.javadsl.Sink; import akka.stream.javadsl.FileIO; +import akka.stream.javadsl.Source; import jdocs.AbstractJavaTest; import jdocs.stream.SilenceSystemOut; import akka.testkit.javadsl.TestKit; @@ -48,9 +50,16 @@ public class StreamFileDocTest extends AbstractJavaTest { final SilenceSystemOut.System System = SilenceSystemOut.get(); { - //#file-source - final Path file = Paths.get("example.csv"); - //#file-source + // Using 4 spaces here to align with code in try block below. + //#file-source + final Path file = Paths.get("example.csv"); + //#file-source + } + + { + //#file-sink + final Path file = Paths.get("greeting.txt"); + //#file-sink } @Test @@ -87,5 +96,21 @@ public class StreamFileDocTest extends AbstractJavaTest { } } + @Test + public void demontrateFileIOWriting() throws IOException { + final Path file = Files.createTempFile(getClass().getName(), ".tmp"); + try { + //#file-sink + Sink> fileSink = FileIO.toPath(file); + Source textSource = Source.single("Hello Akka Stream!"); + + CompletionStage ioResult = textSource + .map(ByteString::fromString) + .runWith(fileSink, mat); + //#file-sink + } finally { + Files.delete(file); + } + } } diff --git a/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala b/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala index a5682cfaa1..98a8d8c2e8 100644 --- a/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala +++ b/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala @@ -7,7 +7,7 @@ package docs.stream.io import java.nio.file.{ Files, Paths } import akka.stream._ -import akka.stream.scaladsl.{ FileIO, Sink } +import akka.stream.scaladsl.{ FileIO, Sink, Source } import akka.stream.testkit.Utils._ import akka.util.ByteString import akka.testkit.AkkaSpec @@ -39,6 +39,12 @@ class StreamFileDocSpec extends AkkaSpec(UnboundedMailboxConfig) { //#file-source } + { + //#file-sink + val file = Paths.get("greeting.txt") + //#file-sink + } + "read data from a file" in { //#file-source def handle(b: ByteString): Unit //#file-source @@ -58,4 +64,13 @@ class StreamFileDocSpec extends AkkaSpec(UnboundedMailboxConfig) { .withAttributes(ActorAttributes.dispatcher("custom-blocking-io-dispatcher")) //#custom-dispatcher-code } + + "write data into a file" in { + //#file-sink + val text = Source.single("Hello Akka Stream!") + val result: Future[IOResult] = text + .map(t ⇒ ByteString(t)) + .runWith(FileIO.toPath(file)) + //#file-sink + } } diff --git a/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala b/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala index b8bd06c07c..6dc9fe4220 100644 --- a/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala +++ b/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala @@ -63,7 +63,7 @@ object FileIO { * except the final element, which will be up to `chunkSize` in size. * * You can configure the default dispatcher for this Source by changing the `akka.stream.materializer.blocking-io-dispatcher` or - * set it for a given Source by using [[ActorAttributes]]. + * set it for a given Source by using [[akka.stream.ActorAttributes]]. * * It materializes a [[Future]] of [[IOResult]] containing the number of bytes read from the source file upon completion, * and a possible exception if IO operation was not completed successfully. @@ -122,7 +122,7 @@ object FileIO { * and a possible exception if IO operation was not completed successfully. * * This source is backed by an Actor which will use the dedicated `akka.stream.blocking-io-dispatcher`, - * unless configured otherwise by using [[ActorAttributes]]. + * unless configured otherwise by using [[akka.stream.ActorAttributes]]. * * Accepts as arguments a set of [[java.nio.file.StandardOpenOption]], which will determine * the underlying behavior when writing the file. If [[java.nio.file.StandardOpenOption.SYNC]] is diff --git a/project/StreamOperatorsIndexGenerator.scala b/project/StreamOperatorsIndexGenerator.scala index 70a3e34c00..d2393fcaea 100644 --- a/project/StreamOperatorsIndexGenerator.scala +++ b/project/StreamOperatorsIndexGenerator.scala @@ -106,10 +106,6 @@ object StreamOperatorsIndexGenerator extends AutoPlugin { "foldAsync", "newOnCompleteStage" ), - "FileIO" -> Seq( - "fromFile", - "toFile" - ), "ActorSink" → Seq( "actorRefWithAck" ),