com.netease.cloud.services.nos.transfer
public class TransferManager extends Object
TransferManager
provides a simple API for uploading content to
Nos, and makes extensive use of Nos 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 SDK for Java, is thread safe.
Using TransferManager
to upload options to Nos is easy:
Credentials myCredentials = new BasicCredentials(...); TransferManager tx = new TransferManager(myCredentials); Upload myUpload = tx.upload(myBucket, myFile.getName(), myFile); while (myUpload.isDone() == false) { System.out.println("Transfer: " + myUpload.getDescription()); System.out.println(" - State: " + myUpload.getState()); System.out.println(" - Progress: " + myUpload.getProgress().getBytesTransfered()); // Do work while we wait for our upload to complete... Thread.sleep(500); }
Note: Transfers are stored in memory. If the JVM is restarted, previous transfers are no longer accessible. If needed, clean up any multipart uploads that are incomplete.
Constructor and Description |
---|
TransferManager(Credentials credentials)
Constructs a new
TransferManager and Nos client using the
specified security credentials. |
TransferManager(Nos nos)
Constructs a new
TransferManager , specifying the client to
use when making requests to Nos. |
TransferManager(Nos nos,
ThreadPoolExecutor threadPool)
Constructs a new
TransferManager specifying the client and
thread pool to use when making requests to Nos. |
Modifier and Type | Method and Description |
---|---|
void |
abortMultipartUploads(String bucketName,
Date date)
Aborts any multipart uploads that were initiated before the specified
date.
|
<X extends WebServiceRequest> |
appendUserAgent(X request,
String userAgent) |
Download |
download(GetObjectRequest getObjectRequest,
File file)
Schedules a new transfer to download data from Nos and save it to the
specified file.
|
Download |
download(String bucket,
String key,
File file)
Schedules a new transfer to download data from Nos and save it to the
specified file.
|
TransferManagerConfiguration |
getConfiguration()
Returns the configuration which specifies how this
TransferManager processes requests. |
Nos |
getNosClient()
Returns the underlying Nos client used to make requests to Nos.
|
void |
setConfiguration(TransferManagerConfiguration configuration)
Sets the configuration which specifies how this
TransferManager processes requests. |
void |
shutdownNow()
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 Nos.
|
Upload |
upload(String bucketName,
String key,
File file)
Schedules a new transfer to upload data to Nos.
|
Upload |
upload(String bucketName,
String key,
InputStream input,
ObjectMetadata objectMetadata)
Schedules a new transfer to upload data to Nos.
|
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.
|
public TransferManager(Credentials credentials)
TransferManager
and Nos client using the
specified security credentials.
TransferManager
and client objects may pool connections and
threads. Reuse TransferManager
and client objects and share
them throughout applications.
TransferManager and all client objects are thread safe.
credentials
- The security credentials to use when making authenticated
requests.public TransferManager(Nos nos)
TransferManager
, specifying the client to
use when making requests to Nos.
TransferManager
and client objects may pool connections and
threads. Reuse TransferManager
and client objects and share
them throughout applications.
TransferManager and all client objects are thread safe.
nos
- The client to use when making requests to Nos.public TransferManager(Nos nos, ThreadPoolExecutor threadPool)
TransferManager
specifying the client and
thread pool to use when making requests to Nos.
TransferManager
and client objects may pool connections and
threads. Reuse TransferManager
and client objects and share
them throughout applications.
TransferManager and all client objects are thread safe.
nos
- The client to use when making requests to Nos.threadPool
- The thread pool in which to execute requests.public void setConfiguration(TransferManagerConfiguration configuration)
TransferManager
processes requests.configuration
- The new configuration specifying how this
TransferManager
processes requests.public TransferManagerConfiguration getConfiguration()
TransferManager
processes requests.TransferManager
.public Nos getNosClient()
public Upload upload(String bucketName, String key, InputStream input, ObjectMetadata objectMetadata) throws ServiceException, ClientException
Schedules a new transfer to upload data to Nos. 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.
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 Nos.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.
ClientException
- If any errors are encountered in the client while making the
request or handling the response.ServiceException
- If any errors occurred in Nos while processing the request.public Upload upload(String bucketName, String key, File file) throws ServiceException, ClientException
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.
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.ClientException
- If any errors are encountered in the client while making the
request or handling the response.ServiceException
- If any errors occurred in Nos while processing the request.public Upload upload(PutObjectRequest putObjectRequest) throws ServiceException, ClientException
Schedules a new transfer to upload data to Nos. 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.
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.
ClientException
- If any errors are encountered in the client while making the
request or handling the response.ServiceException
- If any errors occurred in Nos 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.
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.ClientException
- If any errors are encountered in the client while making the
request or handling the response.ServiceException
- If any errors occurred in Nos 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.
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.ClientException
- If any errors are encountered in the client while making the
request or handling the response.ServiceException
- If any errors occurred in Nos while processing the request.public MultipleFileUpload uploadDirectory(String bucketName, String virtualDirectoryKeyPrefix, File directory, boolean includeSubdirectories)
Nos will overwrite any existing objects that happen to have the same key, just as when uploading individual files, so use with caution.
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 void abortMultipartUploads(String bucketName, Date date) throws ServiceException, ClientException
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.ServiceException
ClientException
public void shutdownNow()
Callers should also remember that uploaded parts from an interrupted
upload may not always be automatically cleaned up, but callers can use
abortMultipartUploads(String, Date)
to clean up any upload
parts.
public <X extends WebServiceRequest> X appendUserAgent(X request, String userAgent)
Copyright © 2017. All Rights Reserved.