ReqT
- parsed type of request message.RespT
- parsed type of response message.public abstract class ServerCall<ReqT,RespT> extends Object
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.
DO NOT MOCK: Use InProcessTransport and make a fake server instead.
Modifier and Type | Class and Description |
---|---|
static class |
ServerCall.Listener<ReqT>
Callbacks for consuming incoming RPC messages.
|
Constructor and Description |
---|
ServerCall() |
Modifier and Type | Method and Description |
---|---|
abstract void |
close(Status status,
Metadata trailers)
Close the call with the provided status.
|
Attributes |
getAttributes()
Returns properties of a single call.
|
String |
getAuthority()
Gets the authority this call is addressed to.
|
abstract MethodDescriptor<ReqT,RespT> |
getMethodDescriptor()
The
MethodDescriptor for the call. |
SecurityLevel |
getSecurityLevel()
Returns the level of security guarantee in communications
|
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.
|
public abstract void request(int numMessages)
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 synchronization.
numMessages
- the requested number of messages to be delivered to the listener.public abstract void sendHeaders(Metadata headers)
sendMessage(RespT)
or close(io.grpc.Status, io.grpc.Metadata)
.
Since Metadata
is not thread-safe, the caller must not access (read or write) headers
after this point.
headers
- metadata to send prior to any response body.IllegalStateException
- if close
has been called, a message has been sent, or
headers have already been sentpublic abstract void sendMessage(RespT message)
message
- response message.IllegalStateException
- if headers not sent or call is close(io.grpc.Status, io.grpc.Metadata)
dpublic boolean isReady()
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
, ServerCall.Listener.onReady()
will be called after isReady()
transitions to true
.
This abstract class's implementation always returns true
. Implementations generally
override the method.
public abstract void close(Status status, Metadata trailers)
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 (read or write) trailers
after this point.
This method implies the caller completed processing the RPC, but it does not imply the RPC
is complete. The call implementation will need additional time to complete the RPC and during
this time the client is still able to cancel the request or a network error might cause the
RPC to fail. If you wish to know when the call is actually completed/closed, you have to use
ServerCall.Listener.onComplete()
or ServerCall.Listener.onCancel()
instead. This method is not
necessarily invoked when Listener.onCancel() is called.
IllegalStateException
- if call is already close
dpublic abstract boolean isCancelled()
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.
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1704") public void setMessageCompression(boolean enabled)
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1704") public void setCompression(String compressor)
sendHeaders(io.grpc.Metadata)
.
The compressor to use will be looked up in the CompressorRegistry
. Default gRPC
servers support the "gzip" compressor.
It is safe to call this even if the client does not support the compression format chosen. The implementation will handle negotiation with the client and may fall back to no compression.
compressor
- the name of the compressor to use.IllegalArgumentException
- if the compressor name can not be found.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4692") public SecurityLevel getSecurityLevel()
Determining the level of security offered by the transport for RPCs on server-side. This can be approximated by looking for the SSLSession, but that doesn't work for ALTS and maybe some future TLS approaches. May return a lower security level when it cannot be determined precisely.
null
SecurityLevel enum@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1779") @Grpc.TransportAttr public Attributes getAttributes()
Attributes originate from the transport and can be altered by ServerTransportFilter
.
null
Attributes container@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/2924") @Nullable public String getAuthority()
null
if not available.public abstract MethodDescriptor<ReqT,RespT> getMethodDescriptor()
MethodDescriptor
for the call.