Top Description Inners Constructors Methods
io.grpc

public abstract Class ClientCall<ReqT, RespT>

extends Object
Class Inheritance
Known Direct Subclasses
io.grpc.PartialForwardingClientCall
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.
Imports
javax.annotation.Nullable
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 must be called prior to calling any other methods, with the exception of cancel. Whereas cancel 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, 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 and the completion/failure of the RPC in other ways. If cancel 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.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public abstract static class
ClientCall.Listener<
type of message received.
T>

Callbacks for receiving metadata, response messages and completion status from the server.

Constructor Summary

AccessConstructor and Description
public
ClientCall()

Method Summary

Modifier and TypeMethod and Description
public abstract void
cancel(String
if not null, will appear as the description of the CANCELLED status
message, Throwable
if not null, will appear as the cause of the CANCELLED status
cause)

Prevent any further processing for this ClientCall.

public Attributes

Returns:

non-null attributes
getAttributes()

Returns additional properties of the call.

public abstract void
halfClose()

Close the call for request message sending.

public boolean
isReady()

If true, indicates that the call is capable of sending additional messages without requiring excessive buffering internally.

public abstract void
request(int
the requested number of messages to be delivered to the listener. Must be non-negative.
numMessages)

Requests up to the given number of messages from the call to be delivered to Listener#onMessage(Object).

public abstract void
sendMessage(ReqT
message to be sent to the server.
message)

Send a request message to the server.

public void
setMessageCompression(boolean enabled)

Enables per-message compression, if an encoding type has been negotiated.

public abstract void
start(ClientCall.Listener<RespT>
receives response messages
responseListener, Metadata
which can contain extra call metadata, e.g. authentication credentials.
headers)

Start a call, using responseListener for processing response messages.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

ClientCallback to summary
public ClientCall()

Method Detail

cancelback to summary
public abstract void cancel(String message, 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 halfClosed. 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:String

if not null, will appear as the description of the CANCELLED status

cause:Throwable

if not null, will appear as the cause of the CANCELLED status

getAttributesback to summary
public Attributes getAttributes()

Returns additional properties of the call. May only be called after Listener#onHeaders or Listener#onClose. If called prematurely, the implementation may throw IllegalStateException or return arbitrary Attributes.

Returns:Attributes

non-null attributes

Annotations
@ExperimentalApi:https://github.com/grpc/grpc-java/issues/2607
@TransportAttr
Exceptions
IllegalStateException:
(optional) if called before permitted
halfCloseback to summary
public abstract void halfClose()

Close the call for request message sending. Incoming response messages are unaffected. This should be called when no more messages will be sent from the client.

Exceptions
IllegalStateException:
if call is already halfClose()d or canceled
isReadyback to summary
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, 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.

requestback to summary
public abstract void request(int numMessages)

Requests up to the given number of messages from the call to be delivered to 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:int

the requested number of messages to be delivered to the listener. Must be non-negative.

Exceptions
IllegalStateException:
if call is not start()ed
IllegalArgumentException:
if numMessages is negative
sendMessageback to summary
public abstract void sendMessage(ReqT message)

Send a request message to the server. May be called zero or more times depending on how many messages the server is willing to accept for the operation.

Parameters
message:ReqT

message to be sent to the server.

Exceptions
IllegalStateException:
if call is halfClosed or explicitly canceled
setMessageCompressionback to summary
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.

startback to summary
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 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:ClientCall.Listener<RespT>

receives response messages

headers:Metadata

which can contain extra call metadata, e.g. authentication credentials.

Exceptions
IllegalStateException:
if a method (including start()) on this class has been called.
io.grpc back to summary

public abstract Class ClientCall.Listener<T>

extends Object
Class Inheritance
Known Direct Subclasses
io.grpc.PartialForwardingClientCallListener
Type Parameters
<T>
type of message received.
Callbacks for receiving metadata, response messages and completion status from the server.

Implementations are free to block for extended periods of time. Implementations are not required to be thread-safe, but they must not be thread-hostile. The caller is free to call an instance from multiple threads, but only one call simultaneously. A single thread may interleave calls to multiple instances, so implementations using ThreadLocals must be careful to avoid leaking inappropriate state (e.g., clearing the ThreadLocal before returning).

Constructor Summary

AccessConstructor and Description
public
Listener()

Method Summary

Modifier and TypeMethod and Description
public void
onClose(Status
the result of the remote call.
status, Metadata
metadata provided at call completion.
trailers)

The ClientCall has been closed.

public void
onHeaders(Metadata
containing metadata sent by the server at the start of the response.
headers)

The response headers have been received.

public void
onMessage(T
returned by the server
message)

A response message has been received.

public void
onReady()

This indicates that the ClientCall may now be capable of sending additional messages (via sendMessage) without requiring excessive buffering internally.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Listenerback to summary
public Listener()

Method Detail

onCloseback to summary
public void onClose(Status status, Metadata trailers)

The ClientCall has been closed. Any additional calls to the ClientCall will not be processed by the server. No further receiving will occur and no further notifications will be made.

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

If status returns false for Status#isOk(), then the call failed. An additional block of trailer metadata may be received at the end of the call from the server. An empty Metadata object is passed if no trailers are received.

This method should not throw. If this method throws, there is no way to be notified of the exception. Implementations should therefore be careful of exceptions which can accidentally leak resources.

Parameters
status:Status

the result of the remote call.

trailers:Metadata

metadata provided at call completion.

onHeadersback to summary
public void onHeaders(Metadata headers)

The response headers have been received. Headers always precede messages.

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

Parameters
headers:Metadata

containing metadata sent by the server at the start of the response.

onMessageback to summary
public void onMessage(T message)

A response message has been received. May be called zero or more times depending on whether the call response is empty, a single message or a stream of messages.

Parameters
message:T

returned by the server

onReadyback to summary
public void onReady()

This indicates that the ClientCall may now be capable of sending additional messages (via sendMessage) 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 ClientCall.

Because there is a processing delay to deliver this notification, it is possible for concurrent writes to cause isReady() == false within this callback. Handle "spurious" notifications by checking isReady()'s current value instead of assuming it is now true. If isReady() == false the normal expectations apply, so there would be another onReady() callback.

If the type of a call is either MethodDescriptor.MethodType#UNARY or MethodDescriptor.MethodType#SERVER_STREAMING, this callback may not be fired. Calls that send exactly one message should not await this callback.