Move (de)compression helpers to akka-stream module #21395 (#21409)

* Move (de)compression helpers to akka-stream #21395

* Move compression and decompression -related classes from
  akka-http-experimental to akka-stream
* Add Compression helper object with functions to create
  decompressing Flows
* Add a short cookbook entry

* =str move compression impl classes into their own directory (and change visibility)

* =str also expose gzip/deflate compression flows

* Fix formatting of plural ByteStrings in cookbook

* =str #21395 make compressor call Deflater.end in postStop to release resources

Also simplified the creation of the flow given a compressor.

* =str #21395 decompressors call Inflater.end in postStop to release resources

* =str #21395 smallish Scaladoc fixes

akka-docs/rst/java/code/docs/stream/javadsl/cookbook/RecipeDecompress.java

@@ -0,0 +1,68 @@
+/**
+ * Copyright (C) 2016 Lightbend Inc. <http://www.lightbend.com/>
+ */
+package docs.stream.javadsl.cookbook;
+
+import akka.NotUsed;
+import akka.actor.ActorSystem;
+import akka.stream.ActorMaterializer;
+import akka.stream.Materializer;
+import akka.stream.javadsl.Compression;
+import akka.stream.javadsl.Sink;
+import akka.stream.javadsl.Source;
+import akka.testkit.JavaTestKit;
+import akka.util.ByteString;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.concurrent.TimeUnit;
+import java.util.zip.GZIPOutputStream;
+
+public class RecipeDecompress extends RecipeTest {
+
+    static ActorSystem system;
+    static Materializer mat;
+
+    @BeforeClass
+    public static void setup() {
+        system = ActorSystem.create("RecipeDecompress");
+        mat = ActorMaterializer.create(system);
+    }
+
+    @AfterClass
+    public static void tearDown() {
+        JavaTestKit.shutdownActorSystem(system);
+        system = null;
+        mat = null;
+    }
+
+    private ByteString gzip(final String s) throws IOException {
+        final ByteArrayOutputStream buf = new ByteArrayOutputStream();
+        final GZIPOutputStream out = new GZIPOutputStream(buf);
+        try {
+            out.write(s.getBytes(StandardCharsets.UTF_8));
+        } finally {
+            out.close();
+        }
+        return ByteString.fromArray(buf.toByteArray());
+    }
+
+    @Test
+    public void parseLines() throws Exception {
+        final Source<ByteString, NotUsed> compressed = Source.single(gzip("Hello World"));
+
+        //#decompress-gzip
+        final Source<String, NotUsed> uncompressed = compressed
+                .via(Compression.gunzip(100))
+                .map(b -> b.utf8String());
+        //#decompress-gzip
+
+        uncompressed.runWith(Sink.head(), mat).toCompletableFuture().get(1, TimeUnit.SECONDS);
+    }
+
+}

akka-docs/rst/java/stream/stream-cookbook.rst

@@ -102,6 +102,17 @@ The :class:`Framing` helper class contains a convenience method to parse message
 
 .. includecode:: ../code/docs/stream/javadsl/cookbook/RecipeParseLines.java#parse-lines
 
+Dealing with compressed data streams
+------------------------------------
+
+**Situation:** A gzipped stream of bytes is given as a stream of ``ByteString`` s, for example from a ``FileIO`` source.
+
+The :class:`Compression` helper class contains convenience methods for decompressing data streams compressed with
+Gzip or Deflate.
+
+.. includecode:: ../code/docs/stream/javadsl/cookbook/RecipeDecompress.java#decompress-gzip
+
+
 Implementing reduce-by-key
 --------------------------