Update Javadocs

Author: zoewangg

services-custom/s3-transfer-manager/README.md

@@ -26,7 +26,7 @@ You can instantiate the transfer manager easily using the default settings
 
 ```java
 
-S3TranfserManager tranferManager = S3TransferManager.create();
+S3TransferManager transferManager = S3TransferManager.create();
 
 ```
 

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

@@ -15,18 +15,19 @@
 
 package software.amazon.awssdk.transfer.s3;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.services.s3.model.GetObjectResponse;
-import software.amazon.awssdk.transfer.s3.internal.S3CrtAsyncClient;
 
 /**
  * A completed download transfer.
  */
 @SdkPublicApi
+@SdkPreviewApi
 public interface CompletedDownload extends CompletedTransfer {
 
     /**
-     * Returns the API response from the {@link S3CrtAsyncClient#getObject}
+     * Returns the API response from the {@link S3TransferManager#download(DownloadRequest)}
      * @return the response
      */
     GetObjectResponse response();

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

@@ -15,11 +15,13 @@
 
 package software.amazon.awssdk.transfer.s3;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 
 /**
  * A completed transfer.
  */
 @SdkPublicApi
+@SdkPreviewApi
 public interface CompletedTransfer {
 }

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

@@ -15,24 +15,20 @@
 
 package software.amazon.awssdk.transfer.s3;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.services.s3.model.PutObjectResponse;
-import software.amazon.awssdk.transfer.s3.internal.DefaultCompletedUpload;
 
 /**
  * A completed upload transfer.
  */
 @SdkPublicApi
+@SdkPreviewApi
 public interface CompletedUpload extends CompletedTransfer {
-    PutObjectResponse response();
-
-    static Builder builder() {
-        return new DefaultCompletedUpload.BuilderImpl();
-    }
 
-    interface Builder {
-        Builder response(PutObjectResponse response);
-
-        CompletedUpload build();
-    }
+    /**
+     * Returns the API response from the {@link S3TransferManager#upload(UploadRequest)}
+     * @return the response
+     */
+    PutObjectResponse response();
 }

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

@@ -16,13 +16,16 @@
 package software.amazon.awssdk.transfer.s3;
 
 import java.util.concurrent.CompletableFuture;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 
 /**
  * A download transfer of a single object from S3.
  */
 @SdkPublicApi
+@SdkPreviewApi
 public interface Download extends Transfer {
+
     @Override
     CompletableFuture<CompletedDownload> completionFuture();
 }

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

@@ -19,6 +19,7 @@
 import java.util.Objects;
 import java.util.function.Consumer;
 import software.amazon.awssdk.annotations.NotThreadSafe;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.services.s3.model.GetObjectRequest;
 import software.amazon.awssdk.utils.Validate;
@@ -29,6 +30,7 @@
  * Request object to download an object from S3 using the Transfer Manager.
  */
 @SdkPublicApi
+@SdkPreviewApi
 public final class DownloadRequest implements TransferRequest, ToCopyableBuilder<DownloadRequest.Builder, DownloadRequest> {
     private final Path destination;
     private final GetObjectRequest getObjectRequest;
@@ -115,14 +117,20 @@ public interface Builder extends TransferRequest.Builder<DownloadRequest, Builde
          *
          * @param getObjectRequest the getObject request
          * @return a reference to this object so that method calls can be chained together.
+         * @see #getObjectRequest(Consumer)
          */
         Builder getObjectRequest(GetObjectRequest getObjectRequest);
 
         /**
          * The {@link GetObjectRequest} request that should be used for the download
          *
+         * <p>
+         * This is a convenience method that creates an instance of the {@link GetObjectRequest} builder avoiding the
+         * need to create one manually via {@link GetObjectRequest#builder()}.
+         *
          * @param getObjectRequestBuilder the getObject request
          * @return a reference to this object so that method calls can be chained together.
+         * @see #getObjectRequest(GetObjectRequest)
          */
         default Builder getObjectRequest(Consumer<GetObjectRequest.Builder> getObjectRequestBuilder) {
             GetObjectRequest request = GetObjectRequest.builder()
@@ -132,7 +140,6 @@ default Builder getObjectRequest(Consumer<GetObjectRequest.Builder> getObjectReq
             return this;
         }
 
-
         /**
          * @return The built request.
          */

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

@@ -26,7 +26,8 @@
 import software.amazon.awssdk.utils.builder.ToCopyableBuilder;
 
 /**
- * Configuration values for which the TransferManager already provides sensible defaults. All values are optional
+ * Optional Configurations for the underlying S3 client for which the TransferManager already provides
+ * sensible defaults.
  *
  * <p>Use {@link #builder()} to create a set of options.</p>
  */
@@ -124,15 +125,35 @@ public int hashCode() {
         return result;
     }
 
+    /**
+     * Creates a default builder for {@link S3ClientConfiguration}.
+     */
     public static Builder builder() {
         return new DefaultBuilder();
     }
 
+    /**
+     * The builder definition for a {@link S3ClientConfiguration}.
+     */
     public interface Builder extends CopyableBuilder<Builder, S3ClientConfiguration>  {
 
         /**
          * Configure the credentials that should be used to authenticate with S3.
          *
+         * <p>The default provider will attempt to identify the credentials automatically using the following checks:
+         * <ol>
+         *   <li>Java System Properties - <code>aws.accessKeyId</code> and <code>aws.secretKey</code></li>
+         *   <li>Environment Variables - <code>AWS_ACCESS_KEY_ID</code> and <code>AWS_SECRET_ACCESS_KEY</code></li>
+         *   <li>Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI</li>
+         *   <li>Credentials delivered through the Amazon EC2 container service if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
+         *   environment variable is set and security manager has permission to access the variable.</li>
+         *   <li>Instance profile credentials delivered through the Amazon EC2 metadata service</li>
+         * </ol>
+         *
+         * <p>If the credentials are not found in any of the locations above, an exception will be thrown at {@link #build()}
+         * time.
+         * </p>
+         *
          * @param credentialsProvider the credentials to use
          * @return This builder for method chaining.
          */
@@ -169,21 +190,30 @@ public interface Builder extends CopyableBuilder<Builder, S3ClientConfiguration>
 
         /**
          * The target throughput for transfer requests. Higher value means more S3 connections
-         * will be opened.
+         * will be opened. Whether the transfer manager can achieve the configured target throughput depends
+         * on various factors such as the network bandwidth of the environment and the configured {@link #maxConcurrency}.
          *
          * <p>
          * By default, it is 5Gbps
          *
          * @param targetThroughputInGbps the target throughput in Gbps
          * @return this builder for method chaining.
+         * @see #maxConcurrency(Integer)
          */
         Builder targetThroughputInGbps(Double targetThroughputInGbps);
 
         /**
-         * Specifies the maximum number of concurrent Amazon S3 transfer requests that can run at the same time.
+         * Specifies the maximum number of S3 connections that should be established during
+         * a transfer.
+         *
+         * <p>
+         * If not provided, the TransferManager will calculate the optional number of connections
+         * based on {@link #targetThroughputInGbps}. If the value is too low, the S3TransferManager
+         * might not achieve the specified target throughput.
          *
          * @param maxConcurrency the max number of concurrent requests
          * @return this builder for method chaining.
+         * @see #targetThroughputInGbps(Double)
          */
         Builder maxConcurrency(Integer maxConcurrency);
     }