Package io.grpc.stub

Class BlockingClientCall<ReqT,RespT>

java.lang.Object

io.grpc.stub.BlockingClientCall<ReqT,RespT>

Type Parameters:

ReqT - Type of the Request Message

RespT - Type of the Response Message

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
public final class BlockingClientCall<ReqT,RespT>
extends Object

Represents a bidirectional streaming call from a client. Allows in a blocking manner, sending over the stream and receiving from the stream. Also supports terminating the call. Wraps a ClientCall and converts from async communication to the sync paradigm used by the various blocking stream methods in ClientCalls which are used by the generated stubs.

Supports separate threads for reads and writes, but only 1 of each

Read methods consist of:

• read()
• read(long timeout, TimeUnit unit)
• hasNext()
• cancel(String, Throwable)

Write methods consist of:

• write(Object)
• write(Object, long timeout, TimeUnit unit)
• halfClose()

Method Summary

Modifier and Type	Method	Description
void	cancel(String message, Throwable cause)	Cancel stream and stop any further writes.
void	halfClose()	Indicate that no more writes will be done and the stream will be closed from the client side.
boolean	hasNext()	Wait for a value to be available from the server.
RespT	read()	Wait if necessary for a value to be available from the server.
RespT	read(long timeout, TimeUnit unit)	Wait with timeout, if necessary, for a value to be available from the server.
boolean	write(ReqT request)	Send a value to the stream for sending to server, wait if necessary for the grpc stream to be ready.
boolean	write(ReqT request, long timeout, TimeUnit unit)	Send a value to the stream for sending to server, wait if necessary for the grpc stream to be ready up to specified timeout.

Methods inherited from class java.lang.Object

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

Method Detail

read

public RespT read()
           throws InterruptedException,
                  StatusException

Wait if necessary for a value to be available from the server. If there is an available value return it immediately, if the stream is closed return a null. Otherwise, wait for a value to be available or the stream to be closed

Returns:

value from server or null if stream has been closed

Throws:

StatusException - If the stream has closed in an error state

InterruptedException

read

public RespT read(long timeout,
                  TimeUnit unit)
           throws InterruptedException,
                  TimeoutException,
                  StatusException

Wait with timeout, if necessary, for a value to be available from the server. If there is an available value, return it immediately. If the stream is closed return a null. Otherwise, wait for a value to be available, the stream to be closed or the timeout to expire.

Parameters:

timeout - how long to wait before giving up. Values <= 0 are no wait

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

value from server or null (if stream has been closed)

Throws:

TimeoutException - if no read becomes ready before the specified timeout expires

StatusException - If the stream has closed in an error state

InterruptedException

hasNext

public boolean hasNext()
                throws InterruptedException,
                       StatusException

Wait for a value to be available from the server. If there is an available value, return true immediately. If the stream was closed with Status.OK, return false. If the stream was closed with an error status, throw a StatusException. Otherwise, wait for a value to be available or the stream to be closed.

Returns:

True when there is a value to read. Return false if stream closed cleanly.

Throws:

StatusException - If the stream was closed in an error state

InterruptedException

write

public boolean write(ReqT request)
              throws InterruptedException,
                     StatusException

Send a value to the stream for sending to server, wait if necessary for the grpc stream to be ready.

If write is not legal at the time of call, immediately returns false

NOTE: This method will return as soon as it passes the request to the grpc stream layer. It will not block while the message is being sent on the wire and returning true does not guarantee that the server gets the message.

WARNING: Doing only writes without reads can lead to deadlocks. This is because flow control, imposed by networks to protect intermediary routers and endpoints that are operating under resource constraints, requires reads to be done in order to progress writes. Furthermore, the server closing the stream will only be identified after the last sent value is read.

Parameters:

request - Message to send to the server

Returns:

true if the request is sent to stream, false if skipped

Throws:

StatusException - If the stream has closed in an error state

InterruptedException

write

public boolean write(ReqT request,
                     long timeout,
                     TimeUnit unit)
              throws InterruptedException,
                     TimeoutException,
                     StatusException

Send a value to the stream for sending to server, wait if necessary for the grpc stream to be ready up to specified timeout.

If write is not legal at the time of call, immediately returns false

NOTE: This method will return as soon as it passes the request to the grpc stream layer. It will not block while the message is being sent on the wire and returning true does not guarantee that the server gets the message.

WARNING: Doing only writes without reads can lead to deadlocks as a result of flow control. Furthermore, the server closing the stream will only be identified after the last sent value is read.

Parameters:

request - Message to send to the server

timeout - How long to wait before giving up. Values <= 0 are no wait

unit - A TimeUnit determining how to interpret the timeout parameter

Returns:

true if the request is sent to stream, false if skipped

Throws:

TimeoutException - if write does not become ready before the specified timeout expires

StatusException - If the stream has closed in an error state

InterruptedException

cancel

public void cancel(String message,
                   Throwable cause)

Cancel stream and stop any further writes. Note that some reads that are in flight may still happen after the cancel.

Parameters:

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

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

halfClose

public void halfClose()

Indicate that no more writes will be done and the stream will be closed from the client side.

See Also:

ClientCall.halfClose()