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 4c37fb3866..0f8cd1f4cf 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 @@ 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> { /** * 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. + *

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. + *

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(); }