[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.nio.ByteBuffer;
+
+/**
+ * Interface allowing the embedder to provide an upload body to 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.
+ *
+ * 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 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 uploadDataSink:
+     * onReadSucceeded on success or onError on failure. Neither read nor rewind
+     * will be called until one of those methods or the other is called. Even if
+     * the associated 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.
+     *
+     * @param uploadDataSink The object to notify when the read has completed,
+     *            successfully or otherwise.
+     * @param byteBuffer The buffer to copy the read bytes into.
+     */
+    public void read(UploadDataSink uploadDataSink, ByteBuffer byteBuffer);
+
+    /**
+     * Rewinds upload data. Each call must be followed be a single
+     * call, either synchronous or asynchronous, to uploadDataSink:
+     * onRewindSucceeded on success or onError on failure. Neither read nor
+     * rewind will be called until one of those methods or the other is called.
+     * Even if the associated 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.
+     *
+     * If rewinding is not supported, this should call onError. 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.
+     */
+    public void rewind(UploadDataSink uploadDataSink);
+}