org.apache.jackrabbit.oak.api.blob

Interface BlobAccessProvider

@ProviderType
public interface BlobAccessProvider

Extension interface applied to a class that indicates that the class implements the direct upload and direct download feature for Blobs.

Method Summary

Modifier and Type	Method and Description
@Nullable Blob	completeBlobUpload(@NotNull String uploadToken) Complete a transaction for uploading a blob to a storage location via direct blob upload.
@Nullable URI	getDownloadURI(@NotNull Blob blob, @NotNull BlobDownloadOptions downloadOptions) Obtain a download URI for a Blob.
@Nullable BlobUpload	initiateBlobUpload(long maxUploadSizeInBytes, int maxNumberOfURIs) Begin a transaction to perform a direct blob upload to a storage location.

Method Detail

initiateBlobUpload

@Nullable
@Nullable BlobUpload initiateBlobUpload(long maxUploadSizeInBytes,
                                                  int maxNumberOfURIs)
                                           throws IllegalArgumentException

Begin a transaction to perform a direct blob upload to a storage location. This method will throw IllegalArgumentException if no valid upload can be arranged with the arguments specified. E.g. the max upload size specified divided by the number of URIs requested indicates the minimum size of each upload. If that size exceeds the maximum upload size supported by the service provider, IllegalArgumentException is thrown.

Each service provider has specific limitations with regard to maximum upload sizes, maximum overall blob sizes, numbers of URIs in multi-part uploads, etc. which can lead to IllegalArgumentException being thrown. You should consult the documentation for your specific service provider for details.

Beyond service provider limitations, the implementation may also choose to enforce its own limitations and may throw this exception based on those limitations. Configuration may also be used to set limitations so this exception may be thrown when configuration parameters are exceeded.

Parameters:

maxUploadSizeInBytes - the largest size of the blob to be uploaded, in bytes, based on the caller's best guess. If the actual size of the file to be uploaded is known, that value should be used.

maxNumberOfURIs - the maximum number of URIs the client is able to accept. If the client does not support multi-part uploading, this value should be 1. Note that the implementing class is not required to support multi-part uploading so it may return only a single upload URI regardless of the value passed in for this parameter. If the client is able to accept any number of URIs, a value of -1 may be passed in to indicate that the implementation is free to return as many URIs as it desires.

Returns:

A BlobUpload referencing this direct upload, or null if the underlying implementation doesn't support direct uploading.

Throws:

IllegalArgumentException - if maxUploadSizeInBytes is not a positive value, or if maxNumberOfURIs is not either a positive value or -1, or if the upload cannot be completed as requested, due to a mismatch between the request parameters and the capabilities of the service provider or the implementation.

completeBlobUpload

@Nullable
@Nullable Blob completeBlobUpload(@NotNull
                                            @NotNull String uploadToken)
                                     throws IllegalArgumentException

Complete a transaction for uploading a blob to a storage location via direct blob upload.

This requires an uploadToken that can be obtained from the returned BlobUpload from a previous call to initiateBlobUpload(long, int). This token is required to complete the transaction for an upload to be valid and complete. The token includes encoded data about the transaction and may include a signature that will be verified by the implementation.

Parameters:

uploadToken - the upload token from a BlobUpload object returned from a previous call to initiateBlobUpload(long, int).

Returns:

The Blob that was created, or null if the object could not be created.

Throws:

IllegalArgumentException - if the uploadToken is null, empty, or cannot be parsed or is otherwise invalid, e.g. if the included signature does not match.

getDownloadURI

@Nullable
@Nullable URI getDownloadURI(@NotNull
                                       @NotNull Blob blob,
                                       @NotNull
                                       @NotNull BlobDownloadOptions downloadOptions)

Obtain a download URI for a Blob. This is usually a signed URI that can be used to directly download the blob corresponding to the provided Blob.

A caller must specify a BlobDownloadOptions instance. The implementation will attempt to apply the specified downloadOptions to the subsequent download. For example, if the caller knows that the URI refers to a specific type of content, the caller can specify that content type by setting it in the downloadOptions. The caller may also use a default instance obtained via BlobDownloadOptions.DEFAULT in which case the caller is indicating that the default behavior of the service provider is acceptable.

Parameters:

blob - The Blob to be downloaded.

downloadOptions - A BlobDownloadOptions instance that specifies any download options to be used for the download URI.

Returns:

A URI to download the blob directly or null if the blob cannot be downloaded directly.