docs: Javadocs for remainder of Transfer Manager (#2097)

sydney-munro · web-flow · commit 0362e80386d8 · 2023-06-29T09:37:38.000-07:00
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/DownloadJob.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/DownloadJob.java
@@ -29,6 +29,11 @@
 import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * A parallel download job sent to Transfer Manager.
+ *
+ * @see Builder
+ */
 @BetaApi
 public final class DownloadJob {
 
@@ -43,11 +48,23 @@ private DownloadJob(
     this.parallelDownloadConfig = parallelDownloadConfig;
   }
 
+  /**
+   * The list of {@link DownloadResult DownloadResults} for each download request Transfer Manager
+   * executed for this job. Note calling this method will block the invoking thread until all
+   * download requests are complete.
+   *
+   * @see Builder#setDownloadResults(List)
+   */
   @BetaApi
   public @NonNull List<DownloadResult> getDownloadResults() {
     return ApiExceptions.callAndTranslateApiException(ApiFutures.allAsList(downloadResults));
   }
 
+  /**
+   * The {@link ParallelDownloadConfig} used for this DownloadJob.
+   *
+   * @see Builder#setParallelDownloadConfig(ParallelDownloadConfig)
+   */
   @BetaApi
   public @NonNull ParallelDownloadConfig getParallelDownloadConfig() {
     return parallelDownloadConfig;
@@ -84,6 +101,11 @@ public static Builder newBuilder() {
     return new Builder();
   }
 
+  /**
+   * Builds an instance of DownloadJob
+   *
+   * @see DownloadJob
+   */
   @BetaApi
   public static final class Builder {
 
@@ -94,19 +116,36 @@ private Builder() {
       this.downloadResults = ImmutableList.of();
     }
 
+    /**
+     * Sets the results for a DownloadJob being performed by Transfer Manager.
+     *
+     * @return the instance of the Builder with DownloadResults modified.
+     * @see DownloadJob#getDownloadResults()
+     */
     @BetaApi
     public Builder setDownloadResults(@NonNull List<ApiFuture<DownloadResult>> downloadResults) {
       this.downloadResults = ImmutableList.copyOf(downloadResults);
       return this;
     }
 
+    /**
+     * Sets the {@link ParallelDownloadConfig} used for this DownloadJob.
+     *
+     * @return the instance of the Builder with ParallelDownloadConfig modified.
+     * @see DownloadJob#getParallelDownloadConfig()
+     */
     @BetaApi
     public Builder setParallelDownloadConfig(
         @NonNull ParallelDownloadConfig parallelDownloadConfig) {
       this.parallelDownloadConfig = parallelDownloadConfig;
       return this;
     }
 
+    /**
+     * Creates a DownloadJob object.
+     *
+     * @return {@link DownloadJob}
+     */
     @BetaApi
     public DownloadJob build() {
       checkNotNull(downloadResults);
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/DownloadResult.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/DownloadResult.java
@@ -28,6 +28,11 @@
 import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * Result for a single download performed by Transfer Manager.
+ *
+ * @see Builder
+ */
 @BetaApi
 public final class DownloadResult {
   static final Comparator<DownloadResult> COMPARATOR =
@@ -49,11 +54,22 @@ private DownloadResult(
     this.exception = exception;
   }
 
+  /**
+   * The {@link BlobInfo} for the object requested for download.
+   *
+   * @see Builder#setInput(BlobInfo)
+   */
   @BetaApi
   public @NonNull BlobInfo getInput() {
     return input;
   }
 
+  /**
+   * The destination on the Filesystem the object has been written to. This field will only be
+   * populated if the Transfer was a {@link TransferStatus#SUCCESS SUCCESS}.
+   *
+   * @see Builder#setOutputDestination(Path)
+   */
   @BetaApi
   public @NonNull Path getOutputDestination() {
     checkState(
@@ -63,11 +79,24 @@ private DownloadResult(
     return outputDestination;
   }
 
+  /**
+   * The status of the download operation.
+   *
+   * @see TransferStatus
+   * @see Builder#setStatus(TransferStatus)
+   */
   @BetaApi
   public @NonNull TransferStatus getStatus() {
     return status;
   }
 
+  /**
+   * The exception produced by a failed download operation. This field will only be populated if the
+   * Transfer was not {@link TransferStatus#SUCCESS success}ful or {@link TransferStatus#SKIPPED
+   * skipped}
+   *
+   * @see Builder#setException(Exception)
+   */
   @BetaApi
   public @NonNull Exception getException() {
     checkState(
@@ -112,6 +141,11 @@ public static Builder newBuilder(@NonNull BlobInfo blobInfo, @NonNull TransferSt
     return new Builder(blobInfo, status);
   }
 
+  /**
+   * Builds an instance of DownloadResult
+   *
+   * @see DownloadResult
+   */
   @BetaApi
   public static final class Builder {
 
@@ -125,30 +159,62 @@ private Builder(@NonNull BlobInfo input, @NonNull TransferStatus status) {
       this.status = status;
     }
 
+    /**
+     * Sets the {@link BlobInfo} for the object request for download. This field is required.
+     *
+     * @see DownloadResult#getInput()
+     * @return the instance of the Builder with the value for input modified.
+     */
     @BetaApi
     public Builder setInput(@NonNull BlobInfo input) {
       this.input = input;
       return this;
     }
 
+    /**
+     * Sets the location on the Filesystem the object has been written to. This field will only be
+     * populated if the Transfer was {@link TransferStatus#SUCCESS success}ful.
+     *
+     * @see DownloadResult#getOutputDestination()
+     * @return the instance of the Builder with the value for outputDestination modified.
+     */
     @BetaApi
     public Builder setOutputDestination(@NonNull Path outputDestination) {
       this.outputDestination = outputDestination;
       return this;
     }
 
+    /**
+     * Sets the status of the download.This field is required.
+     *
+     * @see TransferStatus
+     * @return the instance of the Builder with the value for status modified.
+     */
     @BetaApi
     public Builder setStatus(@NonNull TransferStatus status) {
       this.status = status;
       return this;
     }
 
+    /**
+     * Sets the Exception produced by a failed download operation. This field will only be populated
+     * if the Transfer was not {@link TransferStatus#SUCCESS success}ful or {@link
+     * TransferStatus#SKIPPED skipped}
+     *
+     * @see DownloadResult#getException()
+     * @return the instance of the Builder with the value for exception modified.
+     */
     @BetaApi
     public Builder setException(@NonNull Exception exception) {
       this.exception = exception;
       return this;
     }
 
+    /**
+     * Creates a DownloadResult object.
+     *
+     * @return {@link DownloadResult}
+     */
     @BetaApi
     public DownloadResult build() {
       checkNotNull(input);
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManagerConfig.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManagerConfig.java
@@ -21,6 +21,11 @@
 import com.google.common.base.MoreObjects;
 import java.util.Objects;
 
+/**
+ * Configuration for an instance of {@link TransferManager}
+ *
+ * @see Builder
+ */
 @BetaApi
 public final class TransferManagerConfig {
   private final int maxWorkers;
@@ -43,13 +48,21 @@ public final class TransferManagerConfig {
     this.qos = qos;
   }
 
-  /** Maximum amount of workers to be allocated to perform work in Transfer Manager */
+  /**
+   * Maximum amount of workers to be allocated to perform work in Transfer Manager
+   *
+   * @see Builder#setMaxWorkers(int)
+   */
   @BetaApi
   public int getMaxWorkers() {
     return maxWorkers;
   }
 
-  /** Buffer size allowed to each worker */
+  /**
+   * Buffer size allowed to each worker
+   *
+   * @see Builder#setPerWorkerBufferSize(int)
+   */
   @BetaApi
   public int getPerWorkerBufferSize() {
     return perWorkerBufferSize;
@@ -58,18 +71,25 @@ public int getPerWorkerBufferSize() {
   /**
    * Whether to allow Transfer Manager to perform chunked Uploads/Downloads if it determines
    * chunking will be beneficial
+   *
+   * @see Builder#setAllowDivideAndConquer(boolean)
    */
   @BetaApi
   public boolean isAllowDivideAndConquer() {
     return allowDivideAndConquer;
   }
 
-  /** Storage options that Transfer Manager will use to interact with GCS */
+  /**
+   * Storage options that Transfer Manager will use to interact with Google Cloud Storage
+   *
+   * @see Builder#setStorageOptions(StorageOptions)
+   */
   @BetaApi
   public StorageOptions getStorageOptions() {
     return storageOptions;
   }
 
+  /** The service object for {@link TransferManager} */
   @BetaApi
   public TransferManager getService() {
     return new TransferManagerImpl(this);
@@ -124,6 +144,11 @@ public static Builder newBuilder() {
     return new Builder();
   }
 
+  /**
+   * Builds an instance of TransferManagerConfig
+   *
+   * @see TransferManagerConfig
+   */
   @BetaApi
   public static class Builder {
 
@@ -142,24 +167,58 @@ private Builder() {
       this.qos = DefaultQos.of();
     }
 
+    /**
+     * Maximum amount of workers to be allocated to perform work in Transfer Manager
+     *
+     * <p><i>Default Value:</i> {@code 2 * }{@link Runtime#getRuntime()}{@code .}{@link
+     * Runtime#availableProcessors() availableProcessors()}
+     *
+     * @return the instance of Builder with the value for maxWorkers modified.
+     * @see TransferManagerConfig#getMaxWorkers()
+     */
     @BetaApi
     public Builder setMaxWorkers(int maxWorkers) {
       this.maxWorkers = maxWorkers;
       return this;
     }
 
+    /**
+     * Buffer size allowed to each worker
+     *
+     * <p><i>Default Value:</i> 16MiB
+     *
+     * @return the instance of Builder with the value for maxWorkers modified.
+     * @see TransferManagerConfig#getPerWorkerBufferSize()
+     */
     @BetaApi
     public Builder setPerWorkerBufferSize(int perWorkerBufferSize) {
       this.perWorkerBufferSize = perWorkerBufferSize;
       return this;
     }
 
+    /**
+     * Whether to allow Transfer Manager to perform chunked Uploads/Downloads if it determines
+     * chunking will be beneficial
+     *
+     * <p><i>Default Value:</i> false
+     *
+     * @return the instance of Builder with the value for allowDivideAndConquer modified.
+     * @see TransferManagerConfig#isAllowDivideAndConquer()
+     */
     @BetaApi
     public Builder setAllowDivideAndConquer(boolean allowDivideAndConquer) {
       this.allowDivideAndConquer = allowDivideAndConquer;
       return this;
     }
 
+    /**
+     * Storage options that Transfer Manager will use to interact with Google Cloud Storage
+     *
+     * <p><i>Default Value:</i> {@link StorageOptions#getDefaultInstance()}
+     *
+     * @return the instance of Builder with the value for storageOptions modified.
+     * @see TransferManagerConfig#getStorageOptions()
+     */
     @BetaApi
     public Builder setStorageOptions(StorageOptions storageOptions) {
       this.storageOptions = storageOptions;
@@ -172,6 +231,11 @@ Builder setQos(Qos qos) {
       return this;
     }
 
+    /**
+     * Creates a TransferManagerConfig object.
+     *
+     * @return {@link TransferManagerConfig}
+     */
     @BetaApi
     public TransferManagerConfig build() {
       return new TransferManagerConfig(
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManagerImpl.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManagerImpl.java
@@ -77,7 +77,7 @@ public void close() throws Exception {
     }
     return UploadJob.newBuilder()
         .setParallelUploadConfig(config)
-        .setUploadResponses(ImmutableList.copyOf(uploadTasks))
+        .setUploadResults(ImmutableList.copyOf(uploadTasks))
         .build();
   }
 
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferStatus.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferStatus.java
@@ -19,14 +19,23 @@
 import com.google.api.core.BetaApi;
 import java.util.Comparator;
 
+/** The status of a Upload/Download operation performed by Transfer Manager. */
 @BetaApi
 public enum TransferStatus {
+  /** The transfer failed before bytes could be moved. */
   @BetaApi
   FAILED_TO_START,
+  /** The transfer failed after bytes could be moved. */
   @BetaApi
   FAILED_TO_FINISH,
+  /**
+   * The transfer failed because the object/file already exists and skipIfExists was set to true.
+   *
+   * @see ParallelUploadConfig.Builder#setSkipIfExists(boolean)
+   */
   @BetaApi
   SKIPPED,
+  /** The transfer was successful. */
   @BetaApi
   SUCCESS;
 
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/UploadJob.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/UploadJob.java
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/UploadResult.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/UploadResult.java
