org.apache.jackrabbit.oak.plugins.blob.datastore.directaccess

Interface DataRecordAccessProvider

All Known Subinterfaces:

ConfigurableDataRecordAccessProvider

All Known Implementing Classes:

AzureDataStore, S3DataStore

public interface DataRecordAccessProvider

Method Summary

Modifier and Type	Method and Description
@NotNull DataRecord	completeDataRecordUpload(@NotNull String uploadToken) Completes the transaction to perform a direct binary upload.
@Nullable URI	getDownloadURI(@NotNull DataIdentifier identifier, @NotNull DataRecordDownloadOptions downloadOptions) Return a URI for directly reading the binary associated with the provided DataRecord.
@Nullable DataRecordUpload	initiateDataRecordUpload(long maxUploadSizeInBytes, int maxNumberOfURIs) Begin a transaction to perform a direct binary upload to the storage location.
@Nullable DataRecordUpload	initiateDataRecordUpload(long maxUploadSizeInBytes, int maxNumberOfURIs, DataRecordUploadOptions options) Begin a transaction to perform a direct binary upload to the storage location.

Method Detail

getDownloadURI

@Nullable
@Nullable URI getDownloadURI(@NotNull
                                       @NotNull DataIdentifier identifier,
                                       @NotNull
                                       @NotNull DataRecordDownloadOptions downloadOptions)

Return a URI for directly reading the binary associated with the provided DataRecord.

The caller must provide a DataRecordDownloadOptions instance that will be used by the implementation to specify options on the download. This can be obtained from a BlobDownloadOptions instance by calling DataRecordDownloadOptions.fromBlobDownloadOptions(BlobDownloadOptions), or to accept the service provider default behavior a caller can simply use DataRecordDownloadOptions.DEFAULT.

Parameters:

identifier - The DataIdentifier for the DataRecord containing the binary to be read via direct download.

downloadOptions - A DataRecordDownloadOptions instance used to specify any download options that should be set on this download.

Returns:

A URI for directly reading the binary, or null if the URI cannot be generated, for example if the capability is disabled by configuration or if a service provider error occurs.

initiateDataRecordUpload

@Nullable
@Nullable DataRecordUpload initiateDataRecordUpload(long maxUploadSizeInBytes,
                                                              int maxNumberOfURIs)
                                                       throws IllegalArgumentException,
                                                              DataRecordUploadException

Begin a transaction to perform a direct binary upload to the storage location.

Parameters:

maxUploadSizeInBytes - - the largest size of the binary 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 caller 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. A caller may also pass in -1 to indicate that it is able to accept any number of URIs. Any other negative number or 0 may result in IllegalArgumentException.

Returns:

A DataRecordUpload referencing this direct upload, or null if the implementation does not support direct upload.

Throws:

IllegalArgumentException - if the service provider or implementation cannot support the requested upload.

DataRecordUploadException - if the upload cannot be completed as requested.

initiateDataRecordUpload

@Nullable
@Nullable DataRecordUpload initiateDataRecordUpload(long maxUploadSizeInBytes,
                                                              int maxNumberOfURIs,
                                                              DataRecordUploadOptions options)
                                                       throws IllegalArgumentException,
                                                              DataRecordUploadException

Begin a transaction to perform a direct binary upload to the storage location.

Parameters:

maxUploadSizeInBytes - - the largest size of the binary 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 caller 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. A caller may also pass in -1 to indicate that it is able to accept any number of URIs. Any other negative number or 0 may result in IllegalArgumentException.

options - - a DataRecordUploadOptions instance containing any caller-specified options for upload URI generation.

Returns:

A DataRecordUpload referencing this direct upload, or null if the implementation does not support direct upload.

Throws:

IllegalArgumentException - if the service provider or implementation cannot support the requested upload.

DataRecordUploadException - if the upload cannot be completed as requested.

completeDataRecordUpload

@NotNull
@NotNull DataRecord completeDataRecordUpload(@NotNull
                                                      @NotNull String uploadToken)
                                               throws IllegalArgumentException,
                                                      DataRecordUploadException,
                                                      DataStoreException

Completes the transaction to perform a direct binary upload. This method verifies that the uploaded binary has been created and is now referenceable. For some providers doing multi-part upload, this also completes the multi-part upload process if a multi-part upload was performed.

Parameters:

uploadToken - The upload token identifying this direct upload transaction, as returned in the DataRecordUpload object resulting from a call to initiateDataRecordUpload(long, int).

Returns:

A DataRecord for the uploaded binary.

Throws:

IllegalArgumentException - if the uploadToken is null, empty, or otherwise invalid.

DataRecordUploadException - if the object written can't be found by the service provider.

DataStoreException - if the object written can't be found by the DataStore.