Package io.vertx.grpc.client

## Interface GrpcClientRequest<Req,​Resp>

- All Superinterfaces:
    `GrpcWriteStream<Req>`, `StreamBase`, `WriteStream<Req>`

      public interface GrpcClientRequest<Req,​Resp>
      extends GrpcWriteStream<Req>

  A request to a gRPC server.

  You interact with the remote service with gRPC generated messages or protobuf encoded messages.

  Before sending a request you need to set {@link #serviceName)} and {@link #methodName)} or alternatively the service `fullMethodName(java.lang.String)`.

  Writing a request message will send the request to the service:

  - To send a unary request, just call `#end(Req)`
  - To send a streaming request, call `#write(Req)` any time you need and then `WriteStream.end()`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `HttpConnection` | `connection()` |
    `Timer` | `deadline()` |
    `GrpcClientRequest<Req,​Resp>` | `drainHandler​(Handler<Void> handler)` | Set a drain handler on the stream.
    `GrpcClientRequest<Req,​Resp>` | `encoding​(String encoding)` | Set the stream encoding, e.g.
    `GrpcClientRequest<Req,​Resp>` | `exceptionHandler​(Handler<Throwable> handler)` | Set an exception handler on the write stream.
    `GrpcClientRequest<Req,​Resp>` | `format​(WireFormat format)` | Set the stream format, e.g.
    `GrpcClientRequest<Req,​Resp>` | `fullMethodName​(String fullMethodName)` | Set the full method name to call, it must follow the format `package-name + '.' + service-name + '/' + method-name` or an `IllegalArgumentException` is thrown.
    `GrpcClientRequest<Req,​Resp>` | `idleTimeout​(long timeout)` | Sets the amount of time after which, if the request does not return any data within the timeout period, the request/response is cancelled and the related futures.
    `GrpcClientRequest<Req,​Resp>` | `methodName​(String methodName)` | Set the method name to call.
    `Future<GrpcClientResponse<Req,​Resp>>` | `response()` |
    `default Future<GrpcClientResponse<Req,​Resp>>` | `send​(ReadStream<Req> body)` |
    `default Future<GrpcClientResponse<Req,​Resp>>` | `send​(Req item)` |
    `GrpcClientRequest<Req,​Resp>` | `serviceName​(ServiceName serviceName)` | Set the service name to call.
    `GrpcClientRequest<Req,​Resp>` | `setWriteQueueMaxSize​(int maxSize)` | Set the maximum size of the write queue to `maxSize`.
    `GrpcClientRequest<Req,​Resp>` | `timeout​(long timeout, TimeUnit unit)` | Set a `grpc-timeout` header to be sent to the server to indicate the client expects a response with a timeout.

    - ### Methods inherited from interface io.vertx.grpc.common.GrpcWriteStream

      `cancel, endMessage, headers, writeMessage`

    - ### Methods inherited from interface io.vertx.core.streams.WriteStream

      `end, end, write, writeQueueFull`

- - ### Method Detail

    - #### encoding

          GrpcClientRequest<Req,​Resp> encoding​(String encoding)

      Description copied from interface: `GrpcWriteStream`

      Set the stream encoding, e.g. `identity` or `gzip`,

      - The encoding must be set before sending any message, otherwise `identity` will be used.
      - The encoding should also match the opposite endpoint expectations.
      Specified by:
        `encoding` in interface `GrpcWriteStream<Req>`
      Parameters:
        `encoding` - the target message encoding
      Returns:
        a reference to this, so the API can be used fluently

    - #### format

          GrpcClientRequest<Req,​Resp> format​(WireFormat format)

      Description copied from interface: `GrpcWriteStream`
      Set the stream format, e.g. `proto` or `json`. It must be called before sending any message, otherwise `proto` will be used.
      Specified by:
        `format` in interface `GrpcWriteStream<Req>`
      Parameters:
        `format` - the message format
      Returns:
        a reference to this, so the API can be used fluently

    - #### fullMethodName

          GrpcClientRequest<Req,​Resp> fullMethodName​(String fullMethodName)

      Set the full method name to call, it must follow the format `package-name + '.' + service-name + '/' + method-name` or an `IllegalArgumentException` is thrown.

      It must be called before sending the request otherwise an `IllegalStateException` is thrown.

      Parameters:
        `fullMethodName` - the full method name to call
      Returns:
        a reference to this, so the API can be used fluently

    - #### serviceName

          GrpcClientRequest<Req,​Resp> serviceName​(ServiceName serviceName)

      Set the service name to call.

      It must be called before sending the request otherwise an `IllegalStateException` is thrown.

      Parameters:
        `serviceName` - the service name to call
      Returns:
        a reference to this, so the API can be used fluently

    - #### methodName

          GrpcClientRequest<Req,​Resp> methodName​(String methodName)

      Set the method name to call.

      It must be called before sending the request otherwise an `IllegalStateException` is thrown.

      Parameters:
        `methodName` - the method name to call
      Returns:
        a reference to this, so the API can be used fluently

    - #### response

          Future<GrpcClientResponse<Req,​Resp>> response()

      Returns:
        the gRPC response

    - #### exceptionHandler

          GrpcClientRequest<Req,​Resp> exceptionHandler​(Handler<Throwable> handler)

      Description copied from interface: `WriteStream`
      Set an exception handler on the write stream.
      Specified by:
        `exceptionHandler` in interface `GrpcWriteStream<Req>`
      Specified by:
        `exceptionHandler` in interface `StreamBase`
      Specified by:
        `exceptionHandler` in interface `WriteStream<Req>`
      Parameters:
        `handler` - the exception handler
      Returns:
        a reference to this, so the API can be used fluently

    - #### setWriteQueueMaxSize

          GrpcClientRequest<Req,​Resp> setWriteQueueMaxSize​(int maxSize)

      Description copied from interface: `WriteStream`
      Set the maximum size of the write queue to `maxSize`. You will still be able to write to the stream even if there is more than `maxSize` items in the write queue. This is used as an indicator by classes such as `Pipe` to provide flow control.

      The value is defined by the implementation of the stream, e.g in bytes for a `NetSocket`, etc...
      Specified by:
        `setWriteQueueMaxSize` in interface `GrpcWriteStream<Req>`
      Specified by:
        `setWriteQueueMaxSize` in interface `WriteStream<Req>`
      Parameters:
        `maxSize` - the max size of the write stream
      Returns:
        a reference to this, so the API can be used fluently

    - #### drainHandler

          GrpcClientRequest<Req,​Resp> drainHandler​(Handler<Void> handler)

      Description copied from interface: `WriteStream`
      Set a drain handler on the stream. If the write queue is full, then the handler will be called when the write queue is ready to accept buffers again. See `Pipe` for an example of this being used.

      The stream implementation defines when the drain handler, for example it could be when the queue size has been reduced to `maxSize / 2`.

      Specified by:
        `drainHandler` in interface `GrpcWriteStream<Req>`
      Specified by:
        `drainHandler` in interface `WriteStream<Req>`
      Parameters:
        `handler` - the handler
      Returns:
        a reference to this, so the API can be used fluently

    - #### timeout

          GrpcClientRequest<Req,​Resp> timeout​(long timeout,
                                                    TimeUnit unit)

      Set a `grpc-timeout` header to be sent to the server to indicate the client expects a response with a timeout.

      When the request handle deadline a timer will be set when sending the request to cancel the request when the response has not been received in time.

      Parameters:
        `timeout` -
        `unit` -
      Returns:

    - #### deadline

          Timer deadline()

      Returns:
        the request deadline or `null` when no deadline has been scheduled

    - #### idleTimeout

          GrpcClientRequest<Req,​Resp> idleTimeout​(long timeout)

      Sets the amount of time after which, if the request does not return any data within the timeout period, the request/response is cancelled and the related futures.
      Parameters:
        `timeout` - the amount of time in milliseconds.
      Returns:
        a reference to this, so the API can be used fluently

    - #### connection

          HttpConnection connection()

      Returns:
        the underlying HTTP connection

    - #### send

          default Future<GrpcClientResponse<Req,​Resp>> send​(Req item)

    - #### send

          default Future<GrpcClientResponse<Req,​Resp>> send​(ReadStream<Req> body)