== Vert.x gRPC/IO Client

Vert.x gRPC/IO Client extends the Vert.x gRPC client with _grpc-java_ integration.

This client provides a generated stub approach with a gRPC Channel

=== Using Vert.x gRPC/IO Client

To use Vert.x gRPC/IO Client, add the following dependency to the _dependencies_ section of your build descriptor:

* Maven (in your `pom.xml`):

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-grpcio-client</artifactId>
  <version>5.0.2</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
dependencies {
  compile 'io.vertx:vertx-grpcio-client:5.0.2'
}
----

=== gRPC channel

The Vert.x gRPC/IO Client provides a gRPC channel to use with _grpc-java_ generated client classes.

[source,java]
----
GrpcIoClientChannel channel = new GrpcIoClientChannel(client, SocketAddress.inetSocketAddress(443, "example.com"));

GreeterGrpc.GreeterStub greeter = GreeterGrpc.newStub(channel);

StreamObserver<HelloReply> observer = new StreamObserver<HelloReply>() {
  @Override
  public void onNext(HelloReply value) {
    // Process response
  }

  @Override
  public void onCompleted() {
    // Done
  }

  @Override
  public void onError(Throwable t) {
    // Something went bad
  }
};

greeter.sayHello(HelloRequest.newBuilder().setName("Bob").build(), observer);
----

Timeout and deadlines are supported through the usual gRPC API.

[source,java]
----
GreeterGrpc.GreeterStub greeter = GreeterGrpc.newStub(channel).withDeadlineAfter(10, TimeUnit.SECONDS);

greeter.sayHello(HelloRequest.newBuilder().setName("Bob").build(), observer);
----

Deadline are cascaded, e.g. when the current `io.grpc.Context` carries a deadline and the stub has no explicit deadline
set, the client automatically inherits the implicit deadline. Such deadline can be set when using a stub within a gRPC server
call.

=== Idiomatic gRPC/IO client

The <<vertx-grpc-protoc-plugin,Vert.x gRPC protoc plugin>> supports the generation of gRPC/IO client code:

- `examples/Greeter.java`
- `examples/GreeterClient.java`
- `examples/GreeterGrpcIo.java`

By default, `GreeterGrpcIo` is not generated, to activate it you need to tell the Vert.x gRPC protoc plugin to generate it:

[source,xml]
----
<protocPlugin>
  <id>vertx-grpc-protoc-plugin2</id>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-grpc-protoc-plugin2</artifactId>
  <version>${stack.version}</version>
  <mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
  <args>
    <arg>grpc-io</arg>
  </args>
</protocPlugin>
----

The `GreeterGrpcIo` provides a client stub that uses the Vert.x gRPC/IO Client to interact with a service:

[source,java]
----
GrpcIoClientChannel channel = new GrpcIoClientChannel(client, SocketAddress.inetSocketAddress(443, "example.com"));

GreeterGrpcIo.GreeterStub greeter = GreeterGrpcIo.newStub(vertx, channel);

Future<HelloReply> future = greeter.sayHello(HelloRequest.newBuilder().setName("Bob").build());

future
  .onSuccess(reply -> {
    // Process response
  })
  .onFailure(err -> {
    // Something went bad
  });
----

You can read the <<idiomatic-client, idiomatic client>> section to learn more about it.