org.apache.jackrabbit.oak.api.blob.BlobAccessProvider Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.jackrabbit.oak.api.blob;
import java.net.URI;
import org.apache.jackrabbit.oak.api.Blob;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import org.osgi.annotation.versioning.ProviderType;
/**
* Extension interface applied to a class that indicates that the class
* implements the direct upload and direct download feature for {@link Blob}s.
*/
@ProviderType
public interface BlobAccessProvider {
/**
* Begin a transaction to perform a direct blob upload to a storage
* location. This method will throw {@link 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, {@link 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 {@link 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.
*
* @param 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.
* @param 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.
* @return A {@link BlobUpload} referencing this direct upload, or
* {@code null} if the underlying implementation doesn't support
* direct uploading.
* @throws IllegalArgumentException if {@code maxUploadSizeInBytes} is not
* a positive value, or if {@code 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.
*/
@Nullable
BlobUpload initiateBlobUpload(long maxUploadSizeInBytes,
int maxNumberOfURIs)
throws IllegalArgumentException;
/**
* Complete a transaction for uploading a blob to a storage location via
* direct blob upload.
*
* This requires an {@code uploadToken} that can be obtained from the
* returned {@link BlobUpload} from a previous call to {@link
* #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.
*
* @param uploadToken the upload token from a {@link BlobUpload} object
* returned from a previous call to {@link
* #initiateBlobUpload(long, int)}.
* @return The {@link Blob} that was created, or {@code null} if the object
* could not be created.
* @throws IllegalArgumentException if the {@code uploadToken} is null,
* empty, or cannot be parsed or is otherwise invalid, e.g. if the
* included signature does not match.
*/
@Nullable
Blob completeBlobUpload(@NotNull String uploadToken)
throws IllegalArgumentException;
/**
* Obtain a download URI for a {@link Blob}. This is usually a signed URI
* that can be used to directly download the blob corresponding to the
* provided {@link Blob}.
*
* A caller must specify a {@link BlobDownloadOptions} instance. The
* implementation will attempt to apply the specified {@code
* 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 {@code downloadOptions}.
* The caller may also use a default instance obtained via {@link
* BlobDownloadOptions#DEFAULT} in which case the caller is indicating that
* the default behavior of the service provider is acceptable.
*
* @param blob The {@link Blob} to be downloaded.
* @param downloadOptions A {@link BlobDownloadOptions} instance that
* specifies any download options to be used for the download URI.
* @return A URI to download the blob directly or {@code null} if the blob
* cannot be downloaded directly.
*/
@Nullable
URI getDownloadURI(@NotNull Blob blob,
@NotNull BlobDownloadOptions downloadOptions);
}