Add support for S3TransferManager TransferListeners

This adds initial support for S3TransferManager TransferListeners. The
motivation and design is consistent as outlined in
aws#2729. It also addresses
some customer asks as mentioned in
aws#37.

Every @SdkPublicApi has been thoroughly documented with its description
and usage instructions where applicable.

Author: Bennett Lynch

core/annotations/src/main/java/software/amazon/awssdk/annotations/Immutable.java

@@ -40,6 +40,8 @@
  * Based on code developed by Brian Goetz and Tim Peierls and concepts
  * published in 'Java Concurrency in Practice' by Brian Goetz, Tim Peierls,
  * Joshua Bloch, Joseph Bowbeer, David Holmes and Doug Lea.
+ * 
+ * @see Mutable
  */
 @Documented
 @Target(ElementType.TYPE)

core/annotations/src/main/java/software/amazon/awssdk/annotations/Mutable.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * The class to which this annotation is applied is explicitly mutable,
+ * meaning that its state is subject to change between calls. Mutable
+ * classes offer no inherent guarantees on thread-safety. Where possible,
+ * classes may be further annotated as either {@link ThreadSafe} or
+ * {@link NotThreadSafe}.
+ * 
+ * @see Immutable
+ */
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.CLASS)
+@SdkProtectedApi
+public @interface Mutable {
+}

services-custom/s3-transfer-manager/src/it/java/software/amazon/awssdk/transfer/s3/ProgressPrintingTransferListener.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.transfer.s3;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.util.Collections;
+
+/**
+ * An example implementation of {@link TransferListener} that prints a progress bar to System.out. This example is referenced to
+ * in the {@link TransferListener} documentation and also used in some {@link S3TransferManager} integration tests
+ */
+public class ProgressPrintingTransferListener implements TransferListener {
+    
+    private final ProgressBar progressBar = new ProgressBar(20);
+
+    @Override
+    public void transferInitiated(Context.TransferInitiated context) {
+        System.out.println("Transfer initiated...");
+        context.progressSnapshot().ratioTransferred().ifPresent(progressBar::update);
+    }
+
+    @Override
+    public void bytesTransferred(Context.BytesTransferred context) {
+        context.progressSnapshot().ratioTransferred().ifPresent(progressBar::update);
+    }
+
+    @Override
+    public void transferComplete(Context.TransferComplete context) {
+        context.progressSnapshot().ratioTransferred().ifPresent(progressBar::update);
+        System.out.println("Transfer complete!");
+    }
+
+    @Override
+    public void transferFailed(Context.TransferFailed context) {
+        System.out.println("Transfer failed.");
+        context.exception().printStackTrace();
+    }
+
+    private static class ProgressBar {
+        private final int maxTicks;
+        private int prevTicks = -1;
+
+        public ProgressBar(int maxTicks) {
+            this.maxTicks = maxTicks;
+        }
+
+        public void update(double ratio) {
+            int ticks = (int) Math.floor(ratio * maxTicks);
+            if (ticks != prevTicks) {
+                System.out.printf("|%s%s| %s%n",
+                                  repeat("=", ticks),
+                                  repeat(" ", maxTicks - ticks),
+                                  round(ratio * 100, 1) + "%");
+                prevTicks = ticks;
+            }
+        }
+
+        private static String repeat(String str, int n) {
+            return String.join("", Collections.nCopies(n, str));
+        }
+
+        private static double round(double value, int places) {
+            BigDecimal bd = BigDecimal.valueOf(value);
+            bd = bd.setScale(places, RoundingMode.HALF_DOWN);
+            return bd.doubleValue();
+        }
+    }
+}

services-custom/s3-transfer-manager/src/it/java/software/amazon/awssdk/transfer/s3/S3TransferManagerDownloadIntegrationTest.java

