diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelDownloadConfig.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelDownloadConfig.java index 6bce5a72e0..222dc9e36b 100644 --- a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelDownloadConfig.java +++ b/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 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 optionsPerRequest) { this.optionsPerRequest = ImmutableList.copyOf(optionsPerRequest); return this; } + /** + * Creates a ParallelDownloadConfig object. + * + * @return {@link ParallelDownloadConfig} + */ @BetaApi public ParallelDownloadConfig build() { checkNotNull(bucketName); diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelUploadConfig.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelUploadConfig.java index 8c7289c803..b724d9817b 100644 --- a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelUploadConfig.java +++ b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/ParallelUploadConfig.java @@ -19,7 +19,6 @@ 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; @@ -27,13 +26,17 @@ 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 targetOptsPerRequest; @NonNull private final List writeOptsPerRequest; @@ -41,40 +44,49 @@ private ParallelUploadConfig( boolean skipIfExists, @NonNull String prefix, @NonNull String bucketName, - @NonNull List targetOptsPerRequest, @NonNull List 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 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 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 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 optionsPerRequest; - private @NonNull List 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 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 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); } } } diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManager.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManager.java index 7db4780078..f333deca69 100644 --- a/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManager.java +++ b/google-cloud-storage/src/main/java/com/google/cloud/storage/transfermanager/TransferManager.java @@ -18,19 +18,77 @@ import com.google.api.core.BetaApi; import com.google.cloud.storage.BlobInfo; -import java.io.IOException; import java.nio.file.Path; import java.util.List; import org.checkerframework.checker.nullness.qual.NonNull; +/** + * An interface for a Transfer Manager. + * + *

Transfer Manager handles Parallel Uploads and Parallel Downloads. + */ @BetaApi public interface TransferManager extends AutoCloseable { + /** + * Uploads a list of files in parallel. This operation will not block the invoking thread, + * awaiting results should be done on the returned UploadJob. + * + *

Accepts a {@link ParallelUploadConfig} which defines the constraints of parallel uploads or + * predefined defaults. + * + *

Example of creating a parallel upload with Transfer Manager. + * + *

{@code
+   * String bucketName = "my-unique-bucket";
+   * Path filePath = Paths.get("/path/to/my/file.txt");
+   * Path anotherFilePath = Paths.get("/path/to/another/file.txt");
+   * List files = List.of(filePath, anotherFilePath);
+   *
+   * ParallelUploadConfig parallelUploadConfig =
+   *           ParallelUploadConfig.newBuilder()
+   *               .setBucketName(bucketName)
+   *               .build();
+   *
+   * UploadJob uploadedFiles = transferManager.uploadFiles(files, config);
+   *
+   * }
+ * + * @return an {@link UploadJob} + */ @BetaApi @NonNull - UploadJob uploadFiles(List files, ParallelUploadConfig opts) throws IOException; + UploadJob uploadFiles(List files, ParallelUploadConfig config); + /** + * Downloads a list of blobs in parallel. This operation will not block the invoking thread, + * awaiting results should be done on the returned DownloadJob. + * + *

Accepts a {@link ParallelDownloadConfig} which defines the constraints of parallel downloads + * or predefined defaults. + * + *

Example of creating a parallel download with Transfer Manager. + * + *

{@code
+   * String bucketName = "my-unique-bucket";
+   * String blobName = "my-blob-name";
+   * BlobId blobId = BlobId.of(bucketName, blobName);
+   * BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
+   * Path baseDir = Paths.get("/path/to/directory/");
+   *
+   * ParallelDownloadConfig parallelDownloadConfig =
+   *           ParallelDownloadConfig.newBuilder()
+   *               .setBucketName(bucketName)
+   *               .setDownloadDirectory(baseDir)
+   *               .build();
+   *
+   * DownloadJob downloadedBlobs = transferManager.downloadBlobs(files, config);
+   *
+   * }
+ * + * @return a {@link DownloadJob} + */ @BetaApi @NonNull - DownloadJob downloadBlobs(List blobs, ParallelDownloadConfig opts); + DownloadJob downloadBlobs(List blobs, ParallelDownloadConfig config); }