/*
 * 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.plugins.blob.datastore.directaccess;

import java.net.URI;
import java.util.Collection;

import org.jetbrains.annotations.NotNull;

public interface DataRecordUpload {
    /**
     * Returns a token that uniquely identifies this upload.  This token must be
     * provided in a subsequent call to {@link
     * DataRecordAccessProvider#completeDataRecordUpload(String)}.
     *
     * @return The unique upload token for this upload.
     */
    @NotNull
    String getUploadToken();

    /**
     * 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 uploadPartURIs.  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 parts
     * in order to upload the entire binary with the number of URIs provided.
     * <p>
     * Note that some backends have lower-bound limits for the size of a part of
     * a multi-part upload.
     *
     * @return The smallest part size acceptable, for multi-part uploads.
     */
    long getMinPartSize();

    /**
     * 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
     * that those provided, SO LONG AS the file being uploaded is not larger
     * than the maxSize specified in the original call.
     * <p>
     * A smaller size may also be used so long as it exceeds the value returned
     * by {@link #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 {@link #getMaxPartSize()} will work without using
     * more URIs than those available in the Collection returned by {@link
     * #getUploadURIs()};
     * <p>
     * If a client calls {@link
     * DataRecordAccessProvider#initiateDataRecordUpload(long, int)} with a
     * value of {@code maxUploadSizeInBytes} 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.
     * <p>
     * Note that some backends have upper-bound limits for the size of a part of
     * a multi-part upload.
     *
     * @return The largest part size acceptable, for multi-part uploads.
     */
    long getMaxPartSize();

    /**
     * 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 of maxNumberOfURIs in a call to
     *    {@link DataRecordAccessProvider#initiateDataRecordUpload(long, int)},
     *    OR
     *  - If the implementing data store does not support multi-part uploading,
     *    OR
     *  - If the client-specified value for maxUploadSizeInBytes in a call to
     *    {@link DataRecordAccessProvider#initiateDataRecordUpload(long, int)}
     *    is less than or equal to the minimum 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 up to the entire
     * collection of URIs provided.
     * <p>
     * Note that ordering matters; URIs should be consumed in sequence and not
     * skipped.
     *
     * @return ordered collection of URIs to be consumed in sequence.
     */
    @NotNull
    Collection<URI> getUploadURIs();
}