@ProviderType
public interface BinaryUpload
JackrabbitValueFactory.initiateBinaryUpload(long, int)
. A high-level
overview of the process can be found in JackrabbitValueFactory
.
Note that although the API allows URI schemes other than "http(s)", the upload functionality is currently only defined for HTTP.
A caller usually needs to pass the information provided by this interface to a remote client that is in possession of the actual binary, who then has to upload the binary using HTTP according to the logic described below. A remote client is expected to support multi-part uploads as per the logic described below, in case multiple URIs are returned.
Once a remote client finishes uploading the binary data, the application must
be notified and must then call
JackrabbitValueFactory.completeBinaryUpload(String)
to complete the
upload. This completion requires the exact upload token obtained from
getUploadToken()
.
Please be aware that if the size passed to
JackrabbitValueFactory.initiateBinaryUpload(long, int)
was an
estimation, but the actual binary is larger, there is no guarantee the
upload will be possible using all getUploadURIs()
and the
getMaxPartSize()
. In such cases, the application should restart the
transaction using the correct size.
fileSize
: the actual binary size (must be known at this
point)minPartSize
: the value from getMinPartSize()
maxPartSize
: the value from getMaxPartSize()
numUploadURIs
: the number of entries in getUploadURIs()
uploadURIs
: the entries in getUploadURIs()
partSize
: the part size to be used in the upload (to be
determined in the algorithm)(fileSize / maxPartSize) > numUploadURIs
, then the
client cannot proceed and will have to request a new set of URIs
with the right fileSize as maxSize
fileSize < minPartSize
, then take the first provided
upload URI to upload the entire binary, with
partSize = fileSize
partSize
can be chosen, under the condition that all of these are
true:
partSize >= minPartSize
partSize <= maxPartSize
(unless maxPartSize = -1
meaning unlimited)partSize > (fileSize / numUploadURIs)
partSize
to use for all parts except the last would be calculated using:
partSize = (fileSize + numUploadURIs - 1) / numUploadURIs
partSize
, for each segment take the
next URI from uploadURIs
(strictly in order), proceed with a standard
HTTP PUT for each, and for the last part use whatever segment size is left
upload token
, and the application will call JackrabbitValueFactory.completeBinaryUpload(String)
with the token
{ "uploadToken": "aaaa-bbbb-cccc-dddd-eeee-ffff-gggg-hhhh", "minPartSize": 10485760, "maxPartSize": 104857600, "uploadURIs": [ "http://server.com/upload/1", "http://server.com/upload/2", "http://server.com/upload/3", "http://server.com/upload/4" ] }
Modifier and Type | Method and Description |
---|---|
long |
getMaxPartSize()
Return the largest possible part size in bytes.
|
long |
getMinPartSize()
Return the smallest possible part size in bytes.
|
@NotNull String |
getUploadToken()
Returns a token identifying this upload.
|
@NotNull Iterable<URI> |
getUploadURIs()
Returns a list of URIs that can be used for uploading binary data
directly to a storage location in one or more parts.
|
@NotNull @NotNull Iterable<URI> getUploadURIs()
Remote clients must support multi-part uploading as per the
upload algorithm described above. Clients
are not necessarily required to use all of the URIs provided. A client
may choose to use fewer, or even only one of the URIs. However, it must
always ensure the part size is between getMinPartSize()
and
getMaxPartSize()
. These can reflect strict limitations of the
storage provider.
Regardless of the number of URIs used, they must be consumed in sequence, without skipping any, and the order of parts the original binary is split into must correspond exactly with the order of URIs.
For example, if a client wishes to upload a binary in three parts and there are five URIs returned, the client must use the first URI to upload the first part, the second URI to upload the second part, and the third URI to upload the third part. The client is not required to use the fourth and fifth URIs. However, using the second URI to upload the third part may result in either an upload failure or a corrupted upload; likewise, skipping the second URI to use subsequent URIs may result in either an upload failure or a corrupted upload.
While the API supports multi-part uploading via multiple upload URIs, implementations are not required to support multi-part uploading. If the underlying implementation does not support multi-part uploading, a single URI will be returned regardless of the size of the data being uploaded.
Security considerations:
long getMinPartSize()
Note that the API offers no guarantees that using this minimal part size
is possible with the number of available getUploadURIs()
. This
might not be the case if the binary is too large. Please refer to the
upload algorithm for the correct use of
this value.
long getMaxPartSize()
The API guarantees that a client can split the binary of the requested
size using this maximum part size and there will be sufficient URIs
available in getUploadURIs()
. Please refer to the
upload algorithm for the correct use of
this value.
@NotNull @NotNull String getUploadToken()
JackrabbitValueFactory.completeBinaryUpload(String)
.
The format of this string is implementation-dependent. Implementations must ensure that clients cannot guess tokens for existing binaries.
Copyright © 2004–2020 The Apache Software Foundation. All rights reserved.