public class TransferManager extends Object
TransferManager provides a simple API for uploading content to
Amazon S3, and makes extensive use of Amazon S3 multipart uploads to achieve
enhanced throughput, performance and reliability.
When possible, TransferManager attempts to use multiple threads
to upload multiple parts of a single upload at once. When dealing with large
content sizes and high bandwidth, this can have a significant increase on
throughput.
TransferManager is responsible for managing resources such as
connections and threads; share a single instance of
TransferManager whenever possible. TransferManager,
like all the client classes in the Amazon Web Services SDK for Java, is thread safe. Call
TransferManager.shutdownNow() to release the resources once the
transfer is complete.
Using TransferManager to upload objects to Amazon S3 is easy:
DefaultAWSCredentialsProviderChain credentialProviderChain = new DefaultAWSCredentialsProviderChain();
TransferManager tx = new TransferManager(
credentialProviderChain.getCredentials());
Upload myUpload = tx.upload(myBucket, myFile.getName(), myFile);
// You can poll your transfer's status to check its progress
if (myUpload.isDone() == false) {
System.out.println("Transfer: " + myUpload.getDescription());
System.out.println(" - State: " + myUpload.getState());
System.out.println(" - Progress: "
+ myUpload.getProgress().getBytesTransferred());
}
// Transfers also allow you to set a <code>ProgressListener</code> to receive
// asynchronous notifications about your transfer's progress.
myUpload.addProgressListener(myProgressListener);
// Or you can block the current thread and wait for your transfer to
// to complete. If the transfer fails, this method will throw an
// AmazonClientException or AmazonServiceException detailing the reason.
myUpload.waitForCompletion();
// After the upload is complete, call shutdownNow to release the resources.
tx.shutdownNow();
Transfers can be paused and resumed at a later time. It can also survive JVM crash, provided the information that is required to resume the transfer is given as input to the resume operation. For more information on pause and resume.
See Migration Guide for more information.
| Modifier | Constructor and Description |
|---|---|
|
TransferManager()
Deprecated.
|
|
TransferManager(AmazonS3 s3)
Deprecated.
|
|
TransferManager(AmazonS3 s3,
ExecutorService executorService)
|
|
TransferManager(AmazonS3 s3,
ExecutorService executorService,
boolean shutDownThreadPools)
|
|
TransferManager(AWSCredentials credentials)
Deprecated.
use
TransferManagerBuilder.withS3Client(AmazonS3) for example:
TransferManagerBuilder.standard().withS3Client(AmazonS3ClientBuilder.standard.withCredentials(credentials).build()).build(); |
|
TransferManager(AWSCredentialsProvider credentialsProvider)
Deprecated.
use
TransferManagerBuilder.withS3Client(AmazonS3) for example:
TransferManagerBuilder.standard().withS3Client(AmazonS3ClientBuilder.standard.withCredentials(credentialsProvider).build()).build(); |
protected |
TransferManager(TransferManagerBuilder builder)
Constructor for use by classes that need to extend the TransferManager.
|
| Modifier and Type | Method and Description |
|---|---|
void |
abortMultipartUploads(String bucketName,
Date date)
Aborts any multipart uploads that were initiated before the specified date.
|
static <X extends AmazonWebServiceRequest> |
appendMultipartUserAgent(X request) |
static <X extends AmazonWebServiceRequest> |
appendSingleObjectUserAgent(X request) |
Copy |
copy(CopyObjectRequest copyObjectRequest)
Schedules a new transfer to copy data from one Amazon S3 location to
another Amazon S3 location.
|
Copy |
copy(CopyObjectRequest copyObjectRequest,
AmazonS3 srcS3,
TransferStateChangeListener stateChangeListener)
Schedules a new transfer to copy data from one Amazon S3 location to
another Amazon S3 location.
|
Copy |
copy(CopyObjectRequest copyObjectRequest,
TransferStateChangeListener stateChangeListener)
Schedules a new transfer to copy data from one Amazon S3 location to
another Amazon S3 location.
|
Copy |
copy(String sourceBucketName,
String sourceKey,
String destinationBucketName,
String destinationKey)
Schedules a new transfer to copy data from one Amazon S3 location to
another Amazon S3 location.
|
Download |
download(GetObjectRequest getObjectRequest,
File file)
Schedules a new transfer to download data from Amazon S3 and save it to
the specified file.
|
Download |
download(GetObjectRequest getObjectRequest,
File file,
long timeoutMillis)
Schedules a new transfer to download data from Amazon S3 and save it to
the specified file.
|
Download |
download(GetObjectRequest getObjectRequest,
File file,
S3ProgressListener progressListener)
Schedules a new transfer to download data from Amazon S3 and save it to
the specified file.
|
Download |
download(GetObjectRequest getObjectRequest,
File file,
S3ProgressListener progressListener,
long timeoutMillis)
Schedules a new transfer to download data from Amazon S3 and save it to
the specified file.
|
Download |
download(GetObjectRequest getObjectRequest,
File file,
S3ProgressListener progressListener,
long timeoutMillis,
boolean resumeOnRetry)
Schedules a new transfer to download data from Amazon S3 and save it to
the specified file.
|
PresignedUrlDownload |
download(PresignedUrlDownloadRequest request,
File destFile)
Schedules a new transfer to download data from Amazon S3 using presigned url
and save it to the specified file.
|
PresignedUrlDownload |
download(PresignedUrlDownloadRequest request,
File destFile,
PresignedUrlDownloadConfig downloadContext)
Schedules a new transfer to download data from Amazon S3 using presigned url
and save it to the specified file.
|
Download |
download(String bucket,
String key,
File file)
Schedules a new transfer to download data from Amazon S3 and save it to
the specified file.
|
Download |
download(String bucket,
String key,
File file,
long timeoutMillis)
Schedules a new transfer to download data from Amazon S3 and save it to
the specified file.
|
MultipleFileDownload |
downloadDirectory(String bucketName,
String keyPrefix,
File destinationDirectory) |
MultipleFileDownload |
downloadDirectory(String bucketName,
String keyPrefix,
File destinationDirectory,
boolean resumeOnRetry) |
MultipleFileDownload |
downloadDirectory(String bucketName,
String keyPrefix,
File destinationDirectory,
boolean resumeOnRetry,
KeyFilter filter)
Downloads all objects in the virtual directory designated by the
keyPrefix given to the destination directory given.
|
MultipleFileDownload |
downloadDirectory(String bucketName,
String keyPrefix,
File destinationDirectory,
KeyFilter filter) |
protected void |
finalize()
Releasing all resources created by
TransferManager before it
is being garbage collected. |
AmazonS3 |
getAmazonS3Client()
Returns the underlying Amazon S3 client used to make requests to
Amazon S3.
|
TransferManagerConfiguration |
getConfiguration()
Returns the configuration which specifies how
this
TransferManager processes requests. |
Download |
resumeDownload(PersistableDownload persistableDownload)
Resumes an download operation.
|
Upload |
resumeUpload(PersistableUpload persistableUpload)
Resumes an upload operation.
|
void |
setConfiguration(TransferManagerConfiguration configuration)
Deprecated.
use appropriate method on the
TransferManagerBuilder for example:
TransferManagerBuilder.standard().withMinimumUploadPartSize(100L).build(); |
void |
shutdownNow()
Forcefully shuts down this TransferManager instance - currently executing
transfers will not be allowed to finish.
|
void |
shutdownNow(boolean shutDownS3Client)
Forcefully shuts down this TransferManager instance - currently executing
transfers will not be allowed to finish.
|
Upload |
upload(PutObjectRequest putObjectRequest)
Schedules a new transfer to upload data to Amazon S3.
|
Upload |
upload(PutObjectRequest putObjectRequest,
S3ProgressListener progressListener)
Schedules a new transfer to upload data to Amazon S3.
|
Upload |
upload(String bucketName,
String key,
File file)
Schedules a new transfer to upload data to Amazon S3.
|
Upload |
upload(String bucketName,
String key,
InputStream input,
ObjectMetadata objectMetadata)
Schedules a new transfer to upload data to Amazon S3.
|
MultipleFileUpload |
uploadDirectory(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
boolean includeSubdirectories)
Uploads all files in the directory given to the bucket named, optionally
recursing for all subdirectories.
|
MultipleFileUpload |
uploadDirectory(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
boolean includeSubdirectories,
ObjectMetadataProvider metadataProvider)
Uploads all files in the directory given to the bucket named, optionally
recursing for all subdirectories.
|
MultipleFileUpload |
uploadDirectory(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
boolean includeSubdirectories,
ObjectMetadataProvider metadataProvider,
com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider)
Uploads all files in the directory given to the bucket named, optionally
recursing for all subdirectories.
|
MultipleFileUpload |
uploadDirectory(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
boolean includeSubdirectories,
ObjectMetadataProvider metadataProvider,
com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider,
ObjectCannedAclProvider cannedAclProvider)
Uploads all files in the directory given to the bucket named, optionally
recursing for all subdirectories.
|
MultipleFileUpload |
uploadFileList(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
List<File> files)
Uploads all specified files to the bucket named, constructing
relative keys depending on the commonParentDirectory given.
|
MultipleFileUpload |
uploadFileList(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
List<File> files,
ObjectMetadataProvider metadataProvider)
Uploads all specified files to the bucket named, constructing
relative keys depending on the commonParentDirectory given.
|
MultipleFileUpload |
uploadFileList(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
List<File> files,
ObjectMetadataProvider metadataProvider,
com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider)
Uploads all specified files to the bucket named, constructing
relative keys depending on the commonParentDirectory given.
|
MultipleFileUpload |
uploadFileList(String bucketName,
String virtualDirectoryKeyPrefix,
File directory,
List<File> files,
ObjectMetadataProvider metadataProvider,
com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider,
ObjectCannedAclProvider cannedAclProvider)
Uploads all specified files to the bucket named, constructing
relative keys depending on the commonParentDirectory given.
|
@Deprecated public TransferManager()
TransferManagerBuilder.defaultTransferManager()TransferManager and Amazon S3 client using
the credentials from DefaultAWSCredentialsProviderChain
TransferManager and client objects may pool connections and
threads. Reuse TransferManager and client objects and share
them throughout applications.
TransferManager and all Amazon Web Services client objects are thread safe.
@Deprecated public TransferManager(AWSCredentialsProvider credentialsProvider)
TransferManagerBuilder.withS3Client(AmazonS3) for example:
TransferManagerBuilder.standard().withS3Client(AmazonS3ClientBuilder.standard.withCredentials(credentialsProvider).build()).build(); TransferManager and Amazon S3 client using
the specified Amazon Web Services security credentials provider.
TransferManager and client objects may pool connections and
threads. Reuse TransferManager and client objects and share
them throughout applications.
TransferManager and all Amazon Web Services client objects are thread safe.
credentialsProvider - The Amazon Web Services security credentials provider to use when making
authenticated requests.@Deprecated public TransferManager(AWSCredentials credentials)
TransferManagerBuilder.withS3Client(AmazonS3) for example:
TransferManagerBuilder.standard().withS3Client(AmazonS3ClientBuilder.standard.withCredentials(credentials).build()).build(); TransferManager and Amazon S3 client using
the specified Amazon Web Services security credentials.
TransferManager and client objects
may pool connections and threads.
Reuse TransferManager and client objects
and share them throughout applications.
TransferManager and all Amazon Web Services client objects are thread safe.
credentials - The Amazon Web Services security credentials to use when making authenticated
requests.@Deprecated public TransferManager(AmazonS3 s3)
TransferManagerBuilder.withS3Client(AmazonS3)TransferManager,
specifying the client to use when making
requests to Amazon S3.
TransferManager and client objects
may pool connections and threads.
Reuse TransferManager and client objects
and share them throughout applications.
TransferManager and all Amazon Web Services client objects are thread safe.
s3 - The client to use when making requests to Amazon S3.@Deprecated public TransferManager(AmazonS3 s3, ExecutorService executorService)
TransferManagerBuilder.withS3Client(AmazonS3) and
TransferManagerBuilder.withExecutorFactory(com.ibm.cloud.objectstorage.client.builder.ExecutorFactory)TransferManager specifying the client and
thread pool to use when making requests to Amazon S3.
TransferManager and client objects may pool connections and
threads. Reuse TransferManager and client objects and share
them throughout applications.
TransferManager and all Amazon Web Services client objects are thread safe.
By default, the thread pool will shutdown when the transfer manager instance is garbage collected.
s3 - The client to use when making requests to Amazon S3.executorService - The ExecutorService to use for the TransferManager. It is not recommended to
use a single threaded executor or a thread pool with a bounded work queue as
control tasks may submit subtasks that can't complete until all sub tasks
complete. Using an incorrectly configured thread pool may cause a deadlock (I.E.
the work queue is filled with control tasks that can't finish until subtasks
complete but subtasks can't execute because the queue is filled).TransferManager(AmazonS3 s3, ExecutorService
executorService, boolean shutDownThreadPools)@Deprecated public TransferManager(AmazonS3 s3, ExecutorService executorService, boolean shutDownThreadPools)
TransferManagerBuilder.withS3Client(AmazonS3) and
TransferManagerBuilder.withExecutorFactory(com.ibm.cloud.objectstorage.client.builder.ExecutorFactory) and
TransferManagerBuilder.withShutDownThreadPools(Boolean)TransferManager specifying the client and
thread pool to use when making requests to Amazon S3.
TransferManager and client objects may pool connections and
threads. Reuse TransferManager and client objects and share
them throughout applications.
TransferManager and all Amazon Web Services client objects are thread safe.
s3 - The client to use when making requests to Amazon S3.executorService - The ExecutorService to use for the TransferManager. It is not recommended to
use a single threaded executor or a thread pool with a bounded work queue as
control tasks may submit subtasks that can't complete until all sub tasks
complete. Using an incorrectly configured thread pool may cause a deadlock (I.E.
the work queue is filled with control tasks that can't finish until subtasks
complete but subtasks can't execute because the queue is filled).shutDownThreadPools - If set to true, the thread pool will be shutdown when transfer
manager instance is garbage collected.protected TransferManager(TransferManagerBuilder builder)
builder - - transfer manager builder with the required configuration@Deprecated public void setConfiguration(TransferManagerConfiguration configuration)
TransferManagerBuilder for example:
TransferManagerBuilder.standard().withMinimumUploadPartSize(100L).build(); TransferManager processes requests.configuration - The new configuration specifying how
this TransferManager
processes requests.public TransferManagerConfiguration getConfiguration()
TransferManager processes requests.TransferManager.public AmazonS3 getAmazonS3Client()
public Upload upload(String bucketName, String key, InputStream input, ObjectMetadata objectMetadata) throws AmazonServiceException, AmazonClientException
Schedules a new transfer to upload data to Amazon S3. This method is non-blocking and returns immediately (i.e. before the upload has finished).
When uploading options from a stream, callers must supply the size of
options in the stream through the content length field in the
ObjectMetadata parameter.
If no content length is specified for the input
stream, then TransferManager will attempt to buffer all the stream
contents in memory and upload the options as a traditional, single part
upload. Because the entire stream contents must be buffered in memory,
this can be very expensive, and should be avoided whenever possible.
Use the returned Upload object to query the progress of the
transfer, add listeners for progress events, and wait for the upload to
complete.
If resources are available, the upload will begin immediately. Otherwise, the upload is scheduled and started as soon as resources become available.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload the new object to.key - The key in the specified bucket by which to store the new
object.input - The input stream containing the options to upload to Amazon S3.objectMetadata - Additional information about the object being uploaded,
including the size of the options, content type, additional
custom user metadata, etc.Upload object to use to check
the state of the upload, listen for progress notifications,
and otherwise manage the upload.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Upload upload(String bucketName, String key, File file) throws AmazonServiceException, AmazonClientException
The returned Upload object allows you to query the progress of the transfer, add listeners for progress events, and wait for the upload to complete.
If resources are available, the upload will begin immediately, otherwise it will be scheduled and started as soon as resources become available.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload the new object to.key - The key in the specified bucket by which to store the new
object.file - The file to upload.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Upload upload(PutObjectRequest putObjectRequest) throws AmazonServiceException, AmazonClientException
Schedules a new transfer to upload data to Amazon S3. This method is non-blocking and returns immediately (i.e. before the upload has finished).
Use the returned Upload object to query the progress of the
transfer, add listeners for progress events, and wait for the upload to
complete.
If resources are available, the upload will begin immediately. Otherwise, the upload is scheduled and started as soon as resources become available.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
putObjectRequest - The request containing all the parameters for the upload.Upload object to use to check
the state of the upload, listen for progress notifications,
and otherwise manage the upload.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Upload upload(PutObjectRequest putObjectRequest, S3ProgressListener progressListener) throws AmazonServiceException, AmazonClientException
Schedules a new transfer to upload data to Amazon S3. This method is non-blocking and returns immediately (i.e. before the upload has finished).
Use the returned Upload object to query the progress of the
transfer, add listeners for progress events, and wait for the upload to
complete.
If resources are available, the upload will begin immediately. Otherwise, the upload is scheduled and started as soon as resources become available.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
putObjectRequest - The request containing all the parameters for the upload.progressListener - An optional callback listener to receive the progress of the
upload.Upload object to use to check the state of the
upload, listen for progress notifications, and otherwise manage
the upload.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download download(String bucket, String key, File file)
Use the returned Download object to query the progress of the transfer, add listeners for progress events, and wait for the download to complete.
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucket - The name of the bucket containing the object to download.key - The key under which the object to download is stored.file - The file to download the object's data to.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download download(String bucket, String key, File file, long timeoutMillis)
Use the returned Download object to query the progress of the transfer, add listeners for progress events, and wait for the download to complete.
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucket - The name of the bucket containing the object to download.key - The key under which the object to download is stored.file - The file to download the object's data to.timeoutMillis - Timeout, in milliseconds, for waiting for this download to
complete. Note that the timeout time will be approximate
and is not strictly guaranteed. As a result this timeout
should not be relied on in cases where exact precision is
required.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download download(GetObjectRequest getObjectRequest, File file)
Use the returned Download object to query the progress of the transfer, add listeners for progress events, and wait for the download to complete.
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
getObjectRequest - The request containing all the parameters for the download.file - The file to download the object data to.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download download(GetObjectRequest getObjectRequest, File file, long timeoutMillis)
Use the returned Download object to query the progress of the transfer, add listeners for progress events, and wait for the download to complete.
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
getObjectRequest - The request containing all the parameters for the download.file - The file to download the object data to.timeoutMillis - Timeout, in milliseconds, for waiting for this download to
complete. Note that the timeout time will be approximate
and is not strictly guaranteed. As a result this timeout
should not be relied on in cases where exact precision is
required.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download download(GetObjectRequest getObjectRequest, File file, S3ProgressListener progressListener)
Use the returned Download object to query the progress of the transfer, add listeners for progress events, and wait for the download to complete.
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
getObjectRequest - The request containing all the parameters for the download.file - The file to download the object data to.progressListener - An optional callback listener to get the progress of the
download.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download download(GetObjectRequest getObjectRequest, File file, S3ProgressListener progressListener, long timeoutMillis)
Use the returned Download object to query the progress of the transfer, add listeners for progress events, and wait for the download to complete.
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
getObjectRequest - The request containing all the parameters for the download.file - The file to download the object data to.progressListener - An optional callback listener to get the progress of the
download.timeoutMillis - Timeout, in milliseconds, for waiting for this download to
complete. Note that the timeout time will be approximate
and is not strictly guaranteed. As a result this timeout
should not be relied on in cases where exact precision is
required.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download download(GetObjectRequest getObjectRequest, File file, S3ProgressListener progressListener, long timeoutMillis, boolean resumeOnRetry)
Use the returned Download object to query the progress of the transfer, add listeners for progress events, and wait for the download to complete.
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
getObjectRequest - The request containing all the parameters for the download.file - The file to download the object data to.progressListener - An optional callback listener to get the progress of the
download.timeoutMillis - Timeout, in milliseconds, for waiting for this download to
complete. Note that the timeout time will be approximate
and is not strictly guaranteed. As a result this timeout
should not be relied on in cases where exact precision is
required.resumeOnRetry - If set to true, upon an immediate retry of a failed object
download, the TransferManager will resume the
download from the current end of the file on disk.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public PresignedUrlDownload download(PresignedUrlDownloadRequest request, File destFile)
Use the returned PresignedUrlDownload object to query the progress of the transfer,
add listeners for progress events, and wait for the download to complete.
Note: The result of the operation doesn't support pause and resume functionality.
request - The request containing all the parameters for the download.destFile - The file to download the object data to.PresignedUrlDownload object to check the state of the download,
listen for progress notifications, and otherwise manage the download.public PresignedUrlDownload download(PresignedUrlDownloadRequest request, File destFile, PresignedUrlDownloadConfig downloadContext)
Use the returned PresignedUrlDownload object to query the progress of the transfer,
add listeners for progress events, and wait for the download to complete.
Note: The result of the operation doesn't support pause and resume functionality.
request - The request containing all the parameters for the download.destFile - The file to download the object data to.downloadContext - Additional configuration to control the download behaviorPresignedUrlDownload object to check the state of the download,
listen for progress notifications, and otherwise manage the download.public MultipleFileDownload downloadDirectory(String bucketName, String keyPrefix, File destinationDirectory)
public MultipleFileDownload downloadDirectory(String bucketName, String keyPrefix, File destinationDirectory, KeyFilter filter)
public MultipleFileDownload downloadDirectory(String bucketName, String keyPrefix, File destinationDirectory, boolean resumeOnRetry)
public MultipleFileDownload downloadDirectory(String bucketName, String keyPrefix, File destinationDirectory, boolean resumeOnRetry, KeyFilter filter)
If you are downloading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The bucket containing the virtual directorykeyPrefix - The key prefix for the virtual directory, or null for the
entire bucket. All subdirectories will be downloaded
recursively.destinationDirectory - The directory to place downloaded files. Subdirectories will
be created as necessary.resumeOnRetry - If set to true, upon an immediate retry of a failed object
download, the TransferManager will resume the
download from the current end of the file on disk.filter - If set, applies the filter to determine which keys to include
in the download request. (default is include all).public MultipleFileUpload uploadDirectory(String bucketName, String virtualDirectoryKeyPrefix, File directory, boolean includeSubdirectories)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The directory to upload.includeSubdirectories - Whether to include subdirectories in the upload. If true,
files found in subdirectories will be included with an
appropriate concatenation to the key prefix.public MultipleFileUpload uploadDirectory(String bucketName, String virtualDirectoryKeyPrefix, File directory, boolean includeSubdirectories, ObjectMetadataProvider metadataProvider)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The directory to upload.includeSubdirectories - Whether to include subdirectories in the upload. If true,
files found in subdirectories will be included with an
appropriate concatenation to the key prefix.metadataProvider - A callback of type ObjectMetadataProvider which
is used to provide metadata for each file being uploaded.public MultipleFileUpload uploadDirectory(String bucketName, String virtualDirectoryKeyPrefix, File directory, boolean includeSubdirectories, ObjectMetadataProvider metadataProvider, com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The directory to upload.includeSubdirectories - Whether to include subdirectories in the upload. If true,
files found in subdirectories will be included with an
appropriate concatenation to the key prefix.metadataProvider - A callback of type ObjectMetadataProvider which
is used to provide metadata for each file being uploaded.taggingProvider - A callback of type ObjectTaggingProvider which
is used to provide the tags for each file being uploaded.public MultipleFileUpload uploadDirectory(String bucketName, String virtualDirectoryKeyPrefix, File directory, boolean includeSubdirectories, ObjectMetadataProvider metadataProvider, com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider, ObjectCannedAclProvider cannedAclProvider)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The directory to upload.includeSubdirectories - Whether to include subdirectories in the upload. If true,
files found in subdirectories will be included with an
appropriate concatenation to the key prefix.metadataProvider - A callback of type ObjectMetadataProvider which
is used to provide metadata for each file being uploaded.taggingProvider - A callback of type ObjectTaggingProvider which
is used to provide the tags for each file being uploaded.cannedAclProvider - A callback of type ObjectCannedAclProvider which
is used to provide the CannedAccessControlList for each file
being uploaded.public MultipleFileUpload uploadFileList(String bucketName, String virtualDirectoryKeyPrefix, File directory, List<File> files)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The common parent directory of files to upload. The keys
of the files in the list of files are constructed relative to
this directory and the virtualDirectoryKeyPrefix.files - A list of files to upload. The keys of the files are
calculated relative to the common parent directory and the
virtualDirectoryKeyPrefix.public MultipleFileUpload uploadFileList(String bucketName, String virtualDirectoryKeyPrefix, File directory, List<File> files, ObjectMetadataProvider metadataProvider)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The common parent directory of files to upload. The keys
of the files in the list of files are constructed relative to
this directory and the virtualDirectoryKeyPrefix.files - A list of files to upload. The keys of the files are
calculated relative to the common parent directory and the
virtualDirectoryKeyPrefix.metadataProvider - A callback of type ObjectMetadataProvider which
is used to provide metadata for each file being uploaded.public MultipleFileUpload uploadFileList(String bucketName, String virtualDirectoryKeyPrefix, File directory, List<File> files, ObjectMetadataProvider metadataProvider, com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The common parent directory of files to upload. The keys
of the files in the list of files are constructed relative to
this directory and the virtualDirectoryKeyPrefix.files - A list of files to upload. The keys of the files are
calculated relative to the common parent directory and the
virtualDirectoryKeyPrefix.metadataProvider - A callback of type ObjectMetadataProvider which
is used to provide metadata for each file being uploaded.taggingProvider - A callback of type ObjectTaggingProvider which
is used to provide the tags for each file being uploaded.public MultipleFileUpload uploadFileList(String bucketName, String virtualDirectoryKeyPrefix, File directory, List<File> files, ObjectMetadataProvider metadataProvider, com.ibm.cloud.objectstorage.services.s3.transfer.ObjectTaggingProvider taggingProvider, ObjectCannedAclProvider cannedAclProvider)
S3 will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
If you are uploading Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket to upload objects to.virtualDirectoryKeyPrefix - The key prefix of the virtual directory to upload to. Use the
null or empty string to upload files to the root of the
bucket.directory - The common parent directory of files to upload. The keys
of the files in the list of files are constructed relative to
this directory and the virtualDirectoryKeyPrefix.files - A list of files to upload. The keys of the files are
calculated relative to the common parent directory and the
virtualDirectoryKeyPrefix.metadataProvider - A callback of type ObjectMetadataProvider which
is used to provide metadata for each file being uploaded.taggingProvider - A callback of type ObjectTaggingProvider which
is used to provide the tags for each file being uploaded.cannedAclProvider - A callback of type ObjectCannedAclProvider which
is used to provide the CannedAccessControlList for each file
being uploaded.public void abortMultipartUploads(String bucketName, Date date) throws AmazonServiceException, AmazonClientException
Aborts any multipart uploads that were initiated before the specified date.
This method is useful for cleaning up any interrupted multipart uploads.
TransferManager attempts to abort any failed uploads,
but in some cases this may not be possible, such as if network connectivity
is completely lost.
bucketName - The name of the bucket containing the multipart uploads to
abort.date - The date indicating which multipart uploads should be aborted.AmazonServiceExceptionAmazonClientExceptionpublic void shutdownNow()
TransferManager.shutdownNow(boolean)public void shutdownNow(boolean shutDownS3Client)
Callers should also remember that uploaded parts from an interrupted
upload may not always be automatically cleaned up, but callers can use
TransferManager.abortMultipartUploads(String, Date) to clean up any upload
parts.
shutDownS3Client - Whether to shut down the underlying Amazon S3 client.public static <X extends AmazonWebServiceRequest> X appendSingleObjectUserAgent(X request)
public static <X extends AmazonWebServiceRequest> X appendMultipartUserAgent(X request)
public Copy copy(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey) throws AmazonServiceException, AmazonClientException
Schedules a new transfer to copy data from one Amazon S3 location to another Amazon S3 location. This method is non-blocking and returns immediately (before the copy has finished).
TransferManager doesn't support copying of encrypted objects
whose encryption materials are stored in an instruction file.
Use the returned Copy object to check if the copy is
complete.
If resources are available, the copy request will begin immediately. Otherwise, the copy is scheduled and started as soon as resources become available.
Note: If the TransferManager is created with a regional S3 client and
the source & destination buckets are in different regions, use the
TransferManager.copy(CopyObjectRequest, AmazonS3, TransferStateChangeListener) method.
sourceBucketName - The name of the bucket from where the object is to be copied.sourceKey - The name of the Amazon S3 object.destinationBucketName - The name of the bucket to where the Amazon S3 object has to be
copied.destinationKey - The name of the object in the destination bucket.Copy object to use to check the state of the
copy request being processed.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.TransferManager.copy(CopyObjectRequest, AmazonS3, TransferStateChangeListener)public Copy copy(CopyObjectRequest copyObjectRequest)
Schedules a new transfer to copy data from one Amazon S3 location to another Amazon S3 location. This method is non-blocking and returns immediately (i.e. before the copy has finished).
TransferManager doesn't support copying of encrypted objects
whose encryption materials are stored in an instruction file.
Use the returned Copy object to check if the copy is
complete.
If resources are available, the copy request will begin immediately. Otherwise, the copy is scheduled and started as soon as resources become available.
Note: If the TransferManager is created with a regional S3 client and
the source & destination buckets are in different regions, use the
TransferManager.copy(CopyObjectRequest, AmazonS3, TransferStateChangeListener) method.
copyObjectRequest - The request containing all the parameters for the copy.Copy object to use to check the state of the
copy request being processed.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.TransferManager.copy(CopyObjectRequest, AmazonS3, TransferStateChangeListener)public Copy copy(CopyObjectRequest copyObjectRequest, TransferStateChangeListener stateChangeListener) throws AmazonServiceException, AmazonClientException
Schedules a new transfer to copy data from one Amazon S3 location to another Amazon S3 location. This method is non-blocking and returns immediately (i.e. before the copy has finished).
TransferManager doesn't support copying of encrypted objects
whose encryption materials are stored in an instruction file.
Use the returned Copy object to check if the copy is
complete.
If resources are available, the copy request will begin immediately. Otherwise, the copy is scheduled and started as soon as resources become available.
Note: If the TransferManager is created with a regional S3 client and
the source & destination buckets are in different regions, use the
TransferManager.copy(CopyObjectRequest, AmazonS3, TransferStateChangeListener) method.
copyObjectRequest - The request containing all the parameters for the copy.stateChangeListener - The transfer state change listener to monitor the copy requestCopy object to use to check the state of the
copy request being processed.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.TransferManager.copy(CopyObjectRequest, AmazonS3, TransferStateChangeListener)public Copy copy(CopyObjectRequest copyObjectRequest, AmazonS3 srcS3, TransferStateChangeListener stateChangeListener) throws AmazonServiceException, AmazonClientException
Schedules a new transfer to copy data from one Amazon S3 location to another Amazon S3 location. This method is non-blocking and returns immediately (i.e. before the copy has finished).
Note: You need to use this method if the TransferManager is created with
a regional S3 client and the source & destination buckets are in different regions.
TransferManager doesn't support copying of encrypted objects
whose encryption materials are stored in an instruction file.
Use the returned Copy object to check if the copy is
complete.
If resources are available, the copy request will begin immediately. Otherwise, the copy is scheduled and started as soon as resources become available.
copyObjectRequest - The request containing all the parameters for the copy.srcS3 - An AmazonS3 client constructed for the region in which the source
object's bucket is located.stateChangeListener - The transfer state change listener to monitor the copy requestCopy object to use to check the state of the
copy request being processed.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Upload resumeUpload(PersistableUpload persistableUpload)
TransferManagerConfiguration as the original
upload. Any data already uploaded will be skipped, and only the remaining
will be uploaded to Amazon S3.persistableUpload - the upload to resume.Upload object to use to check the state of the
upload, listen for progress notifications, and otherwise manage
the upload.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.public Download resumeDownload(PersistableDownload persistableDownload)
persistableDownload - the download to resume.Download object to use to check the state of
the download, listen for progress notifications, and otherwise
manage the download.AmazonClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.Copyright © 2025. All rights reserved.