Initial declaration of Cronet Async API.

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

+// Copyright 2014 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.

[mmenke, 2014/09/02 19:48:03]

nit:  Blank line after license header.

[mef, 2014/09/03 20:58:57]

Done.

+package org.chromium.net;
+
+import java.nio.ByteBuffer;
+
+// Note:  All methods must be called on the executor passed in during creation.

[mmenke, 2014/09/02 19:48:03]

nit:  Executor

[mef, 2014/09/03 20:58:58]

Done.

+public abstract interface AsyncUrlRequest {

[mmenke, 2014/09/02 19:48:03]

Maybe some class level description?

[mef, 2014/09/03 20:58:58]

Done.

+    /**
+     * Methods to set the request body.  Could instead use a single method that
+     * takes a class, and three implementations of that class, but this allows
+     * file/string bodies to easily be handled C++-side.
+     */
+
+    /**
+     * Set request body using a constant ByteBuffer.
+     * Note:  Not sure if taking another type would be better.
+     * @param buffer
+     */
+    public void setRequestBodyByteBuffer(ByteBuffer buffer);

[mmenke, 2014/09/02 19:48:03]

Let's get rid of all the request body stuff - I think it's better using a
separate class for this (Which is what the drafts I've been playing around with
do).

[mef, 2014/09/03 20:58:58]

Done.

+
+    /**
+     * Set request body using a file.  File must not be modified until
+     * request is finished.
+     * TODO(mmenke):  After cancelling, file won’t be closed instantly.
+     * Figure out how to better handle it (In case someone wants to delete
+     * the file).
+     * @param filePath
+     */
+    public void setRequestBodyFile(String filePath);
+
+    /**
+     * The request body will be passed to the AsyncUrlRequest as needed,
+     * and uploaded using chunked encoding, since the length may not be known.
+     */
+    public void setStreamRequestBody();
+
+    /**
+     * Appends data to the body, when setStreamRequestBody is called.  Can be
+     * called at any point before the request is cancelled,
+     * fails with an error, or onResponseStarted is called on the listener.
+     * The request takes ownership of the buffer, and will delete it once the
+     * data is sent.  While the request will call the listener’s
+     * needUploadData method when all appended data has been uploaded,
+     * there’s no need for the embedder to wait for that callback before
+     * appending more data.
+     * If the request retries, or is redirected, the embedder must replay
+     * the original data. See AsyncUrlRequestListener for those methods.
+     * @param buffer
+     */
+    public void appendBodyData(ByteBuffer buffer);
+
+    /**
+     * Called when the last bytes to be uploaded have been appended with
+     * appendBodyData.
+     */
+    public void bodyComplete();
+
+    /**
+     * More setters go here.  They may only be called before start (Maybe
+     * also allow during redirects).  Could optionally instead use arguments
+     * to URLRequestFactory when creating the request.
+     */
+
+    /**
+     * Starts the request, all callbacks go to listener.
+     * @param listener
+     */
+    public void start(AsyncUrlRequestListener listener);
+
+    /**
+     * Can be called at any time.
+     */
+    public void cancel();
+
+    /**
+     *
+     * @return

[mmenke, 2014/09/02 19:48:03]

@return {boolean} true if the request has been cancelled by the embedder.  False
in all other cases (Including errors).

Hrm...  I wonder if we really need this method.

[mef, 2014/09/03 20:58:58]

Are you sure about error case? What would happen then?

+     */
+    public boolean isCanceled();
+
+    /**
+     * Can be called at any time, but the request may continue behind the
+     * scenes, depending on when it’s called.  None of the listener’s methods
+     * will be called while paused, until and unless the request is resumed.
+     * (Note:  This allows us to have more than one ByteBuffer in flight,
+     * if we want, as well as allow pausing at any point).
+     */
+    public void pause();

[mmenke, 2014/09/02 19:48:03]

I want to take a little extra time to think about this.  It seems like there are
3 ways to handle this:

1) Only pause when requests, like this.
2) Always pause, and require the embedder to explicitly continue the request.
3) Take a return value when passing along data, and rely on the embedded to
resume only if a request is paused.  This is how the network stack works
internally.

I think that in terms of complexity for the embedder, this approach is simplest.
 In approach 2, everyone has to worry about resuming the request in ever
callback, which seems like a bit of a pain.  In approach 3, rather than having
every callback (On receive header, on redirect, on body data receive) all have
their own return value to handle pausing, and maybe their own resume functions
as well, we just have one pause function, which works at any point.

One the downside, uploads can't work in this fashion, they instead have to work
like 2) or 3).  We also need more JNI calls when the embedder pauses than in 2)
or 3), though 2) has more JNI calls in the never pause case.

[mef, 2014/09/03 20:58:58]

Acknowledged.

[mmenke, 2014/09/03 21:19:19]

Wow, that's a mess.  I really should be more careful about typos.

+
+    /**
+     * Returns false if cancelled (Or not paused, of course).
+     * @return
+     */
+    public boolean isPaused();
+
+    /**
+     * When resuming, any pending callback to the listener will be called
+     * asynchronously.
+     */
+    public void resume();
+
+    /**
+     * Note:  There are deliberately no accessors for the results of the request
+     * here.  Having none removes any ambiguity over when they are populated,
+     * particularly in the redirect case.
+     */
+}
+