Package io.grpc.stub

Class ClientCalls

java.lang.Object

io.grpc.stub.ClientCalls

public final class ClientCalls
extends Object

Utility functions for processing different call idioms. We have one-to-one correspondence between utilities in this class and the potential signatures in a generated stub class so that the runtime can vary behavior without requiring regeneration of the stub.

Method Summary

Modifier and Type	Method	Description
static <ReqT,RespT> StreamObserver<ReqT>	asyncBidiStreamingCall(ClientCall<ReqT,RespT> call, StreamObserver<RespT> responseObserver)	Executes a bidirectional-streaming call.
static <ReqT,RespT> StreamObserver<ReqT>	asyncClientStreamingCall(ClientCall<ReqT,RespT> call, StreamObserver<RespT> responseObserver)	Executes a client-streaming call returning a StreamObserver for the request messages.
static <ReqT,RespT> void	asyncServerStreamingCall(ClientCall<ReqT,RespT> call, ReqT req, StreamObserver<RespT> responseObserver)	Executes a server-streaming call with a response StreamObserver.
static <ReqT,RespT> void	asyncUnaryCall(ClientCall<ReqT,RespT> call, ReqT req, StreamObserver<RespT> responseObserver)	Executes a unary call with a response StreamObserver.
static <ReqT,RespT> BlockingClientCall<ReqT,RespT>	blockingBidiStreamingCall(Channel channel, MethodDescriptor<ReqT,RespT> method, CallOptions callOptions)	Initiate a bidirectional-streaming ClientCall and returning a stream object (BlockingClientCall) which can be used by the client to send and receive messages over the grpc channel.
static <ReqT,RespT> BlockingClientCall<ReqT,RespT>	blockingClientStreamingCall(Channel channel, MethodDescriptor<ReqT,RespT> method, CallOptions callOptions)	Initiates a server streaming call and sends the specified request to the server.
static <ReqT,RespT> Iterator<RespT>	blockingServerStreamingCall(Channel channel, MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, ReqT req)	Executes a server-streaming call returning a blocking Iterator over the response stream.
static <ReqT,RespT> Iterator<RespT>	blockingServerStreamingCall(ClientCall<ReqT,RespT> call, ReqT req)	Executes a server-streaming call returning a blocking Iterator over the response stream.
static <ReqT,RespT> RespT	blockingUnaryCall(Channel channel, MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, ReqT req)	Executes a unary call and blocks on the response.
static <ReqT,RespT> RespT	blockingUnaryCall(ClientCall<ReqT,RespT> call, ReqT req)	Executes a unary call and blocks on the response.
static <ReqT,RespT> BlockingClientCall<ReqT,RespT>	blockingV2ServerStreamingCall(Channel channel, MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, ReqT req)	Initiates a client streaming call over the specified channel.
static <ReqT,RespT> RespT	blockingV2UnaryCall(Channel channel, MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, ReqT req)	Executes a unary call and blocks on the response, throws a checked StatusException.
static <ReqT,RespT> com.google.common.util.concurrent.ListenableFuture<RespT>	futureUnaryCall(ClientCall<ReqT,RespT> call, ReqT req)	Executes a unary call and returns a ListenableFuture to the response.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

asyncUnaryCall

public static <ReqT,RespT> void asyncUnaryCall(ClientCall<ReqT,RespT> call,
                                                     ReqT req,
                                                     StreamObserver<RespT> responseObserver)

Executes a unary call with a response StreamObserver. The call should not be already started. After calling this method, call should no longer be used.

If the provided responseObserver is an instance of ClientResponseObserver, beforeStart() will be called.

asyncServerStreamingCall

public static <ReqT,RespT> void asyncServerStreamingCall(ClientCall<ReqT,RespT> call,
                                                               ReqT req,
                                                               StreamObserver<RespT> responseObserver)

Executes a server-streaming call with a response StreamObserver. The call should not be already started. After calling this method, call should no longer be used.

If the provided responseObserver is an instance of ClientResponseObserver, beforeStart() will be called.

asyncClientStreamingCall

public static <ReqT,RespT> StreamObserver<ReqT> asyncClientStreamingCall(ClientCall<ReqT,RespT> call,
                                                                               StreamObserver<RespT> responseObserver)

Executes a client-streaming call returning a StreamObserver for the request messages. The call should not be already started. After calling this method, call should no longer be used.

If the provided responseObserver is an instance of ClientResponseObserver, beforeStart() will be called.

Returns:

request stream observer. It will extend ClientCallStreamObserver

asyncBidiStreamingCall

public static <ReqT,RespT> StreamObserver<ReqT> asyncBidiStreamingCall(ClientCall<ReqT,RespT> call,
                                                                             StreamObserver<RespT> responseObserver)

