io.grpc

Class ServerCall<RespT>

java.lang.Object

io.grpc.ServerCall<RespT>

Type Parameters:

RespT - parsed type of response message.

Direct Known Subclasses:

ForwardingServerCall

public abstract class ServerCall<RespT>
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 messages, which must be sent before closing.

No generic method for determining message receipt or providing acknowledgement is provided. Applications are expected to utilize normal 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<ReqT> Callbacks for consuming incoming RPC messages.

Field Summary

Fields

Modifier and Type	Field and Description
static Attributes.Key<SocketAddress>	REMOTE_ADDR_KEY Attributes.Key for the remote address of server call attributes attributes()
static Attributes.Key<SSLSession>	SSL_SESSION_KEY Attributes.Key for the SSL session of server call attributes attributes()

Constructor Summary

Constructors

Constructor and Description
ServerCall()

Method Summary

Modifier and Type	Method and Description
Attributes	attributes() Returns properties of a single call.
abstract void	close(Status status, Metadata 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.onMessage(Object).
abstract void	sendHeaders(Metadata headers) Send response header metadata prior to sending a response message.
abstract void	sendMessage(RespT message) Send a response message.
void	setCompression(String compressor) Sets the compression algorithm for this call.
void	setMessageCompression(boolean enabled) Enables per-message compression, if an encoding type has been negotiated.

Methods inherited from class java.lang.Object

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

Field Detail

REMOTE_ADDR_KEY

@ExperimentalApi
public static final Attributes.Key<SocketAddress> REMOTE_ADDR_KEY

Attributes.Key for the remote address of server call attributes attributes()

SSL_SESSION_KEY

@ExperimentalApi
public static final Attributes.Key<SSLSession> SSL_SESSION_KEY

Attributes.Key for the SSL session of server call attributes attributes()

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.onMessage(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.

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

Parameters:

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

sendHeaders

public abstract void sendHeaders(Metadata headers)

Send response header metadata prior to sending a response message. This method may only be called once and cannot be called after calls to sendMessage(RespT) or close(io.grpc.Status, io.grpc.Metadata).

Since Metadata is not thread-safe, the caller must not access headers after this point.

Parameters:

headers - metadata to send prior to any response body.

Throws:

IllegalStateException - if close has been called, a message has been sent, or headers have already been sent

sendMessage

public abstract void sendMessage(RespT message)

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

Parameters:

message - response message.

Throws:

IllegalStateException - if headers not sent or call is close(io.grpc.Status, io.grpc.Metadata)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)

Close the call with the provided status. No further sending or receiving will occur. If Status.isOk() is false, then the call is said to have failed.

If no errors or cancellations are known to have occurred, then a ServerCall.Listener.onComplete() notification should be expected, independent of status. Otherwise ServerCall.Listener.onCancel() has been or will be called.

Since Metadata is not thread-safe, the caller must not access trailers after this point.

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.

setMessageCompression

@ExperimentalApi
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.

setCompression

@ExperimentalApi
public void setCompression(String compressor)

Sets the compression algorithm for this call. If the server does not support the compression algorithm, the call will fail. This method may only be called before sendHeaders(io.grpc.Metadata). The compressor to use will be looked up in the CompressorRegistry. Default gRPC servers support the "gzip" compressor.

Parameters:

compressor - the name of the compressor to use.

Throws:

IllegalArgumentException - if the compressor name can not be found.

attributes

@ExperimentalApi
public Attributes attributes()

Returns properties of a single call. This is a generic container which can contain any kind of information describing call like for example remote address, TLS information (OU etc.)

Returns:

Attributes container