Cronet API Refactoring

components/cronet/android/java/src/org/chromium/net/impl/BidirectionalStreamBuilderImpl.java

+// Copyright 2016 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.impl;
+
+import android.annotation.SuppressLint;
+import android.support.annotation.IntDef;
+
+import org.chromium.net.BidirectionalStream;
+import org.chromium.net.CronetEngine;
+import org.chromium.net.ExperimentalBidirectionalStream;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.AbstractMap;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Map;
+import java.util.concurrent.Executor;
+
+/**
+ * Implementation of {@link ExperimentalBidirectionalStream.Builder}.
+ */
+public class BidirectionalStreamBuilderImpl extends ExperimentalBidirectionalStream.Builder {
+    // All fields are temporary storage of BidirectionalStream configuration to be
+    // copied to BidirectionalStream.
+
+    // CronetEngine to create the stream.
+    private final CronetEngineBase mCronetEngine;
+    // URL to request.
+    private final String mUrl;
+    // Callback to receive progress callbacks.
+    private final BidirectionalStream.Callback mCallback;
+    // Executor on which callbacks will be invoked.
+    private final Executor mExecutor;
+    // List of request headers, stored as header field name and value pairs.
+    private final ArrayList<Map.Entry<String, String>> mRequestHeaders = new ArrayList<>();
+
+    // HTTP method for the request. Default to POST.
+    private String mHttpMethod = "POST";
+    // Priority of the stream. Default is medium.
+    @StreamPriority
+    private int mPriority = STREAM_PRIORITY_MEDIUM;
+
+    private boolean mDelayRequestHeadersUntilFirstFlush;
+
+    // Request reporting annotations.
+    private Collection<Object> mRequestAnnotations;
+
+    /**
+     * Creates a builder for {@link BidirectionalStream} objects. All callbacks for
+     * generated {@code BidirectionalStream} objects will be invoked on
+     * {@code executor}. {@code executor} must not run tasks on the
+     * current thread, otherwise the networking operations may block and exceptions
+     * may be thrown at shutdown time.
+     *
+     * @param url the URL for the generated stream
+     * @param callback the {@link BidirectionalStream.Callback} object that gets invoked upon
+     * different events
+     *     occuring
+     * @param executor the {@link Executor} on which {@code callback} methods will be invoked
+     * @param cronetEngine the {@link CronetEngine} used to create the stream
+     */
+    BidirectionalStreamBuilderImpl(String url, BidirectionalStream.Callback callback,
+            Executor executor, CronetEngineBase cronetEngine) {
+        super();
+        if (url == null) {
+            throw new NullPointerException("URL is required.");
+        }
+        if (callback == null) {
+            throw new NullPointerException("Callback is required.");
+        }
+        if (executor == null) {
+            throw new NullPointerException("Executor is required.");
+        }
+        if (cronetEngine == null) {
+            throw new NullPointerException("CronetEngine is required.");
+        }
+        mUrl = url;
+        mCallback = callback;
+        mExecutor = executor;
+        mCronetEngine = cronetEngine;
+    }
+
+    /**
+     * Sets the HTTP method for the request. Returns builder to facilitate chaining.
+     *
+     * @param method the method to use for request. Default is 'POST'
+     * @return the builder to facilitate chaining
+     */
+    public BidirectionalStreamBuilderImpl setHttpMethod(String method) {
+        if (method == null) {
+            throw new NullPointerException("Method is required.");
+        }
+        mHttpMethod = method;
+        return this;
+    }
+
+    /**
+     * Adds a request header. Returns builder to facilitate chaining.
+     *
+     * @param header the header name
+     * @param value the header value
+     * @return the builder to facilitate chaining
+     */
+    public BidirectionalStreamBuilderImpl addHeader(String header, String value) {
+        if (header == null) {
+            throw new NullPointerException("Invalid header name.");
+        }
+        if (value == null) {
+            throw new NullPointerException("Invalid header value.");
+        }
+        mRequestHeaders.add(new AbstractMap.SimpleImmutableEntry<>(header, value));
+        return this;
+    }
+
+    /**
+     * Sets priority of the stream which should be one of the
+     * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values.
+     * The stream is given {@link #STREAM_PRIORITY_MEDIUM} priority
+     * if this method is not called.
+     *
+     * @param priority priority of the stream which should be one of the
+     *         {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values.
+     * @return the builder to facilitate chaining.
+     */
+    public BidirectionalStreamBuilderImpl setPriority(@StreamPriority int priority) {
+        mPriority = priority;
+        return this;
+    }
+
+    /**
+     * Delays sending request headers until {@link BidirectionalStream#flush()}
+     * is called. This flag is currently only respected when QUIC is negotiated.
+     * When true, QUIC will send request header frame along with data frame(s)
+     * as a single packet when possible.
+     *
+     * @param delayRequestHeadersUntilFirstFlush if true, sending request headers will
+     *         be delayed until flush() is called.
+     * @return the builder to facilitate chaining.
+     */
+    public BidirectionalStreamBuilderImpl delayRequestHeadersUntilFirstFlush(
+            boolean delayRequestHeadersUntilFirstFlush) {
+        mDelayRequestHeadersUntilFirstFlush = delayRequestHeadersUntilFirstFlush;
+        return this;
+    }
+
+    @Override
+    public ExperimentalBidirectionalStream.Builder addRequestAnnotation(Object annotation) {
+        if (annotation == null) {
+            throw new NullPointerException("Invalid metrics annotation.");
+        }
+        if (mRequestAnnotations == null) {
+            mRequestAnnotations = new ArrayList<Object>();
+        }
+        mRequestAnnotations.add(annotation);
+        return this;
+    }
+
+    /**
+     * Creates a {@link BidirectionalStream} using configuration from this
+     * instance. The returned {@code BidirectionalStream} can then be started
+     * by calling {@link BidirectionalStream#start}.
+     *
+     * @return constructed {@link BidirectionalStream}.
+     */
+    @SuppressLint("WrongConstant") // TODO(jbudorick): Remove this after rolling to the N SDK.
+    public BidirectionalStream build() {
+        return mCronetEngine.createBidirectionalStream(mUrl, mCallback, mExecutor, mHttpMethod,
+                mRequestHeaders, mPriority, mDelayRequestHeadersUntilFirstFlush,
+                mRequestAnnotations);
+    }
+
+    @IntDef({
+            STREAM_PRIORITY_IDLE, STREAM_PRIORITY_LOWEST, STREAM_PRIORITY_LOW,
+            STREAM_PRIORITY_MEDIUM, STREAM_PRIORITY_HIGHEST,
+    })
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface StreamPriority {}
+}