Interface BlobUpload
-
@ProviderType public interface BlobUpload
An object containing information needed to complete a direct binary upload. A client wishing to perform a direct binary upload first callsBlobAccessProvider.initiateBlobUpload(long, int)
which returns an instance of this type. The client then uses the provided URIs viagetUploadURIs()
to upload the binary. After this is done, the client callsBlobAccessProvider.completeBlobUpload(String)
passing in the upload token string obtained from this object viagetUploadToken()
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description long
getMaxPartSize()
The largest part size the client can send in a multi-part upload.long
getMinPartSize()
The smallest part size the client can send in a multi-part upload (not counting the final part).@NotNull java.lang.String
getUploadToken()
Returns a token that uniquely identifies this upload.@NotNull java.util.Collection<java.net.URI>
getUploadURIs()
Returns a collection of direct-writable upload URIs for uploading a file, or file part in the case of multi-part uploading.
-
-
-
Method Detail
-
getUploadToken
@NotNull @NotNull java.lang.String getUploadToken()
Returns a token that uniquely identifies this upload. This token must be provided in a subsequent call toBlobAccessProvider.completeBlobUpload(String)
.- Returns:
- The unique upload token for this upload.
-
getMinPartSize
long getMinPartSize()
The smallest part size the client can send in a multi-part upload (not counting the final part). There is no guarantee made that splitting the binary into parts of this size can complete the full upload without exhausting the full supply of uploadURIs. In other words, clients wishing to perform a multi-part upload MUST split the binary into parts of at least this size, in bytes, but clients may need to use larger part sizes in order to upload the entire binary with the number of URIs provided.Note that some backends have lower-bound limits for the size of a part of a multi-part upload. You should consult the documentation for your specific service provider for details.
- Returns:
- The smallest part size acceptable, for multi-part uploads.
-
getMaxPartSize
long getMaxPartSize()
The largest part size the client can send in a multi-part upload. The API guarantees that splitting the file into parts of this size will allow the client to complete the multi-part upload without requiring more URIs than those provided, SO LONG AS the file being uploaded is not larger than themaxUploadSizeInBytes
specified in the original call.A smaller upload part size may also be used so long as it exceeds the value returned by
getMinPartSize()
. Such smaller values may be more desirable for clients who wish to tune uploads to match network conditions; however, the only guarantee offered by the API is that using parts of the size returned by this method will work without using more URIs than those available in the Collection returned bygetUploadURIs()
.If a client calls
BlobAccessProvider.initiateBlobUpload(long, int)
with a value ofmaxUploadSizeInBytes
that ends up being smaller than the actual size of the binary to be uploaded, it may not be possible to complete the upload with the URIs provided. The client should initiate the transaction again with the correct size.Note that some backends have upper-bound limits for the size of a part of a multi-part upload. You should consult the documentation for your specific service provider for details.
- Returns:
- The largest part size acceptable, for multi-part uploads.
-
getUploadURIs
@NotNull @NotNull java.util.Collection<java.net.URI> getUploadURIs()
Returns a collection of direct-writable upload URIs for uploading a file, or file part in the case of multi-part uploading. This collection may contain only a single URI in the following cases: - If the client requested 1 as the value ofmaxNumberOfURIs
in a call toBlobAccessProvider.initiateBlobUpload(long, int)
, OR - If the implementing data store does not support multi-part uploading, OR - If the client-specified value formaxUploadSizeInBytes
in a call toBlobAccessProvider.initiateBlobUpload(long, int)
is less than or equal to the minimum supported size of a multi-part upload part.If the collection contains only a single URI the client should treat that URI as a direct single-put upload and write the entire binary to the single URI. Otherwise the client may choose to consume any number of URIs in the collection, up to the entire collection of URIs provided.
Note that ordering matters; URIs should be consumed in sequence and should not be skipped.
- Returns:
- ordered collection of URIs to be consumed in sequence.
-
-