[Cronet] Upload support for async APIs

components/cronet/android/java/src/org/chromium/net/UploadDataProvider.java

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// 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.IOException;
+import java.nio.ByteBuffer;
+
+/**
+ * Interface 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 interface UploadDataProvider {
+    /**
+     * @return if this is a non-chunked upload, returns the length of the
+     *         upload. Must always return -1 if this is a chunked upload.
+     */
+    public long getLength();
+
+    /**
+     * 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 cancelled, 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
+     * cancelled.

[mmenke, 2015/02/18 17:08:41]

Maybe "request being cancelled" -> "request failing" or "request being errored
out"?  Same for the rewind docs.

[xunjieli, 2015/02/19 14:59:11]

Done.

+     *
+     * @param uploadDataSink The object to notify when the read has completed,
+     *            successfully or otherwise.
+     * @param byteBuffer The buffer to copy the read bytes into.
+     * @throws IOException if any IOException occurred during the process.
+     */
+    public void read(UploadDataSink uploadDataSink, 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 cancelled, 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
+     * cancelled.
+     *
+     * <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.
+     */
+    public void rewind(UploadDataSink uploadDataSink)
+            throws IOException;
+}