Address remaining feedback

Author: zoewangg

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

@@ -17,18 +17,95 @@
 
 import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.services.s3.S3AsyncClient;
 import software.amazon.awssdk.services.s3.model.GetObjectResponse;
+import software.amazon.awssdk.utils.Validate;
 
 /**
- * A completed download transfer.
+ * Represents a completed download transfer from Amazon S3. It can be used to track
+ * the underlying {@link GetObjectResponse}
+ *
+ * @see S3TransferManager#download(DownloadRequest)
  */
 @SdkPublicApi
 @SdkPreviewApi
-public interface CompletedDownload extends CompletedTransfer {
+public final class CompletedDownload implements CompletedTransfer {
+    private final GetObjectResponse response;
+
+    private CompletedDownload(DefaultBuilder builder) {
+        this.response = Validate.paramNotNull(builder.response, "response");
+    }
 
     /**
      * Returns the API response from the {@link S3TransferManager#download(DownloadRequest)}
      * @return the response
      */
-    GetObjectResponse response();
+    public GetObjectResponse response() {
+        return response;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+
+        CompletedDownload that = (CompletedDownload) o;
+
+        return response.equals(that.response);
+    }
+
+    @Override
+    public int hashCode() {
+        return response.hashCode();
+    }
+
+    public static Builder builder() {
+        return new DefaultBuilder();
+    }
+
+    public interface Builder {
+        /**
+         * Specify the {@link GetObjectResponse} from {@link S3AsyncClient#getObject}
+         *
+         * @param response the response
+         * @return This builder for method chaining.
+         */
+        Builder response(GetObjectResponse response);
+
+        /**
+         * Builds a {@link CompletedUpload} based on the properties supplied to this builder
+         * @return An initialized {@link CompletedUpload}
+         */
+        CompletedDownload build();
+    }
+
+    private static final class DefaultBuilder implements Builder {
+        private GetObjectResponse response;
+
+        private DefaultBuilder() {
+        }
+
+        @Override
+        public Builder response(GetObjectResponse response) {
+            this.response = response;
+            return this;
+        }
+
+        public void setResponse(GetObjectResponse response) {
+            response(response);
+        }
+
+        public GetObjectResponse getResponse() {
+            return response;
+        }
+
+        @Override
+        public CompletedDownload build() {
+            return new CompletedDownload(this);
+        }
+    }
 }

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

@@ -17,18 +17,98 @@
 
 import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.services.s3.S3AsyncClient;
 import software.amazon.awssdk.services.s3.model.PutObjectResponse;
+import software.amazon.awssdk.utils.ToString;
+import software.amazon.awssdk.utils.Validate;
 
 /**
- * A completed upload transfer.
+ * Represents a completed upload transfer to Amazon S3. It can be used to track
+ * the underlying {@link PutObjectResponse}
+ *
+ * @see S3TransferManager#upload(UploadRequest)
  */
 @SdkPublicApi
 @SdkPreviewApi
-public interface CompletedUpload extends CompletedTransfer {
+public final class CompletedUpload implements CompletedTransfer {
+    private final PutObjectResponse response;
+
+    private CompletedUpload(DefaultBuilder builder) {
+        this.response = Validate.paramNotNull(builder.response, "response");
+    }
 
     /**
      * Returns the API response from the {@link S3TransferManager#upload(UploadRequest)}
      * @return the response
      */
-    PutObjectResponse response();
+    public PutObjectResponse response() {
+        return response;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+
+        CompletedUpload that = (CompletedUpload) o;
+
+        return response.equals(that.response);
+    }
+
+    @Override
+    public int hashCode() {
+        return response.hashCode();
+    }
+
+    @Override
+    public String toString() {
+        return ToString.builder("CompletedUpload")
+                       .add("response", response)
+                       .build();
+    }
+
+    /**
+     * Creates a default builder for {@link CompletedUpload}.
+     */
+    public static Builder builder() {
+        return new DefaultBuilder();
+    }
+
+    public interface Builder {
+        /**
+         * Specify the {@link PutObjectResponse} from {@link S3AsyncClient#putObject}
+         *
+         * @param response the response
+         * @return This builder for method chaining.
+         */
+        Builder response(PutObjectResponse response);
+
+        /**
+         * Builds a {@link CompletedUpload} based on the properties supplied to this builder
+         * @return An initialized {@link CompletedUpload}
+         */
+        CompletedUpload build();
+    }
+
+    private static class DefaultBuilder implements Builder {
+        private PutObjectResponse response;
+
+        private DefaultBuilder() {
+        }
+
+        @Override
+        public Builder response(PutObjectResponse response) {
+            this.response = response;
+            return this;
+        }
+
+        @Override
+        public CompletedUpload build() {
+            return new CompletedUpload(this);
+        }
+    }
 }

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

@@ -44,14 +44,31 @@ private CompletedUploadDirectory(DefaultBuilder builder) {
      * An immutable collection of failed uploads with error details, request metadata about each file that is failed to
      * upload.
      *
+     * <p>
+     * Failed single file uploads can be retried by calling {@link S3TransferManager#upload(UploadRequest)}
+     *
+     * <pre>
+     * {@code
+     * // Retrying failed uploads if the exception is retryable
+     * List<CompletableFuture<CompletedUpload>> futures =
+     *     completedUploadDirectory.failedUploads()
+     *                             .stream()
+     *                             .filter(failedSingleFileUpload -> isRetryable(failedSingleFileUpload.exception()))
+     *                             .map(failedSingleFileUpload ->
+     *                                  tm.upload(failedSingleFileUpload.request()).completionFuture())
+     *                             .collect(Collectors.toList());
+     * CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
+     * }
+     * </pre>
+     *
      * @return a list of failed uploads
      */
     public Collection<FailedSingleFileUpload> failedUploads() {
         return failedUploads;
     }
 
     /**
-     * Creates a default builder for {@link CompletedUpload}.
+     * Creates a default builder for {@link CompletedUploadDirectory}.
      */
     public static Builder builder() {
         return new DefaultBuilder();

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

@@ -198,7 +198,7 @@ default Upload upload(Consumer<UploadRequest.Builder> request) {
      * // Print out the failed uploads
      * completedUploadDirectory.failedUploads().forEach(System.out::println);
      *
-     * // Retrying failed uploads if the exceptions are retryable
+     * // Retrying failed uploads if the exception is retryable
      * List<CompletableFuture<CompletedUpload>> futures =
      *     completedUploadDirectory.failedUploads()
      *                             .stream()
@@ -207,6 +207,7 @@ default Upload upload(Consumer<UploadRequest.Builder> request) {
      *                                  tm.upload(failedSingleFileUpload.request()).completionFuture())
      *                             .collect(Collectors.toList());
      * CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
+     * }
      * </pre>
      *
      * @param uploadDirectoryRequest the upload directory request
@@ -252,7 +253,7 @@ default UploadDirectoryTransfer uploadDirectory(UploadDirectoryRequest uploadDir
      * // Print out the failed uploads
      * completedUploadDirectory.failedUploads().forEach(System.out::println);
      *
-     * // Retrying failed uploads if the exceptions are retryable
+     * // Retrying failed uploads if the exception is retryable
      * List<CompletableFuture<CompletedUpload>> futures =
      *     completedUploadDirectory.failedUploads()
      *                             .stream()
@@ -261,6 +262,7 @@ default UploadDirectoryTransfer uploadDirectory(UploadDirectoryRequest uploadDir
      *                                  tm.upload(failedSingleFileUpload.request()).completionFuture())
      *                             .collect(Collectors.toList());
      * CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
+     * }
      * </pre>
      * @param requestBuilder the upload directory request builder
      * @see #uploadDirectory(UploadDirectoryRequest)
@@ -342,6 +344,7 @@ default Builder s3ClientConfiguration(Consumer<S3ClientConfiguration.Builder> co
          * @see #transferConfiguration(S3TransferManagerOverrideConfiguration)
          */
         default Builder transferConfiguration(Consumer<S3TransferManagerOverrideConfiguration.Builder> configuration) {
+            Validate.paramNotNull(configuration, "configuration");
             S3TransferManagerOverrideConfiguration.Builder builder = S3TransferManagerOverrideConfiguration.builder();
             configuration.accept(builder);
             transferConfiguration(builder.build());

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

@@ -102,10 +102,15 @@ public static Builder builder() {
     public interface Builder extends CopyableBuilder<Builder, S3TransferManagerOverrideConfiguration> {
 
         /**
-         * Specify the executor that will be used in {@link S3TransferManager} to offload
-         * execution
+         * Specify the executor that {@link S3TransferManager} will use to execute
+         * the request that might take some time to process before handing it off to the underlying S3 async client such as
+         * visiting file tree in {@link S3TransferManager#uploadDirectory(UploadDirectoryRequest)} operation.
          *
-         * @param executor the async configuration
+         * <p>
+         * <b>This executor must be shut down by the user when it is ready to be disposed. The SDK will not close the executor
+         * when the s3 transfer manager is closed.</b>
+         *
+         * @param executor the executor to use
          * @return this builder for method chaining.
          */
         Builder executor(Executor executor);

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

@@ -54,6 +54,7 @@ public UploadDirectoryRequest(DefaultBuilder builder) {
      * The source directory to upload
      *
      * @return the source directory
+     * @see Builder#sourceDirectory(Path)
      */
     public Path sourceDirectory() {
         return sourceDirectory;
@@ -63,24 +64,31 @@ public Path sourceDirectory() {
      * The name of the bucket to upload objects to.
      *
      * @return bucket name
+     * @see Builder#bucket(String)
      */
     public String bucket() {
         return bucket;
     }
 
     /**
      * @return the optional key prefix
+     * @see Builder#prefix(String)
      */
     public Optional<String> prefix() {
         return Optional.ofNullable(prefix);
     }
 
+    /**
+     * @return the optional delimiter
+     * @see Builder#delimiter(String)
+     */
     public Optional<String> delimiter() {
         return Optional.ofNullable(delimiter);
     }
 
     /**
      * @return the optional override configuration
+     * @see Builder#overrideConfiguration(UploadDirectoryOverrideConfiguration)
      */
     public Optional<UploadDirectoryOverrideConfiguration> overrideConfiguration() {
         return Optional.ofNullable(overrideConfiguration);
@@ -134,10 +142,16 @@ public int hashCode() {
     public interface Builder extends CopyableBuilder<Builder, UploadDirectoryRequest> {
 
         /**
-         * Specify the source directory to upload
+         * Specify the source directory to upload. The source directory must exist.
+         * Fle wildcards are not supported and treated literally. Hidden files/directories are visited.
+         *
+         * <p>
+         * Note that the current user must have read access to all directories and files,
+         * otherwise {@link SecurityException} will be thrown.
          *
          * @param sourceDirectory the source directory
          * @return This builder for method chaining.
+         * @see UploadDirectoryOverrideConfiguration
          */
         Builder sourceDirectory(Path sourceDirectory);
 

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

@@ -32,6 +32,7 @@
 
 /**
  * Upload an object to S3 using {@link S3TransferManager}.
+ * @see S3TransferManager#upload(UploadRequest)
  */
 @SdkPublicApi
 @SdkPreviewApi