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
diff --git a/core/src/main/java/com/google/net/stubby/newtransport/Stream.java b/core/src/main/java/com/google/net/stubby/newtransport/Stream.java
index 4c37fb3..0f8cd1f 100644
--- a/core/src/main/java/com/google/net/stubby/newtransport/Stream.java
+++ b/core/src/main/java/com/google/net/stubby/newtransport/Stream.java
@@ -2,6 +2,8 @@
import java.io.InputStream;
+import javax.annotation.Nullable;
+
/**
* A single stream of communication between two end-points within a transport.
*/
@@ -15,56 +17,51 @@
/**
* 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
- * occur, so this method may block if awaiting resources.
+ * the remote end-point is closed.
*/
void close();
/**
- * Writes the context name/value pair to the remote end-point. This method may block if awaiting
- * resources.
+ * Writes the context name/value pair 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 name the unique application-defined name for the context propery.
- * @param value the value of the context property.
- * @param offset the offset within the value array that is the start of the value.
- * @param length the length of the value starting from the offset index.
- * @return this stream instance.
- */
- 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.
+ * <p>When the write is "accepted" by the transport, the given callback (if provided) will be
+ * called. The definition of what it means to be "accepted" is up to the transport implementation,
+ * but this is a general indication that the transport is capable of handling more out-bound data
+ * 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
+ * a {@link StreamListener#closed} callback are assumed to be cancelled.
*
- * @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
- * @param offset the offset within the message array that is the start of the value.
- * @param length the length of the message starting from the offset index.
- * @return this stream instance.
- */
- T writeMessage(byte[] message, int offset, int length);
-
- /**
- * Writes a message payload to the remote end-point. This method may block if awaiting resources.
+ * <p>When the write is "accepted" by the transport, the given callback (if provided) will be
+ * called. The definition of what it means to be "accepted" is up to the transport implementation,
+ * but this is a general indication that the transport is capable of handling more out-bound data
+ * 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
+ * a {@link StreamListener#closed} callback are assumed to be cancelled.
*
* @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
- * awaiting resources.
+ * Flushes any internally buffered messages to the remote end-point.
*/
T flush();
}