io.grpc

Class ServerCall<ResponseT>

java.lang.Object

io.grpc.ServerCall<ResponseT>

Type Parameters:

ResponseT - parsed type of response message.

Direct Known Subclasses:

ForwardingServerCall

public abstract class ServerCall<ResponseT>
extends Object

Encapsulates a single call received from a remote client. Calls may not simply be unary request-response even though this is the most common pattern. Calls may stream any number of requests and responses. This API is generally intended for use by generated handlers, but applications may use it directly if they need to.

Headers must be sent before any payloads, which must be sent before closing.

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. Implementations are not required to be thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ServerCall.Listener<RequestT> Callbacks for consuming incoming RPC messages.

Constructor Summary

Constructors

Constructor and Description
ServerCall()

Method Summary

Modifier and Type	Method and Description
abstract void	close(Status status, Metadata.Trailers trailers) Close the call with the provided status.
abstract boolean	isCancelled() Returns true when the call is cancelled and the server is encouraged to abort processing to save resources, since the client will not be processing any further methods.
boolean	isReady() If true, indicates that the call is capable of sending additional messages without requiring excessive buffering internally.
abstract void	request(int numMessages) Requests up to the given number of messages from the call to be delivered to ServerCall.Listener.onPayload(Object).
abstract void	sendHeaders(Metadata.Headers headers) Send response header metadata prior to sending a response payload.
abstract void	sendPayload(ResponseT payload) Send a response message.

Methods inherited from class java.lang.Object

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

Constructor Detail

ServerCall

public ServerCall()

Method Detail

request

public abstract void request(int numMessages)

Requests up to the given number of messages from the call to be delivered to ServerCall.Listener.onPayload(Object). Once numMessages have been delivered no further request messages will be delivered until more messages are requested by calling this method again.

Servers use this mechanism to provide back-pressure to the client for flow-control.

Parameters:

numMessages - the requested number of messages to be delivered to the listener.

sendHeaders

public abstract void sendHeaders(Metadata.Headers headers)

Send response header metadata prior to sending a response payload. This method may only be called once and cannot be called after calls to Stream#sendPayload or #close.

Parameters:

headers - metadata to send prior to any response body.

Throws:

IllegalStateException - if close has been called or a payload has been sent.

sendPayload

public abstract void sendPayload(ResponseT payload)

Send a response message. Payload messages are the primary form of communication associated with RPCs. Multiple response messages may exist for streaming calls.

Parameters:

payload - response message.

Throws:

IllegalStateException - if call is close(io.grpc.Status, io.grpc.Metadata.Trailers)d

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.

This implementation always returns true.

close

public abstract void close(Status status,
                           Metadata.Trailers trailers)

Close the call with the provided status. No further sending or receiving will occur. If status is not equal to Status.OK, then the call is said to have failed.

If status is not Status.CANCELLED and no errors or cancellations are known to have occured, then a ServerCall.Listener.onComplete() notification should be expected. Otherwise ServerCall.Listener.onCancel() has been or will be called.

Throws:

IllegalStateException - if call is already closed

isCancelled

public abstract boolean isCancelled()

Returns true when the call is cancelled and the server is encouraged to abort processing to save resources, since the client will not be processing any further methods. Cancellations can be caused by timeouts, explicit cancel by client, network errors, and similar.

This method may safely be called concurrently from multiple threads.