Package io.grpc

Class ClientCall<ReqT,​RespT>

  • Type Parameters:
    ReqT - type of message sent one or more times to the server.
    RespT - type of message received one or more times from the server.
    Direct Known Subclasses:
    ForwardingClientCall
    public abstract class ClientCall<ReqT,​RespT>
extends Object
    An instance of a call to a remote method. A call will send zero or more request messages to the server and receive zero or more response messages back.

    Instances are created by a Channel and used by stubs to invoke their remote behavior.

    More advanced usages may consume this interface directly as opposed to using a stub. Common reasons for doing so would be the need to interact with flow-control or when acting as a generic proxy for arbitrary operations.

    start(io.grpc.ClientCall.Listener<RespT>, io.grpc.Metadata) must be called prior to calling any other methods, with the exception of cancel(java.lang.String, java.lang.Throwable). Whereas cancel(java.lang.String, java.lang.Throwable) must not be followed by any other methods, but can be called more than once, while only the first one has effect.

    No generic method for determining message receipt or providing acknowledgement is provided. Applications are expected to utilize normal payload messages for such signals, as a response naturally acknowledges its request.

    Methods are guaranteed to be non-blocking. Not thread-safe except for request(int), which may be called from any thread.

    There is no interaction between the states on the Listener and ClientCall, i.e., if Listener.onClose() is called, it has no bearing on the permitted operations on ClientCall (but it may impact whether they do anything).

    There is a race between cancel(java.lang.String, java.lang.Throwable) and the completion/failure of the RPC in other ways. If cancel(java.lang.String, java.lang.Throwable) won the race, Listener.onClose() is called with CANCELLED. Otherwise, Listener.onClose() is called with whatever status the RPC was finished. We ensure that at most one is called.

    Usage examples

    Simple Unary (1 request, 1 response) RPC

       call = channel.newCall(unaryMethod, callOptions);
   call.start(listener, headers);
   call.sendMessage(message);
   call.halfClose();
   call.request(1);
   // wait for listener.onMessage()

    Flow-control in Streaming RPC

    The following snippet demonstrates a bi-directional streaming case, where the client sends requests produced by a fictional makeNextRequest() in a flow-control-compliant manner, and notifies gRPC library to receive additional response after one is consumed by a fictional processResponse(). 

       call = channel.newCall(bidiStreamingMethod, callOptions);
   listener = new ClientCall.Listener<FooResponse>() {
     @Override
     public void onMessage(FooResponse response) {
       processResponse(response);
       // Notify gRPC to receive one additional response.
       call.request(1);
     }

     @Override
     public void onReady() {
       while (call.isReady()) {
         FooRequest nextRequest = makeNextRequest();
         if (nextRequest == null) {  // No more requests to send
           call.halfClose();
           return;
         }
         call.sendMessage(nextRequest);
       }
     }
   }
   call.start(listener, headers);
   // Notify gRPC to receive one response. Without this line, onMessage() would never be called.
   call.request(1);

    DO NOT MOCK: Use InProcessServerBuilder and make a test server instead.

    • Constructor Detail

      • ClientCall

        public ClientCall()

    • Method Detail

      • start

        public abstract void start​(ClientCall.Listener<RespT> responseListener,
                           Metadata headers)
        Start a call, using responseListener for processing response messages.

        It must be called prior to any other method on this class, except for cancel(java.lang.String, java.lang.Throwable) which may be called at any time.

        Since Metadata is not thread-safe, the caller must not access (read or write) headers after this point.

        Parameters:
        responseListener - receives response messages
        headers - which can contain extra call metadata, e.g. authentication credentials.
        Throws:
        IllegalStateException - if a method (including start()) on this class has been called.

      • request

        public abstract void request​(int numMessages)
        Requests up to the given number of messages from the call to be delivered to ClientCall.Listener.onMessage(Object). No additional messages will be delivered.

        Message delivery is guaranteed to be sequential in the order received. In addition, the listener methods will not be accessed concurrently. While it is not guaranteed that the same thread will always be used, it is guaranteed that only a single thread will access the listener at a time.

        If it is desired to bypass inbound flow control, a very large number of messages can be specified (e.g. Integer.MAX_VALUE).

        If called multiple times, the number of messages able to delivered will be the sum of the calls.

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

        Parameters:
        numMessages - the requested number of messages to be delivered to the listener. Must be non-negative.
        Throws:
        IllegalStateException - if call is not start()ed
        IllegalArgumentException - if numMessages is negative

      • cancel

        public abstract void cancel​(@Nullable
                            String message,
                            @Nullable
                            Throwable cause)
        Prevent any further processing for this ClientCall. No further messages may be sent or will be received. The server is informed of cancellations, but may not stop processing the call. Cancellation is permitted even if previously halfClose()d. Cancelling an already cancel()ed ClientCall has no effect.

        No other methods on this class can be called after this method has been called.

        It is recommended that at least one of the arguments to be non-null, to provide useful debug information. Both argument being null may log warnings and result in suboptimal performance. Also note that the provided information will not be sent to the server.

        Parameters:
        message - if not null, will appear as the description of the CANCELLED status
        cause - if not null, will appear as the cause of the CANCELLED status

      • isReady

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

        If false, ClientCall.Listener.onReady() will be called after isReady() transitions to true.

        If the type of the call is either MethodDescriptor.MethodType.UNARY or MethodDescriptor.MethodType.SERVER_STREAMING, this method may persistently return false. Calls that send exactly one message should not check this method.

        This abstract class's implementation always returns true. Implementations generally override the method.

      • setMessageCompression

        public void setMessageCompression​(boolean enabled)
        Enables per-message compression, if an encoding type has been negotiated. If no message encoding has been negotiated, this is a no-op. By default per-message compression is enabled, but may not have any effect if compression is not enabled on the call.