[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

[miloslav, 2015/02/17 18:14:01]

Need to insert <p> in the beginning of paragraphs.

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

Done.

+ * 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 #onReadSucceeded} on success or

[pauljensen, 2015/02/17 15:55:40]

Do these @links work?  I thought you could drop the class name (i.e. {@link
#blah} instead of {@link thing#blah} ) only when the function was in the same
class?

[xunjieli, 2015/02/17 17:56:07]

Done. You are right, It should be prefixed by class. I just generated javadoc
and confirmed that {@link UploadDataProvider#onReadSucceeded} correctly links.

+     * {@link #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.
+     *
+     * @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);

[miloslav, 2015/02/17 18:14:00]

Maybe returning an int code instead of having to call onReadSucceeded, etc,
would be safer? Could also be declared "throws IOException". This way, Cronet
will not have to rely on implementors actually calling the appropriate method
and the compiler will help clients do the right thing.

[mmenke, 2015/02/17 20:25:49]

I'm very reluctant to force embedders to use a blocking API to obtain data they
aren't ready to give us immediately.

[mmenke, 2015/02/17 20:29:33]

Oh, and I'm fine with adding "throws IOException".  We already catch runtime
exceptions that it throws, anyways.  Allowing IOExceptions, too, makes sense.

+
+    /**
+     * Rewinds upload data. Each call must be followed be a single
+     * call, either synchronous or asynchronous, to {@code uploadDataSink}:
+     * {@link #onRewindSucceeded} on success or {@link #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.
+     *
+     * If rewinding is not supported, this should call {@link #onRewindError}.

[miloslav, 2015/02/17 18:14:01]

<p>

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

Done.

+     * 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);

[miloslav, 2015/02/17 18:14:01]

Similarly, maybe throws an IOException and returning some value, so that people
don't just forget and leave it with empty body.

+}