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/scala/code/docs/stream/cookbook/RecipeDecompress.scala

@@ -0,0 +1,40 @@
+/**
+ * Copyright (C) 2016 Lightbend Inc. <http://www.lightbend.com/>
+ */
+package docs.stream.cookbook
+
+import java.io.ByteArrayOutputStream
+import java.nio.charset.StandardCharsets
+import java.util.zip.GZIPOutputStream
+
+import akka.stream.impl.io.compression.GzipCompressor
+import akka.stream.scaladsl.Sink
+import akka.stream.scaladsl.Source
+import akka.util.ByteString
+
+import scala.annotation.tailrec
+import scala.concurrent.Await
+import scala.concurrent.duration._
+
+class RecipeDecompress extends RecipeSpec {
+  def gzip(s: String): ByteString = {
+    val buf = new ByteArrayOutputStream()
+    val out = new GZIPOutputStream(buf)
+    try out.write(s.getBytes(StandardCharsets.UTF_8)) finally out.close()
+    ByteString(buf.toByteArray)
+  }
+
+  "Recipe for decompressing a Gzip stream" must {
+    "work" in {
+      val compressed = Source.single(gzip("Hello World"))
+
+      //#decompress-gzip
+      import akka.stream.scaladsl.Compression
+      val uncompressed = compressed.via(Compression.gunzip())
+        .map(_.utf8String)
+      //#decompress-gzip
+
+      Await.result(uncompressed.runWith(Sink.head), 3.seconds) should be("Hello World")
+    }
+  }
+}

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

@@ -100,6 +100,16 @@ The :class:`Framing` helper object contains a convenience method to parse messag
 
 .. includecode:: ../code/docs/stream/cookbook/RecipeParseLines.scala#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 object contains convenience methods for decompressing data streams compressed with
+Gzip or Deflate.
+
+.. includecode:: ../code/docs/stream/cookbook/RecipeDecompress.scala#decompress-gzip
+
 Implementing reduce-by-key
 --------------------------