Initial declaration of Cronet Async API.

BUG=409926

Review URL: https://codereview.chromium.org/520093002

Cr-Commit-Position: refs/heads/master@{#293345}

components/cronet.gypi

@@ -162,6 +162,11 @@
           'variables': {
             'java_in_dir': 'cronet/android/java',
             'javac_includes': [
+              '**/AsyncUrlRequest.java',
+              '**/AsyncUrlRequestException.java',
+              '**/AsyncUrlRequestFactory.java',
+              '**/AsyncUrlRequestListener.java',
+              '**/ResponseInfo.java',
               '**/ChunkedWritableByteChannel.java',
               '**/HttpUrlConnection*.java',
               '**/HttpUrlRequest*.java',
@@ -188,6 +193,7 @@
           'variables': {
             'java_in_dir': 'cronet/android/java',
             'javac_includes': [
+              '**/ChromiumAsyncUrlRequest.java',
               '**/ChromiumUrlRequest.java',
               '**/ChromiumUrlRequestContext.java',
               '**/ChromiumUrlRequestError.java',

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.
+
+package org.chromium.net;
+
+/**
+ * HTTP request (GET, PUT or POST).
+ * Note:  All methods must be called on the Executor passed in during creation.
+ */
+public abstract interface AsyncUrlRequest {
+    /**
+     * 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.
+     */
+
+    /**
+     * Sets the HTTP method verb to use for this request.
+     *
+     * <p>The default when this method is not called is "GET" if the request has
+     * no body or "POST" if it does.
+     *
+     * @param method Either "POST" or "PUT".
+     */
+    public void setHttpMethod(String method);
+
+    /**
+     * Adds a request header. Must be done before request has started.
+     *
+     * @param header Header name
+     * @param value Header value
+     */
+    public void addHeader(String header, String value);
+
+    /**
+     * 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 True if the request has been cancelled by the embedder.
+     * TBD(mmenke): False in all other cases (Including errors).
+     */
+    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).
+     *
+     * TBD: May need different pause behavior.
+     */
+    public void pause();
+
+    /**
+     * Returns True if paused. False if not paused or is cancelled.
+     * @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.
+     */
+}
+

components/cronet/android/java/src/org/chromium/net/AsyncUrlRequestException.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.
+
+package org.chromium.net;
+
+import java.io.IOException;
+
+/**
+ *
+ */
+public class AsyncUrlRequestException extends IOException {
+}

components/cronet/android/java/src/org/chromium/net/AsyncUrlRequestFactory.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.
+
+package org.chromium.net;
+
+import java.util.concurrent.Executor;
+
+/**
+ * A factory for {@link AsyncUrlRequest}'s, which uses the best HTTP stack
+ * available on the current platform.
+ */
+public abstract class AsyncUrlRequestFactory {
+    /**
+     * Creates an AsyncUrlRequest object. All AsyncUrlRequest functions must
+     * be called on the Executor's thread, and all callbacks will be called
+     * on the Executor's thread as well.
+     * createAsyncRequest itself may be called on any thread.
+     * @param url URL for the request.
+     * @param listener Callback interface that gets called on different events.
+     * @param executor Executor on which all callbacks will be called.
+     * @return new request.
+     */
+    public abstract AsyncUrlRequest createAsyncRequest(String url,
+            AsyncUrlRequestListener listener, Executor executor);
+}

components/cronet/android/java/src/org/chromium/net/AsyncUrlRequestListener.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.
+
+package org.chromium.net;
+
+import java.net.URL;
+import java.nio.ByteBuffer;
+
+/**
+ * Note:  All methods will be called on the thread of the Executor used during
+ * construction of the AsyncUrlRequest.
+ */
+public abstract interface AsyncUrlRequestListener {
+    /**
+     * Called before following redirects.  The redirect will automatically be
+     * followed, unless the request is paused or cancelled during this
+     * callback.  If the redirect response has a body, it will be ignored.
+     * This will only be called between start and onResponseStarted.
+     *
+     * @param request Request being redirected.
+     * @param info Response information.
+     * @param new_location Location where request is redirected.
+     */
+    public void onRedirect(AsyncUrlRequest request, ResponseInfo info,
+                           URL new_location);
+
+    /**
+     * Called when the final set of headers, after all redirects,
+     * is received. Can only be called once for each request.
+     *
+     * @param request Request that started to get response.
+     * @param info Response information.
+     */
+    public void onResponseStarted(AsyncUrlRequest request, ResponseInfo info);
+
+    /**
+     * Called whenever data is received.  The ByteBuffer remains
+     * valid only for the duration of the callback.  Or if the callback
+     * pauses the request, it remains valid until the request is resumed.
+     * Cancelling the request also invalidates the buffer.
+     *
+     * @param request Request that received data.
+     * @param byteBuffer Received data.
+     */
+    public void onDataReceived(AsyncUrlRequest request, ByteBuffer byteBuffer);
+
+    /**
+     * Called when request is complete, no callbacks will be called afterwards.
+     *
+     * @param request Request that is complete.
+     */
+    public void onComplete(AsyncUrlRequest request);
+
+    /**
+     * Can be called at any point between start() and onComplete().  Once
+     * called, no other functions can be called.  AsyncUrlRequestException
+     * provides information about error.
+     *
+     * @param request Request that received an error.
+     * @param error information about error.
+     */
+    public void onError(AsyncUrlRequest request,
+                        AsyncUrlRequestException error);
+}

components/cronet/android/java/src/org/chromium/net/ChromiumAsyncUrlRequest.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.
+
+package org.chromium.net;
+
+/**
+ * Async request using the native HTTP stack implementation.
+ */
+public class ChromiumAsyncUrlRequest implements AsyncUrlRequest {
+    @Override
+    public void setHttpMethod(String method) {
+
+    }
+
+    @Override
+    public void addHeader(String header, String value) {
+
+    }
+
+    @Override
+    public void start(AsyncUrlRequestListener listener) {
+
+    }
+
+    @Override
+    public void cancel() {
+
+    }
+
+    @Override
+    public boolean isCanceled() {
+        return false;
+    }
+
+    @Override
+    public void pause() {
+
+    }
+
+    @Override
+    public boolean isPaused() {
+        return false;
+    }
+
+    @Override
+    public void resume() {
+
+    }
+}

components/cronet/android/java/src/org/chromium/net/ResponseInfo.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.
+
+package org.chromium.net;
+
+import java.net.URL;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Contains basic information about a response. Sent to the embedder whenever
+ * headers are received.
+ */
+public abstract interface ResponseInfo {
+    /**
+     * Return the url the response is for (Not the original URL - after
+     * redirects, it's the new URL).
+     */
+    URL getUrl();
+
+    /**
+     *
+     * @return the url chain, including all redirects.  The originally
+     * requested URL is first.
+     */
+    URL[] getUrlChain();
+
+    /**
+     * Returns the HTTP status code.
+     */
+    int getHttpStatusCode();
+
+    /**
+     * Returns an unmodifiable map of the response-header fields and values.
+     * The null key is mapped to the HTTP status line for compatibility with
+     * HttpUrlConnection.
+     */
+    Map<String, List<String>> getAllHeaders();
+
+    /** True if the response came from the cache.  Requests that were
+     * revalidated over the network before being retrieved from the cache are
+     * considered cached.
+     */
+    boolean wasCached();
+
+    /**
+     *
+     * @return
+     */
+    boolean wasFetchedOverSPDY();
+
+    /**
+     *
+     * @return
+     */
+    boolean wasFetchedOverQUIC();
+};