Package io.grpc.stub

Class CallStreamObserver<V>

java.lang.Object
io.grpc.stub.CallStreamObserver<V>
Type Parameters:
V - type of outbound message.
All Implemented Interfaces:
StreamObserver<V>
Direct Known Subclasses:
ClientCallStreamObserver, ServerCallStreamObserver
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8499") public abstract class CallStreamObserver<V> extends Object implements StreamObserver<V>
A refinement of StreamObserver provided by the GRPC runtime to the application (the client or the server) that allows for more complex interactions with call behavior.

In any call there are logically four StreamObserver implementations:

  • 'inbound', client-side - which the GRPC runtime calls when it receives messages from the server. This is implemented by the client application and passed into a service method on a stub object.
  • 'outbound', client-side - which the GRPC runtime provides to the client application and the client uses this StreamObserver to send messages to the server.
  • 'inbound', server-side - which the GRPC runtime calls when it receives messages from the client. This is implemented by the server application and returned from service implementations of client-side streaming and bidirectional streaming methods.
  • 'outbound', server-side - which the GRPC runtime provides to the server application and the server uses this StreamObserver to send messages (responses) to the client.

Implementations of this class represent the 'outbound' message streams. The client-side one is ClientCallStreamObserver and the service-side one is ServerCallStreamObserver.

Like StreamObserver, implementations are not required to be thread-safe; if multiple threads will be writing to an instance concurrently, the application must synchronize its calls.

DO NOT MOCK: The API is too complex to reliably mock. Use InProcessChannelBuilder to create "real" RPCs suitable for testing.

  • Constructor Details

    • CallStreamObserver

      public CallStreamObserver()

  • Method Details

    • isReady

      public abstract boolean isReady()
      If true, indicates that the observer is capable of sending additional messages without requiring excessive buffering internally. This value is just a suggestion and the application is free to ignore it, however doing so may result in excessive buffering within the observer.

      If false, the runnable passed to setOnReadyHandler(java.lang.Runnable) will be called after isReady() transitions to true.

    • setOnReadyHandler

      public abstract void setOnReadyHandler(Runnable onReadyHandler)
      Set a Runnable that will be executed every time the stream isReady() state changes from false to true. While it is not guaranteed that the same thread will always be used to execute the Runnable, it is guaranteed that executions are serialized with calls to the 'inbound' StreamObserver.

      On client-side this method may only be called during ClientResponseObserver.beforeStart(io.grpc.stub.ClientCallStreamObserver<ReqT>). On server-side it may only be called during the initial call to the application, before the service returns its StreamObserver.

      Because there is a processing delay to deliver this notification, it is possible for concurrent writes to cause isReady() == false within this callback. Handle "spurious" notifications by checking isReady()'s current value instead of assuming it is now true. If isReady() == false the normal expectations apply, so there would be another onReadyHandler callback.

      Parameters:
      onReadyHandler - to call when peer is ready to receive more messages.

    • disableAutoInboundFlowControl

      public abstract void disableAutoInboundFlowControl()
      Disables automatic flow control where a token is returned to the peer after a call to the 'inbound' StreamObserver.onNext(Object) has completed. If disabled an application must make explicit calls to request(int) to receive messages.

      On client-side this method may only be called during ClientResponseObserver.beforeStart(io.grpc.stub.ClientCallStreamObserver<ReqT>). On server-side it may only be called during the initial call to the application, before the service returns its StreamObserver.

      Note that for cases where the runtime knows that only one inbound message is allowed calling this method will have no effect and the runtime will always permit one and only one message. This is true for:

      This API is being replaced, but is not yet deprecated. On server-side it being replaced with ServerCallStreamObserver.disableAutoRequest(). On client-side disableAutoRequestWithInitial(1).

    • request

      public abstract void request(int count)
      Requests the peer to produce count more messages to be delivered to the 'inbound' StreamObserver.

      This method is safe to call from multiple threads without external synchronization.

      Parameters:
      count - more messages

    • setMessageCompression

      public abstract void setMessageCompression(boolean enable)
      Sets message compression for subsequent calls to StreamObserver.onNext(V).
      Parameters:
      enable - whether to enable compression.