com.google.cloud.storage.transfermanager.TransferManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of google-cloud-storage Show documentation
Java idiomatic client for Google Cloud Storage.
There is a newer version: 2.45.0
/*
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.cloud.storage.transfermanager;

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 config) throws IOException;

  /**
   * 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 config);
}