Updating the transport Stream API to allow for callbacks for when a message was accepted by flow control.

-------------
Created by MOE: http://code.google.com/p/moe-java
MOE_MIGRATED_REVID=68706844

core/src/main/java/com/google/net/stubby/newtransport/Stream.java

@@ -2,6 +2,8 @@ package com.google.net.stubby.newtransport;
 
 import java.io.InputStream;
 
+import javax.annotation.Nullable;
+
 /**
  * A single stream of communication between two end-points within a transport.
  */
@@ -15,56 +17,51 @@ public interface Stream<T extends Stream<T>> {
   /**
    * Closes the local side of this stream and flushes any remaining messages. After this is called,
    * no further messages may be sent on this stream, but additional messages may be received until
-   * the remote end-point is closed. Calling this method automatically causes a {@link #flush()} to
+   * the remote end-point is closed.
-   * occur, so this method may block if awaiting resources.
    */
   void close();
 
   /**
-   * Writes the context name/value pair to the remote end-point. This method may block if awaiting
+   * Writes the context name/value pair to the remote end-point. The bytes from the stream are
-   * resources.
+   * immediate read by the Transport. This method will always return immediately and will not wait
+   * for the write to complete.
    *
-   * @param name the unique application-defined name for the context propery.
+   * <p>When the write is "accepted" by the transport, the given callback (if provided) will be
-   * @param value the value of the context property.
+   * called. The definition of what it means to be "accepted" is up to the transport implementation,
-   * @param offset the offset within the value array that is the start of the value.
+   * but this is a general indication that the transport is capable of handling more out-bound data
-   * @param length the length of the value starting from the offset index.
+   * on the stream. If the stream/connection is closed for any reason before the write could be
-   * @return this stream instance.
+   * accepted, the callback will never be invoked. Any writes that are still pending upon receiving
-   */
+   * a {@link StreamListener#closed} callback are assumed to be cancelled.
-  T writeContext(String name, byte[] value, int offset, int length);
-
-  /**
-   * Writes the context name/value pair to the remote end-point. This method may block if awaiting
-   * resources.
    *
-   * @param name the unique application-defined name for the context propery.
+   * @param name the unique application-defined name for the context property.
    * @param value the value of the context property.
    * @param length the length of the {@link InputStream}.
+   * @param accepted an optional callback for when the transport has accepted the write.
    * @return this stream instance.
    */
-  T writeContext(String name, InputStream value, int length);
+  T writeContext(String name, InputStream value, int length, @Nullable Runnable accepted);
 
   /**
-   * Writes a message payload to the remote end-point. This method may block if awaiting resources.
+   * Writes a message payload to the remote end-point. The bytes from the stream are immediate read
+   * by the Transport. This method will always return immediately and will not wait for the write to
+   * complete.
    *
-   * @param message array containing the serialized message to be sent
+   * <p>When the write is "accepted" by the transport, the given callback (if provided) will be
-   * @param offset the offset within the message array that is the start of the value.
+   * called. The definition of what it means to be "accepted" is up to the transport implementation,
-   * @param length the length of the message starting from the offset index.
+   * but this is a general indication that the transport is capable of handling more out-bound data
-   * @return this stream instance.
+   * on the stream. If the stream/connection is closed for any reason before the write could be
-   */
+   * accepted, the callback will never be invoked. Any writes that are still pending upon receiving
-  T writeMessage(byte[] message, int offset, int length);
+   * a {@link StreamListener#closed} callback are assumed to be cancelled.
-
-  /**
-   * Writes a message payload to the remote end-point. This method may block if awaiting resources.
    *
    * @param message stream containing the serialized message to be sent
    * @param length the length of the {@link InputStream}.
+   * @param accepted an optional callback for when the transport has accepted the write.
    * @return this stream instance.
    */
-  T writeMessage(InputStream message, int length);
+  T writeMessage(InputStream message, int length, @Nullable Runnable accepted);
 
   /**
-   * Flushes any internally buffered messages to the remote end-point. This method may block if
+   * Flushes any internally buffered messages to the remote end-point.
-   * awaiting resources.
    */
   T flush();
 }