90 lines
4.6 KiB
Java
90 lines
4.6 KiB
Java
// 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 {}
|
|
}
|