// Copyright 2015 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package android.net.http;

import androidx.annotation.NonNull;

import java.io.Closeable;
import java.io.IOException;
import java.nio.ByteBuffer;

/**
 * Abstract class allowing the embedder to provide an upload body to {@link UrlRequest}. It supports
 * both non-chunked (size known in advanced) and chunked (size not known in advance) uploads. Be
 * aware that not all servers support chunked uploads.
 *
 * <p>An upload is either always chunked, across multiple uploads if the data
 * ends up being sent more than once, or never chunked.
 */
public abstract class UploadDataProvider implements Closeable {
    /**
     * If this is a non-chunked upload, returns the length of the upload. Must always return -1 if
     * this is a chunked upload.
     *
     * @return the length of the upload for non-chunked uploads, -1 otherwise.
     * @throws IOException if any IOException occurred during the process.
     */
    public abstract long getLength() throws IOException;

    /**
     * Reads upload data into {@code byteBuffer}. Upon completion, the buffer's position is updated
     * to the end of the bytes that were read. The buffer's limit is not changed. Each call of this
     * method must be followed be a single call, either synchronous or asynchronous, to {@code
     * uploadDataSink}: {@link UploadDataSink#onReadSucceeded} on success or {@link
     * UploadDataSink#onReadError} on failure. Neither read nor rewind will be called until one of
     * those methods or the other is called. Even if the associated {@link UrlRequest} is canceled,
     * one or the other must still be called before resources can be safely freed. Throwing an
     * exception will also result in resources being freed and the request being errored out.
     *
     * @param uploadDataSink The object to notify when the read has completed, successfully or
     * otherwise.
     * @param byteBuffer The buffer to copy the read bytes into. Do not change byteBuffer's limit.
     * @throws IOException if any IOException occurred during the process. {@link
     * UrlRequest.Callback#onFailed} will be called with the thrown exception set as the cause of
     * the
     * {@link CallbackException}.
     */
    public abstract void read(@NonNull UploadDataSink uploadDataSink,
            @NonNull ByteBuffer byteBuffer) throws IOException;

    /**
     * Rewinds upload data. Each call must be followed be a single call, either synchronous or
     * asynchronous, to {@code uploadDataSink}: {@link UploadDataSink#onRewindSucceeded} on success
     * or
     * {@link UploadDataSink#onRewindError} on failure. Neither read nor rewind will be called until
     * one of those methods or the other is called. Even if the associated {@link UrlRequest} is
     * canceled, one or the other must still be called before resources can be safely freed.
     * Throwing an exception will also result in resources being freed and the request being errored
     * out.
     *
     * <p>If rewinding is not supported, this should call
     * {@link UploadDataSink#onRewindError}. Note that rewinding is required to follow redirects
     * that preserve the upload body, and for retrying when the server times out stale sockets.
     *
     * @param uploadDataSink The object to notify when the rewind operation has completed,
     * successfully or otherwise.
     * @throws IOException if any IOException occurred during the process. {@link
     * UrlRequest.Callback#onFailed} will be called with the thrown exception set as the cause of
     * the
     * {@link CallbackException}.
     */
    public abstract void rewind(@NonNull UploadDataSink uploadDataSink) throws IOException;

    /**
     * Called when this UploadDataProvider is no longer needed by a request, so that resources (like
     * a file) can be explicitly released.
     *
     * @throws IOException if any IOException occurred during the process. This will cause the
     *         request
     * to fail if it is not yet complete; otherwise it will be logged.
     */
    @Override
    public void close() throws IOException {}
}