@@ -31,13 +31,14 @@
 public class S3TransferManagerDownloadIntegrationTest extends S3IntegrationTestBase {
     private static final String BUCKET = temporaryBucketName(S3TransferManagerDownloadIntegrationTest.class);
     private static final String KEY = "key";
+    private static final int OBJ_SIZE = 16 * 1024 * 1024;
     private static S3TransferManager transferManager;
     private static File file;
 
     @BeforeClass
     public static void setup() throws IOException {
         createBucket(BUCKET);
-        file = new RandomTempFile(10_000);
+        file = new RandomTempFile(OBJ_SIZE);
         s3.putObject(PutObjectRequest.builder()
                                      .bucket(BUCKET)
                                      .key(KEY)
@@ -59,7 +60,8 @@ public static void cleanup() {
     public void download_shouldWork() throws IOException {
         Path path = RandomTempFile.randomUncreatedFile().toPath();
         Download download = transferManager.download(b -> b.getObjectRequest(r -> r.bucket(BUCKET).key(KEY))
-                                                           .destination(path));
+                                                           .destination(path)
+                                                           .listeners(new ProgressPrintingTransferListener()));
         CompletedDownload completedDownload = download.completionFuture().join();
         assertThat(Md5Utils.md5AsBase64(path.toFile())).isEqualTo(Md5Utils.md5AsBase64(file));
         assertThat(completedDownload.response().responseMetadata().requestId()).isNotNull();

services-custom/s3-transfer-manager/src/it/java/software/amazon/awssdk/transfer/s3/S3TransferManagerUploadIntegrationTest.java

@@ -30,8 +30,8 @@
 
 public class S3TransferManagerUploadIntegrationTest extends S3IntegrationTestBase {
     private static final String TEST_BUCKET = temporaryBucketName(S3TransferManagerUploadIntegrationTest.class);
-    private static final String TEST_KEY = "8mib_file.dat";
-    private static final int OBJ_SIZE = 8 * 1024 * 1024;
+    private static final String TEST_KEY = "16mib_file.dat";
+    private static final int OBJ_SIZE = 16 * 1024 * 1024;
 
     private static RandomTempFile testFile;
     private static S3TransferManager tm;
@@ -64,6 +64,7 @@ public void upload_fileSentCorrectly() throws IOException {
         Upload upload = tm.upload(UploadRequest.builder()
                                                .putObjectRequest(b -> b.bucket(TEST_BUCKET).key(TEST_KEY))
                                                .source(testFile.toPath())
+                                               .listeners(new ProgressPrintingTransferListener())
                                                .build());
 
         CompletedUpload completedUpload = upload.completionFuture().join();

services-custom/s3-transfer-manager/src/main/java/software/amazon/awssdk/transfer/s3/Context.java

@@ -0,0 +1,116 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.transfer.s3;
+
+import java.util.concurrent.CompletionException;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
+import software.amazon.awssdk.annotations.SdkProtectedApi;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * A wrapper class that groups together the different context objects that are exposed to {@link TransferListener}s.
+ *
+ * @see TransferListener
+ */
+@SdkProtectedApi
+public final class Context {
+    private Context() {
+    }
+
+    /**
+     * A new transfer has been initiated.
+     * <p>
+     * Available context attributes:
+     * <ol>
+     *     <li>{@link Context.TransferInitiated#request()}</li>
+     *     <li>{@link Context.TransferInitiated#progressSnapshot()}</li>
+     * </ol>
+     */
+    @ThreadSafe
+    @SdkPublicApi
+    @SdkPreviewApi
+    public interface TransferInitiated {
+        /**
+         * The {@link TransferRequest} that was submitted to {@link S3TransferManager}, i.e., the {@link UploadRequest} or {@link
+         * DownloadRequest}.
+         */
+        TransferRequest request();
+
+        /**
+         * The immutable {@link TransferProgressSnapshot} for this specific update.
+         */
+        TransferProgressSnapshot progressSnapshot();
+    }
+
+    /**
+     * Additional bytes have been submitted or received.
+     * <p>
+     * Available context attributes:
+     * <ol>
+     *     <li>{@link Context.BytesTransferred#request()}</li>
+     *     <li>{@link Context.BytesTransferred#progressSnapshot()}</li>
+     * </ol>
+     */
+    @ThreadSafe
+    @SdkPublicApi
+    @SdkPreviewApi
+    public interface BytesTransferred extends TransferInitiated {
+    }
+
+    /**
+     * The transfer has completed successfully.
+     * <p>
+     * Available context attributes:
+     * <ol>
+     *     <li>{@link Context.TransferComplete#request()}</li>
+     *     <li>{@link Context.TransferComplete#progressSnapshot()}</li>
+     *     <li>{@link Context.TransferComplete#completedTransfer()}</li>
+     * </ol>
+     */
+    @ThreadSafe
+    @SdkPublicApi
+    @SdkPreviewApi
+    public interface TransferComplete extends BytesTransferred {
+        /**
+         * The completed transfer, i.e., the {@link CompletedUpload} or {@link CompletedDownload}.
+         */
+        CompletedTransfer completedTransfer();
+    }
+
+    /**
+     * The transfer failed.
+     * <p>
+     * Available context attributes:
+     * <ol>
+     *     <li>{@link Context.TransferFailed#request()}</li>
+     *     <li>{@link Context.TransferFailed#progressSnapshot()}</li>
+     *     <li>{@link Context.TransferFailed#exception()}</li>
+     * </ol>
+     */
+    @ThreadSafe
+    @SdkPublicApi
+    @SdkPreviewApi
+    public interface TransferFailed extends TransferInitiated {
+        /**
+         * The exception associated with the failed transfer.
+         * <p>
+         * Note that this would be the <i>cause</i>> of a {@link CompletionException}, and not a {@link CompletionException}
+         * itself.
+         */
+        Throwable exception();
+    }
+}