Package io.grpc.stub

Interface StreamObserver<V>

All Known Subinterfaces:
ClientResponseObserver<ReqT,RespT>
All Known Implementing Classes:
CallStreamObserver, ClientCallStreamObserver, ServerCallStreamObserver
public interface StreamObserver<V>
Receives notifications from an observable stream of messages.

It is used by both the client stubs and service implementations for sending or receiving stream messages. It is used for all MethodDescriptor.MethodType, including UNARY calls. For outgoing messages, a StreamObserver is provided by the GRPC library to the application. For incoming messages, the application implements the StreamObserver and passes it to the GRPC library for receiving.

Implementations are not required to be thread-safe (but should be thread-compatible). Separate StreamObservers do not need to be synchronized together; incoming and outgoing directions are independent. Since individual StreamObservers are not thread-safe, if multiple threads will be writing to a StreamObserver concurrently, the application must synchronize calls.

This API is asynchronous, so methods may return before the operation completes. The API provides no guarantees for how quickly an operation will complete, so utilizing flow control via ClientCallStreamObserver and ServerCallStreamObserver to avoid excessive buffering is recommended for streaming RPCs. gRPC's implementation of onError() on client-side causes the RPC to be cancelled and discards all messages, so completes quickly.

gRPC guarantees it does not block on I/O in its implementation, but applications are allowed to perform blocking operations in their implementations. However, doing so will delay other callbacks because the methods cannot be called concurrently.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    onCompleted()
    Receives a notification of successful stream completion.
    void
    onError(Throwable t)
    Receives a terminating error from the stream.
    void
    onNext(V value)
    Receives a value from the stream.

  • Method Details

    • onNext

      void onNext(V value)
      Receives a value from the stream.

      Can be called many times but is never called after onError(Throwable) or onCompleted() are called.

      Unary calls must invoke onNext at most once. Clients may invoke onNext at most once for server streaming calls, but may receive many onNext callbacks. Servers may invoke onNext at most once for client streaming calls, but may receive many onNext callbacks.

      If an exception is thrown by an implementation the caller is expected to terminate the stream by calling onError(Throwable) with the caught exception prior to propagating it.

      Parameters:
      value - the value passed to the stream

    • onError

      void onError(Throwable t)
      Receives a terminating error from the stream.

      May only be called once and if called it must be the last method called. In particular if an exception is thrown by an implementation of onError no further calls to any method are allowed.

      t should be a StatusException or StatusRuntimeException, but other Throwable types are possible. Callers should generally convert from a Status via Status.asException() or Status.asRuntimeException(). Implementations should generally convert to a Status via Status.fromThrowable(Throwable).

      Parameters:
      t - the error occurred on the stream

    • onCompleted

      void onCompleted()
      Receives a notification of successful stream completion.

      May only be called once and if called it must be the last method called. In particular if an exception is thrown by an implementation of onCompleted no further calls to any method are allowed.