docs: Javadocs for TransferManager interface and ParallelUploadConfig (#2094)

* docs: Javadocs for TransferManager interface and ParallelUploadConfig

Author: sydney-munro

google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelDownloadConfig.java

@@ -28,6 +28,11 @@
 import java.util.Objects;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * Configuration for performing Parallel Downloads with {@link TransferManager}.
+ *
+ * @see Builder
+ */
 @BetaApi
 public final class ParallelDownloadConfig {
 
@@ -48,26 +53,41 @@ private ParallelDownloadConfig(
   }
 
   /**
-   * A common prefix that is removed from downloaded object's name before written to the filesystem
+   * A common prefix removed from an object's name before being written to the filesystem.
+   *
+   * @see Builder#setStripPrefix(String)
    */
   @BetaApi
   public @NonNull String getStripPrefix() {
     return stripPrefix;
   }
 
-  /** The base directory in which all objects will be placed when downloaded. */
+  /**
+   * The base directory in which all objects will be placed when downloaded.
+   *
+   * @see Builder#setDownloadDirectory(Path)
+   */
   @BetaApi
   public @NonNull Path getDownloadDirectory() {
     return downloadDirectory;
   }
 
-  /** The bucket objects are being downloaded from */
+  /**
+   * The bucket objects are being downloaded from.
+   *
+   * @see Builder#setBucketName(String)
+   */
   @BetaApi
   public @NonNull String getBucketName() {
     return bucketName;
   }
 
-  /** A list of common BlobSourceOptions that are used for each download request */
+  /**
+   * A list of common BlobSourceOptions that are used for each download request. Note this list of
+   * options will be applied to every single request.
+   *
+   * @see Builder#setOptionsPerRequest(List)
+   */
   @BetaApi
   public @NonNull List<BlobSourceOption> getOptionsPerRequest() {
     return optionsPerRequest;
@@ -103,6 +123,11 @@ public String toString() {
         .toString();
   }
 
+  /**
+   * Builds an instance of ParallelDownloadConfig.
+   *
+   * @see ParallelDownloadConfig
+   */
   @BetaApi
   public static Builder newBuilder() {
     return new Builder();
@@ -123,30 +148,61 @@ private Builder() {
       this.optionsPerRequest = ImmutableList.of();
     }
 
+    /**
+     * Sets the value for stripPrefix. This string will be removed from the beginning of all object
+     * names before they are written to the filesystem.
+     *
+     * @return the builder instance with the value for stripPrefix modified.
+     * @see ParallelDownloadConfig#getStripPrefix()
+     */
     @BetaApi
     public Builder setStripPrefix(String stripPrefix) {
       this.stripPrefix = stripPrefix;
       return this;
     }
 
+    /**
+     * Sets the base directory on the filesystem that all objects will be written to.
+     *
+     * @return the builder instance with the value for downloadDirectory modified.
+     * @see ParallelDownloadConfig#getDownloadDirectory()
+     */
     @BetaApi
     public Builder setDownloadDirectory(Path downloadDirectory) {
       this.downloadDirectory = downloadDirectory;
       return this;
     }
 
+    /**
+     * Sets the bucketName that Transfer Manager will download from. This field is required.
+     *
+     * @return the builder instance with the value for bucketName modified.
+     * @see ParallelDownloadConfig#getBucketName()
+     */
     @BetaApi
     public Builder setBucketName(String bucketName) {
       this.bucketName = bucketName;
       return this;
     }
 
+    /**
+     * Sets the BlobSourceOptions that will be applied to each download request. Note these options
+     * will be applied to every single download request.
+     *
+     * @return the builder instance with the value for OptionsPerRequest modified.
+     * @see ParallelDownloadConfig#getOptionsPerRequest()
+     */
     @BetaApi
     public Builder setOptionsPerRequest(List<BlobSourceOption> optionsPerRequest) {
       this.optionsPerRequest = ImmutableList.copyOf(optionsPerRequest);
       return this;
     }
 
+    /**
+     * Creates a ParallelDownloadConfig object.
+     *
+     * @return {@link ParallelDownloadConfig}
+     */
     @BetaApi
     public ParallelDownloadConfig build() {
       checkNotNull(bucketName);

google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelUploadConfig.java

@@ -19,62 +19,74 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import com.google.api.core.BetaApi;
-import com.google.cloud.storage.Storage.BlobTargetOption;
 import com.google.cloud.storage.Storage.BlobWriteOption;
 import com.google.common.base.MoreObjects;
 import com.google.common.collect.ImmutableList;
 import java.util.List;
 import java.util.Objects;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * Configuration for performing Parallel Uploads with {@link TransferManager}.
+ *
+ * @see Builder
+ */
 @BetaApi
 public final class ParallelUploadConfig {
 
   private final boolean skipIfExists;
   @NonNull private final String prefix;
   @NonNull private final String bucketName;
-  @NonNull private final List<BlobTargetOption> targetOptsPerRequest;
 
   @NonNull private final List<BlobWriteOption> writeOptsPerRequest;
 
   private ParallelUploadConfig(
       boolean skipIfExists,
       @NonNull String prefix,
       @NonNull String bucketName,
-      @NonNull List<BlobTargetOption> targetOptsPerRequest,
       @NonNull List<BlobWriteOption> writeOptsPerRequest) {
     this.skipIfExists = skipIfExists;
     this.prefix = prefix;
     this.bucketName = bucketName;
-    this.targetOptsPerRequest = targetOptsPerRequest;
     this.writeOptsPerRequest = applySkipIfExists(skipIfExists, writeOptsPerRequest);
   }
 
-  /** If a corresponding object already exists skip uploading the object */
+  /**
+   * If set Transfer Manager will skip uploading an object if it already exists, equivalent to
+   * providing {@link BlobWriteOption#doesNotExist()} in {@link #getWriteOptsPerRequest()}
+   *
+   * @see Builder#setSkipIfExists(boolean)
+   */
   @BetaApi
   public boolean isSkipIfExists() {
     return skipIfExists;
   }
 
-  /** A common prefix that will be applied to all object paths in the destination bucket */
+  /**
+   * A common prefix that will be applied to all object paths in the destination bucket
+   *
+   * @see Builder#setPrefix(String)
+   */
   @BetaApi
   public @NonNull String getPrefix() {
     return prefix;
   }
 
-  /** The bucket objects are being uploaded from */
+  /**
+   * The bucket objects are being uploaded from
+   *
+   * @see Builder#setBucketName(String)
+   */
   @BetaApi
   public @NonNull String getBucketName() {
     return bucketName;
   }
 
-  /** A list of common BlobTargetOptions that are used for each upload request */
-  @BetaApi
-  public @NonNull List<BlobTargetOption> getTargetOptsPerRequest() {
-    return targetOptsPerRequest;
-  }
-
-  /** A list of common BlobWriteOptions that are used for each upload request */
+  /**
+   * A list of common BlobWriteOptions, note these options will be applied to each upload request.
+   *
+   * @see Builder#setWriteOptsPerRequest(List)
+   */
   @BetaApi
   public @NonNull List<BlobWriteOption> getWriteOptsPerRequest() {
     return writeOptsPerRequest;
@@ -92,12 +104,12 @@ public boolean equals(Object o) {
     return skipIfExists == that.skipIfExists
         && prefix.equals(that.prefix)
         && bucketName.equals(that.bucketName)
-        && targetOptsPerRequest.equals(that.targetOptsPerRequest);
+        && writeOptsPerRequest.equals(that.writeOptsPerRequest);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(skipIfExists, prefix, bucketName, targetOptsPerRequest);
+    return Objects.hash(skipIfExists, prefix, bucketName, writeOptsPerRequest);
   }
 
   @Override
@@ -106,7 +118,7 @@ public String toString() {
         .add("skipIfExists", skipIfExists)
         .add("prefix", prefix)
         .add("bucketName", bucketName)
-        .add("optionsPerRequest", targetOptsPerRequest)
+        .add("writeOptsPerRequest", writeOptsPerRequest)
         .toString();
   }
 
@@ -124,61 +136,86 @@ private static List<BlobWriteOption> applySkipIfExists(
     return writeOptsPerRequest;
   }
 
+  /**
+   * Builds an instance of ParallelUploadConfig.
+   *
+   * @see ParallelUploadConfig
+   */
   @BetaApi
   public static final class Builder {
 
     private boolean skipIfExists;
     private @NonNull String prefix;
     private @NonNull String bucketName;
-    private @NonNull List<BlobTargetOption> optionsPerRequest;
-
     private @NonNull List<BlobWriteOption> writeOptsPerRequest;
 
     private Builder() {
       this.prefix = "";
       this.bucketName = "";
-      this.optionsPerRequest = ImmutableList.of();
       this.writeOptsPerRequest = ImmutableList.of();
     }
 
+    /**
+     * Sets the parameter for skipIfExists. When set to true Transfer Manager will skip uploading an
+     * object if it already exists.
+     *
+     * @return the builder instance with the value for skipIfExists modified.
+     * @see ParallelUploadConfig#isSkipIfExists()
+     */
     @BetaApi
     public Builder setSkipIfExists(boolean skipIfExists) {
       this.skipIfExists = skipIfExists;
       return this;
     }
 
+    /**
+     * Sets a common prefix that will be applied to all object paths in the destination bucket.
+     *
+     * @return the builder instance with the value for prefix modified.
+     * @see ParallelUploadConfig#getPrefix()
+     */
     @BetaApi
     public Builder setPrefix(@NonNull String prefix) {
       this.prefix = prefix;
       return this;
     }
 
+    /**
+     * Sets the bucketName that Transfer Manager will upload to. This field is required.
+     *
+     * @return the builder instance with the value for bucketName modified.
+     * @see ParallelUploadConfig#getBucketName()
+     */
     @BetaApi
     public Builder setBucketName(@NonNull String bucketName) {
       this.bucketName = bucketName;
       return this;
     }
 
-    @BetaApi
-    public Builder setOptionsPerRequest(@NonNull List<BlobTargetOption> optionsPerRequest) {
-      this.optionsPerRequest = ImmutableList.copyOf(optionsPerRequest);
-      return this;
-    }
-
+    /**
+     * Sets the BlobWriteOptions that will be applied to each upload request. Note these options
+     * will be applied to every single upload request.
+     *
+     * @return the builder instance with the value for WriteOptsPerRequest modified.
+     * @see ParallelUploadConfig#getWriteOptsPerRequest()
+     */
     @BetaApi
     public Builder setWriteOptsPerRequest(@NonNull List<BlobWriteOption> writeOptsPerRequest) {
       this.writeOptsPerRequest = writeOptsPerRequest;
       return this;
     }
 
+    /**
+     * Creates a ParallelUploadConfig object.
+     *
+     * @return {@link ParallelUploadConfig}
+     */
     @BetaApi
     public ParallelUploadConfig build() {
       checkNotNull(prefix);
       checkNotNull(bucketName);
-      checkNotNull(optionsPerRequest);
       checkNotNull(writeOptsPerRequest);
-      return new ParallelUploadConfig(
-          skipIfExists, prefix, bucketName, optionsPerRequest, writeOptsPerRequest);
+      return new ParallelUploadConfig(skipIfExists, prefix, bucketName, writeOptsPerRequest);
     }
   }
 }