// 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 org.chromium.net;

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(UploadDataSink uploadDataSink, ByteBuffer byteBuffer)
            throws IOException;

    /**
     * Rewinds upload data to the beginning. Invoked when Cronet requires the upload data
     * provider to be in an equivalent state to as if {@link #read} was never called yet.
     *
     * <p>To signal that the operation has finished, implementations of this function must call
     * {@link UploadDataSink#onRewindSucceeded} to indicate success, or
     * {@link UploadDataSink#onRewindError} on failure. 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 from the method is equivalent to calling {@code onRewindError}.
     * If rewinding is not supported (for instance, if reading from a one-off stream), this
     * should call {@link UploadDataSink#onRewindError} immediately.
     *
     * <p>The implementer can safely assume that neither {@link #read} nor a concurrent
     * {@link #rewind} call will be issued until they notify the sink that rewinding has finished,
     * as described in the previous paragraph.
     *
     * <p>This method is used internally by Cronet if the body needs to be uploaded multiple times. This
     * can occur in many different situations, for instance when following redirects, or when retrying
     * requests after a timeout or a network disconnect. Note that while implementing rewinding is
     * generally optional, requests which end up requiring it will fail unless rewinding is implemented.
     *
     * @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(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 {}
}