[Cronet] Make delaying sending request headers explicit in bidirectional stream

components/cronet/android/api/src/org/chromium/net/BidirectionalStream.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 android.support.annotation.IntDef;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ skipping 29 matching lines @@
         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<Map.Entry<String, String>>();
 
         // 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;
 
+        // TODO(xunjieli): Remove mDisableAutoFlush and make flush() required as part of th API.
         private boolean mDisableAutoFlush;
+        private boolean mDelayRequestHeadersUntilNextFlush;
 
         /**
          * 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 Callback} object that gets invoked upon different events
@@ skipping 106 matching lines @@
          *
          * @param disableAutoFlush if true, auto flush will be disabled.
          * @return the builder to facilitate chaining.
          */
         public Builder disableAutoFlush(boolean disableAutoFlush) {
             mDisableAutoFlush = disableAutoFlush;
             return this;
         }
 
         /**
+         * Delays sending request headers until the next {@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 delayRequestHeadersUntilNextFlush if true, sending request headers will
+         *         be delayed until the next flush() is called.
+         * @return the builder to facilitate chaining.
+         */
+        public Builder delayRequestHeadersUntilNextFlush(
+                boolean delayRequestHeadersUntilNextFlush) {
+            mDelayRequestHeadersUntilNextFlush = delayRequestHeadersUntilNextFlush;
+            return this;
+        }
+
+        /**
          * Creates a {@link BidirectionalStream} using configuration from this
          * {@link Builder}. The returned {@code BidirectionalStream} can then be started
          * by calling {@link BidirectionalStream#start}.
          *
          * @return constructed {@link BidirectionalStream} using configuration from
          *         this {@link Builder}
          */
         public BidirectionalStream build() {
             return mCronetEngine.createBidirectionalStream(mUrl, mCallback, mExecutor, mHttpMethod,
-                    mRequestHeaders, mPriority, mDisableAutoFlush);
+                    mRequestHeaders, mPriority, mDisableAutoFlush,
+                    mDelayRequestHeadersUntilNextFlush);
         }
     }
 
     /**
      * Callback class used to receive callbacks from a {@link BidirectionalStream}.
      */
     public abstract static class Callback {
         /**
          * Invoked when the stream is ready for reading and writing.
          * Consumer may call {@link BidirectionalStream#read read()} to start reading data.
@@ skipping 174 matching lines @@
      *     {@link Callback#onWriteCompleted onWriteCompleted()}, {@link Callback#onCanceled
      *     onCanceled()}, or {@link Callback#onFailed onFailed()} are invoked. Can be empty
      *     when {@code endOfStream} is {@code true}.
      * @param endOfStream if {@code true}, then {@code buffer} is the last buffer to be written,
      *     and once written, stream is closed from the client side, resulting in half-closed
      *     stream or a fully closed stream if the remote side has already closed.
      */
     public abstract void write(ByteBuffer buffer, boolean endOfStream);
 
     /**
-     * Flushes pending writes. This method should only be invoked when auto
-     * flush is disabled through {@link Builder#disableAutoFlush}.
+     * Flushes pending writes. This method should not be invoked before {@link

[mef, 2016/06/01 21:33:20]

I think this deserves more verbose comment, explaining that onWriteCompleted
callbacks will be invoked for previously delayed writes or somesuch.

[xunjieli, 2016/06/01 22:27:16]

Done.

+     * Callback#onStreamReady onStreamReady()}.
      */
     public abstract void flush();
 
     /**
      * Pings remote end-point. {@code callback} methods will be invoked on {@code executor}.
      *
      * @param callback the callback that will be invoked when ping succeeds or fails
      * @param executor the executor on which the callback will be invoked
      */
     // TODO(mef): May be last thing to be implemented on Android.
@@ skipping 24 matching lines @@
     /**
      * Returns {@code true} if the stream was successfully started and is now
      * done (succeeded, canceled, or failed).
      *
      * @return {@code true} if the stream was successfully started and is now
      *         done (completed, canceled, or failed), otherwise returns {@code false}
      *         to indicate stream is not yet started or is in progress.
      */
     public abstract boolean isDone();
 }