Top Description Inners Constructors Methods
io.grpc

public abstract Class ServerCall<ReqT, RespT>

extends Object
Class Inheritance
Known Direct Subclasses
io.grpc.PartialForwardingServerCall
Type Parameters
<ReqT>
parsed type of request message.
<RespT>
parsed type of response message.
Imports
javax.annotation.Nullable
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.

DO NOT MOCK: Use InProcessTransport and make a fake server instead.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public abstract static class
ServerCall.Listener<ReqT>

Callbacks for consuming incoming RPC messages.

Constructor Summary

AccessConstructor and Description
public
ServerCall()

Method Summary

Modifier and TypeMethod and Description
public abstract void
close(Status status, Metadata trailers)

Close the call with the provided status.

public Attributes

Returns:

non-null Attributes container
getAttributes()

Returns properties of a single call.

public String

Returns:

the authority string. null if not available.
getAuthority()

Gets the authority this call is addressed to.

public abstract MethodDescriptor<ReqT, RespT>
getMethodDescriptor()

The MethodDescriptor for the call.

public SecurityLevel

Returns:

non-null SecurityLevel enum
getSecurityLevel()

Returns the level of security guarantee in communications

Determining the level of security offered by the transport for RPCs on server-side.

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.

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.
numMessages)

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

public abstract void
sendHeaders(Metadata
metadata to send prior to any response body.
headers)

Send response header metadata prior to sending a response message.

public abstract void
sendMessage(RespT
response message.
message)

Send a response message.

public void
setCompression(String
the name of the compressor to use.
compressor)

Sets the compression algorithm for this call.

public void
setMessageCompression(boolean enabled)

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

ServerCallback to summary
public ServerCall()

Method Detail

closeback to summary
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 Listener#onComplete notification should be expected, independent of status. Otherwise 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 Listener#onComplete or Listener#onCancel instead. This method is not necessarily invoked when Listener.onCancel() is called.

Exceptions
IllegalStateException:
if call is already closed
getAttributesback to summary
public Attributes getAttributes()

Returns properties of a single call.

Attributes originate from the transport and can be altered by ServerTransportFilter.

Returns:Attributes

non-null Attributes container

Annotations
@ExperimentalApi:https://github.com/grpc/grpc-java/issues/1779
@TransportAttr
getAuthorityback to summary
public String getAuthority()

Gets the authority this call is addressed to.

Returns:String

the authority string. null if not available.

Annotations
@Nullable
getMethodDescriptorback to summary
public abstract MethodDescriptor<ReqT, RespT> getMethodDescriptor()

The MethodDescriptor for the call.

getSecurityLevelback to summary
public SecurityLevel getSecurityLevel()

Returns the level of security guarantee in communications

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.

Returns:SecurityLevel

non-null SecurityLevel enum

Annotations
@ExperimentalApi:https://github.com/grpc/grpc-java/issues/4692
isCancelledback to summary
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.

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.

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). 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.

Parameters
numMessages:int

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

sendHeadersback to summary
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 or close.

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

Parameters
headers:Metadata

metadata to send prior to any response body.

Exceptions
IllegalStateException:
if close has been called, a message has been sent, or headers have already been sent
sendMessageback to summary
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:RespT

response message.

Exceptions
IllegalStateException:
if headers not sent or call is closed
setCompressionback to summary
public void setCompression(String compressor)

Sets the compression algorithm for this call. This compression is utilized for sending. If the server does not support the compression algorithm, the call will fail. This method may only be called before sendHeaders. 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.

Parameters
compressor:String

the name of the compressor to use.

Exceptions
IllegalArgumentException:
if the compressor name can not be found.
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.

io.grpc back to summary

public abstract Class ServerCall.Listener<ReqT>

extends Object
Class Inheritance
Known Direct Subclasses
io.grpc.PartialForwardingServerCallListener
Callbacks for consuming incoming RPC messages.

Any contexts are guaranteed to arrive before any messages, which are guaranteed before half close, which is guaranteed before completion.

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
onCancel()

The call was cancelled and the server is encouraged to abort processing to save resources, since the client will not process any further messages.

public void
onComplete()

The call is considered complete and onCancel is guaranteed not to be called.

public void
onHalfClose()

The client completed all message sending.

public void
onMessage(ReqT
a received request message.
message)

A request message has been received.

public void
onReady()

This indicates that the call 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

onCancelback to summary
public void onCancel()

The call was cancelled and the server is encouraged to abort processing to save resources, since the client will not process any further messages. Cancellations can be caused by timeouts, explicit cancellation by the client, network errors, etc.

There will be no further callbacks for the call.

onCompleteback to summary
public void onComplete()

The call is considered complete and onCancel is guaranteed not to be called. However, the client is not guaranteed to have received all messages.

There will be no further callbacks for the call.

onHalfCloseback to summary
public void onHalfClose()

The client completed all message sending. However, the call may still be cancelled.

onMessageback to summary
public void onMessage(ReqT message)

A request message has been received. For streaming calls, there may be zero or more request messages.

Parameters
message:ReqT

a received request message.

onReadyback to summary
public void onReady()

This indicates that the call 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 call.

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.