gRPC Client Introduction

Helidon gRPC Client provides a framework for creating gRPC client applications. The client framework allows a uniform way to access gRPC services that use either Protobuf or some custom serialization format. It also allows access to gRPC services that use either Java serialization, Protobuf or a custom serialization format.

The class GrpcServiceClient acts as the client object for accessing a gRPC service. Creating a GrpcServiceClient involves:

  1. Creating a ClientServiceDescriptor which describes the methods in the service that this client can invoke.
  2. Creating a gRPC Channel through which the client communicates with the server.

In later sections in this document, you will see how to customize both ClientServiceDescriptor and the Channel.

Maven Coordinates

To enable gRPC Client add the following dependency to your project’s pom.xml (see Managing Dependencies).

<dependency>
    <groupId>io.helidon.grpc</groupId>
    <artifactId>helidon-grpc-client</artifactId>
</dependency>
Copied

Quick Start

First, create and run a minimalist HelloService gRPC server application as described in the gRPC Server documentation.

Assuming that the server is running on port 1408, create a client as follows:

public static void main(String[] args) throws Exception {
    ClientServiceDescriptor descriptor = ClientServiceDescriptor.builder(HelloService.class)    // (1)
                                                                .unary("SayHello")              // (2)
                                                                .build();

    Channel channel = ManagedChannelBuilder.forAddress("localhost", 1408)                       // (3)
                                           .usePlaintext()
                                           .build();

    GrpcServiceClient client = GrpcServiceClient.create(channel, descriptor);                   // (4)

    CompletionStage<String> future = client.unary("SayHello", "Helidon gRPC!!");                                // (5)
    System.out.println(future.get());                                                           // (6)

}
Copied
  1. Create a ClientServiceDescriptor for the HelloService.
  2. Add the SayHello unary method to the ClientServiceDescriptor. This method, by default, uses Java serialization for marshalling and unmarshalling the request and response values.
  3. Create a gRPC Channel that is communicates with the server that is running in localhost and on port 1408 (using plaintext).
  4. Create the GrpcServiceClient that uses the above Channel and ClientServiceDescriptor. GrpcClientService represents a client that can be used to define the set of methods described by the specified ClientServiceDescriptor. In our case, the ClientServiceDescriptor defines one unary method called SayHello.
  5. Invoke the SayHello method which returns a CompletionStage<String>.
  6. Print the result.

The example above creates a very simple client to the gRPC server that by default uses Java serialization to marshall requests and responses.

We will look into deployment of "standard" gRPC services that use Protobuf for request and response marshalling, as well as how you can configure custom marshallers, later in this document.