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

    Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

    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.

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

= gRPC Server Introduction
:pagename: grpc-server-introduction
:description: Helidon gRPC Server Introduction
:keywords: helidon, grpc, java

Helidon gRPC Server provides a framework for creating link:http://grpc.io/[gRPC] applications.

== Experimental

WARNING: The Helidon gRPC feature is currently experimental and the APIs are
 subject to changes until gRPC support is stabilized.

== Quick Start

Here is the code for a minimalist gRPC application that runs on a default port (1408):

[source,java]
----
    public static void main(String[] args) throws Exception {
        GrpcServer grpcServer = GrpcServer
                .create(GrpcRouting.builder()
                                .register(new HelloService()) // <1>
                                .build())
                .start() // <2>
                .toCompletableFuture()
                .get(10, TimeUnit.SECONDS); // <3>

        System.out.println("gRPC Server started at: http://localhost:" + grpcServer.port()); // <4>
    }

    static class HelloService implements GrpcService { <5>
        @Override
        public void update(ServiceDescriptor.Rules rules) {
            rules.unary("SayHello", ((request, responseObserver) -> complete(responseObserver, "Hello World!"))); // <6>
        }
    }
----

<1> Register gRPC service.
<2> Start the server.
<3> Wait for the server to start while throwing possible errors as exceptions.
<4> The server is bound to a default port (1408).
<5> Implement the simplest possible gRPC service.
<6> Add unary method `HelloService/SayHello` to the service definition.

The example above deploys a very simple service 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.

== Maven Coordinates

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

[source,xml,subs="verbatim,attributes"]
----
<dependency>
    <groupId>io.helidon.grpc</groupId>
    <artifactId>helidon-grpc-server</artifactId> <!--1-->
</dependency>
----

<1> Dependency on gRPC Server.
