Interface StreamObserver<V>
-
- All Known Subinterfaces:
ClientResponseObserver<ReqT,RespT>
- All Known Implementing Classes:
CallStreamObserver,ClientCallStreamObserver,ServerCallStreamObserver,StreamRecorder
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, includingUNARYcalls. For outgoing messages, aStreamObserveris provided by the GRPC library to the application. For incoming messages, the application implements theStreamObserverand 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 individualStreamObservers are not thread-safe, if multiple threads will be writing to aStreamObserverconcurrently, 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
ClientCallStreamObserverandServerCallStreamObserverto avoid excessive buffering is recommended for streaming RPCs. gRPC's implementation ofonError()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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidonCompleted()Receives a notification of successful stream completion.voidonError(Throwable t)Receives a terminating error from the stream.voidonNext(V value)Receives a value from the stream.
-
-
-
Method Detail
-
onNext
void onNext(V value)
Receives a value from the stream.Can be called many times but is never called after
onError(Throwable)oronCompleted()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
onErrorno further calls to any method are allowed.tshould be aStatusExceptionorStatusRuntimeException, but otherThrowabletypes are possible. Callers should generally convert from aStatusviaStatus.asException()orStatus.asRuntimeException(). Implementations should generally convert to aStatusviaStatus.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
onCompletedno further calls to any method are allowed.
-
-