Merge pull request #243 from svezfaz/103-S3-documentation

S3 - add documentation #103

docs/src/main/paradox/connectors.md

@@ -13,6 +13,7 @@
 * [HBase Connectors](hbase.md)
 * [JMS Connectors](jms.md)
 * [MQTT Connector](mqtt.md)
+* [S3 Connector](s3.md)
 * [Server-sent Events (SSE)](sse.md)
 
 @@@

docs/src/main/paradox/s3.md

@@ -0,0 +1,82 @@
+# S3 Connector
+
+The S3 connector provides Akka Stream sources and sinks to connect to [Amazon S3](https://aws.amazon.com/s3/).
+S3 stands for Simple Storage Service and is an object storage service with a web service interface.
+
+## Artifacts
+
+sbt
+:   @@@vars
+    ```scala
+    libraryDependencies += "com.lightbend.akka" %% "akka-stream-alpakka-s3" % "$version$"
+    ```
+    @@@
+
+Maven
+:   @@@vars
+    ```xml
+    <dependency>
+      <groupId>com.lightbend.akka</groupId>
+      <artifactId>akka-stream-alpakka-s3_$scala.binaryVersion$</artifactId>
+      <version>$version$</version>
+    </dependency>
+    ```
+    @@@
+
+Gradle
+:   @@@vars
+    ```gradle
+    dependencies {
+      compile group: "com.lightbend.akka", name: "akka-stream-alpakka-s3_$scala.binaryVersion$", version: "$version$"
+    }
+    ```
+    @@@
+
+## Usage
+
+### Set up your S3 clients
+
+The S3 connector can be configured within your `application.conf` file.
+
+Configuration
+: @@snip (../../../../s3/src/main/resources/reference.conf)
+
+### Create an S3 client
+
+Scala
+: @@snip (../../../../s3/src/test/scala/akka/stream/alpakka/s3/scaladsl/S3ClientIntegrationSpec.scala) { #client }
+
+Java
+: @@snip (../../../../s3/src/test/java/akka/stream/alpakka/s3/javadsl/S3ClientTest.java) { #client }
+
+### Storing a file in S3
+
+Scala
+: @@snip (../../../../s3/src/test/scala/akka/stream/alpakka/s3/scaladsl/S3SinkSpec.scala) { #upload }
+
+Java
+: @@snip (../../../../s3/src/test/java/akka/stream/alpakka/s3/javadsl/S3ClientTest.java) { #upload }
+
+### Downloading a file from S3
+
+Scala
+: @@snip (../../../../s3/src/test/scala/akka/stream/alpakka/s3/scaladsl/S3SourceSpec.scala) { #download }
+
+Java
+: @@snip (../../../../s3/src/test/java/akka/stream/alpakka/s3/javadsl/S3ClientTest.java) { #download }
+
+### Running the example code
+
+The code in this guide is part of runnable tests of this project. You are welcome to edit the code and run it in sbt.
+
+Scala
+:   ```
+    sbt
+    > s3/test
+    ```
+
+Java
+:   ```
+    sbt
+    > s3/test
+    ```

s3/src/main/resources/reference.conf

@@ -5,14 +5,14 @@ akka.stream.alpakka.s3 {
   # location for temporary files, if buffer is set to "disk". If empty, uses the standard java temp path.
   disk-buffer-path = ""
 
-  debug-logging = false
-
   proxy {
-    # Hostname of the proxy. If undefined ("") proxy is not enabled.
+    # hostname of the proxy. If undefined ("") proxy is not enabled.
     host = ""
     port = 8000
   }
 
+  # default values for AWS configuration. If credentials and/or region are not specified when creating S3Client,
+  # these values will be used.
   aws {
     access-key-id = ""
     secret-access-key = ""

s3/src/main/scala/akka/stream/alpakka/s3/S3Exception.scala

@@ -3,7 +3,7 @@
  */
 package akka.stream.alpakka.s3
 
-import scala.xml.{Elem, NodeSeq, XML}
+import scala.xml.{Elem, XML}
 
 class S3Exception(val code: String, val message: String, val requestID: String, val hostId: String)
     extends RuntimeException(message) {

s3/src/main/scala/akka/stream/alpakka/s3/S3Settings.scala

@@ -11,13 +11,12 @@ final case class Proxy(host: String, port: Int)
 
 final class S3Settings(val bufferType: BufferType,
                        val diskBufferPath: String,
-                       val debugLogging: Boolean,
                        val proxy: Option[Proxy],
                        val awsCredentials: AWSCredentials,
                        val s3Region: String) {
 
   override def toString: String =
-    s"S3Settings($bufferType,$diskBufferPath,$debugLogging,$proxy,$awsCredentials,$s3Region)"
+    s"S3Settings($bufferType,$diskBufferPath,$proxy,$awsCredentials,$s3Region)"
 }
 
 sealed trait BufferType
@@ -44,7 +43,6 @@ object S3Settings {
       case _ => throw new IllegalArgumentException("Buffer type must be 'memory' or 'disk'")
     },
     diskBufferPath = config.getString("disk-buffer-path"),
-    debugLogging = config.getBoolean("debug-logging"),
     proxy = {
       if (config.getString("proxy.host") != "")
         Some(Proxy(config.getString("proxy.host"), config.getInt("proxy.port")))

s3/src/test/java/akka/stream/alpakka/s3/javadsl/S3ClientTest.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2016-2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+package akka.stream.alpakka.s3.javadsl;
+
+import akka.NotUsed;
+import akka.actor.ActorSystem;
+import akka.http.javadsl.model.Uri;
+import akka.stream.ActorMaterializer;
+import akka.stream.Materializer;
+import akka.stream.alpakka.s3.auth.AWSCredentials;
+import akka.stream.alpakka.s3.auth.BasicCredentials;
+import akka.stream.alpakka.s3.scaladsl.S3WireMockBase;
+import akka.stream.javadsl.Sink;
+import akka.stream.javadsl.Source;
+import akka.util.ByteString;
+import org.junit.Test;
+
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.TimeUnit;
+
+import static org.junit.Assert.assertEquals;
+
+public class S3ClientTest extends S3WireMockBase {
+
+    final Materializer materializer = ActorMaterializer.create(system());
+
+    //#client
+    final AWSCredentials credentials = new BasicCredentials("my-AWS-access-key-ID", "my-AWS-password");
+    final S3Client client = new S3Client(credentials, "us-east-1", system(), materializer);
+    //#client
+
+    @Test
+    public void multipartUpload() throws Exception {
+
+        mockUpload();
+
+        //#upload
+        final Sink<ByteString, CompletionStage<MultipartUploadResult>> sink = client.multipartUpload(bucket(), bucketKey());
+        //#upload
+
+        final CompletionStage<MultipartUploadResult> resultCompletionStage =
+                Source.single(ByteString.fromString(body())).runWith(sink, materializer);
+
+        MultipartUploadResult result = resultCompletionStage.toCompletableFuture().get(5, TimeUnit.SECONDS);
+
+        assertEquals(new MultipartUploadResult(Uri.create(url()), bucket(), bucketKey(), etag()), result);
+    }
+
+    @Test
+    public void download() throws Exception {
+
+        mockDownload();
+
+        //#download
+        final Source<ByteString, NotUsed> source = client.download(bucket(), bucketKey());
+        //#download
+
+        final CompletionStage<String> resultCompletionStage =
+                source.map(ByteString::utf8String).runWith(Sink.head(), materializer);
+
+        String result = resultCompletionStage.toCompletableFuture().get(5, TimeUnit.SECONDS);
+
+        assertEquals(body(), result);
+    }
+}