Executes a bidirectional-streaming call. The call should not be already started. After calling this method, call should no longer be used.

If the provided responseObserver is an instance of ClientResponseObserver, beforeStart() will be called.

Returns:

request stream observer. It will extend ClientCallStreamObserver

blockingUnaryCall

public static <ReqT,RespT> RespT blockingUnaryCall(ClientCall<ReqT,RespT> call,
                                                         ReqT req)

Executes a unary call and blocks on the response. The call should not be already started. After calling this method, call should no longer be used.

Returns:

the single response message.

Throws:

StatusRuntimeException - on error

blockingUnaryCall

public static <ReqT,RespT> RespT blockingUnaryCall(Channel channel,
                                                         MethodDescriptor<ReqT,RespT> method,
                                                         CallOptions callOptions,
                                                         ReqT req)

Executes a unary call and blocks on the response. The call should not be already started. After calling this method, call should no longer be used.

Returns:

the single response message.

Throws:

StatusRuntimeException - on error

blockingV2UnaryCall

public static <ReqT,RespT> RespT blockingV2UnaryCall(Channel channel,
                                                           MethodDescriptor<ReqT,RespT> method,
                                                           CallOptions callOptions,
                                                           ReqT req)
                                                    throws StatusException

Executes a unary call and blocks on the response, throws a checked StatusException.

Returns:

the single response message.

Throws:

StatusException - on error

blockingServerStreamingCall

public static <ReqT,RespT> Iterator<RespT> blockingServerStreamingCall(ClientCall<ReqT,RespT> call,
                                                                             ReqT req)

Executes a server-streaming call returning a blocking Iterator over the response stream. The call should not be already started. After calling this method, call should no longer be used.

The returned iterator may throw StatusRuntimeException on error.

Returns:

an iterator over the response stream.

blockingServerStreamingCall

public static <ReqT,RespT> Iterator<RespT> blockingServerStreamingCall(Channel channel,
                                                                             MethodDescriptor<ReqT,RespT> method,
                                                                             CallOptions callOptions,
                                                                             ReqT req)

Executes a server-streaming call returning a blocking Iterator over the response stream.

The returned iterator may throw StatusRuntimeException on error.

Warning: the iterator can result in leaks if not completely consumed.

Returns:

an iterator over the response stream.

blockingV2ServerStreamingCall

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
public static <ReqT,RespT> BlockingClientCall<ReqT,RespT> blockingV2ServerStreamingCall(Channel channel,
                                                                                                    MethodDescriptor<ReqT,RespT> method,
                                                                                                    CallOptions callOptions,
                                                                                                    ReqT req)

Initiates a client streaming call over the specified channel. It returns an object which can be used in a blocking manner to retrieve responses..

The methods BlockingClientCall.hasNext() and BlockingClientCall.cancel(String, Throwable) can be used for more extensive control.

Returns:

A BlockingClientCall that has had the request sent and halfClose called

blockingClientStreamingCall

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
public static <ReqT,RespT> BlockingClientCall<ReqT,RespT> blockingClientStreamingCall(Channel channel,
                                                                                                  MethodDescriptor<ReqT,RespT> method,
                                                                                                  CallOptions callOptions)

Initiates a server streaming call and sends the specified request to the server. It returns an object which can be used in a blocking manner to retrieve values from the server. After the last value has been read, the next read call will return null.

Call BlockingClientCall.read() for retrieving values. A null will be returned after the server has closed the stream.

The methods BlockingClientCall.hasNext() and BlockingClientCall.cancel(String, Throwable) can be used for more extensive control.

Example usage:

  while ((response = call.read()) != null) { ... }  

or

 
   while (call.hasNext()) {
     response = call.read();
     ...
   }
  

Note that this paradigm is different from the original blockingServerStreamingCall(Channel, MethodDescriptor, CallOptions, Object) which returns an iterator, which would leave the stream open if not completely consumed.

Returns:

A BlockingClientCall which can be used by the client to write and receive messages over the grpc channel.

blockingBidiStreamingCall

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
public static <ReqT,RespT> BlockingClientCall<ReqT,RespT> blockingBidiStreamingCall(Channel channel,
                                                                                                MethodDescriptor<ReqT,RespT> method,
                                                                                                CallOptions callOptions)

Initiate a bidirectional-streaming ClientCall and returning a stream object (BlockingClientCall) which can be used by the client to send and receive messages over the grpc channel.

Returns:

an object representing the call which can be used to read, write and terminate it.

futureUnaryCall

public static <ReqT,RespT> com.google.common.util.concurrent.ListenableFuture<RespT> futureUnaryCall(ClientCall<ReqT,RespT> call,
                                                                                                           ReqT req)

Executes a unary call and returns a ListenableFuture to the response. The call should not be already started. After calling this method, call should no longer be used.

Returns:

a future for the single response message.