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:

Write methods consist of:

  • 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 Details

    • 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: