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
, includingUNARY
calls. For outgoing messages, aStreamObserver
is provided by the GRPC library to the application. For incoming messages, the application implements theStreamObserver
and passes it to the GRPC library for receiving.Implementations are not required to be thread-safe (but should be thread-compatible). Separate
StreamObserver
s do not need to be synchronized together; incoming and outgoing directions are independent. Since individualStreamObserver
s are not thread-safe, if multiple threads will be writing to aStreamObserver
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
andServerCallStreamObserver
to 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 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 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
onError
no further calls to any method are allowed.t
should be aStatusException
orStatusRuntimeException
, but otherThrowable
types are possible. Callers should generally convert from aStatus
viaStatus.asException()
orStatus.asRuntimeException()
. Implementations should generally convert to aStatus
viaStatus.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.
-
-