///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2019, 2020 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

:pagename: grpc-client-introduction
:description: Helidon gRPC Client Introduction
:keywords: helidon, grpc, java

= gRPC Client Introduction

Helidon gRPC Client provides a framework for creating link:http://grpc.io/[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

The <<about/04_managing-dependencies.adoc, Managing Dependencies>> page describes how you
should declare dependency management for Helidon applications. Then declare the following dependency in your project:

[source,xml]
----
<dependency>
    <groupId>io.helidon.grpc</groupId>
    <artifactId>helidon-grpc-client</artifactId> <!--1-->
</dependency>
----

<1> Declare dependency on Helidon gRPC Client.

== Quick Start

First, create and run a minimalist `HelloService` gRPC server application as described in the
https://github.com/oracle/helidon/blob/master/docs/src/main/docs/grpc/01_introduction.adoc[gRPC Server] documentation.

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

[source,java]
----
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)

}
----

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.
