gRPC tutorial introduction

• Background
• Assumptions
• Prerequisites
• Sample service
• Build and run sample service
• Try writing blog service yourself

In this tutorial, you'll learn how to build a gRPC service with Armeria. This tutorial is based on a sample service, a minimal blog service, with which you can create, read, update, and delete blog posts.

Follow this tutorial to write a service yourself or try running the sample service right away.

Background

Before we get our hands on the tutorial, let's swiftly go over Armeria's gRPC features. Armeria supports features that the upstream (gRPC-Java) does not support.

• Protocol
  • HTTP/1.1
  • HTTP/2 (upstream)
• Serialization format - Framed
  • gRPC protobuf: application/grpc+proto (upstream)
  • gRPC JSON: application/grpc+json
  • gRPC Web: application/grpc-web+proto
  • gRPC Web JSON: application/grpc-web+json
  • gRPC Web Text: application/grpc-web-text+proto
• Serialization format - Unframed
  • Protobuf: application/protobuf
  • JSON: application/json
• HTTP level decorator
• Richer error handling
• HTTP-to-JSON transcoding
• Customizing service method paths
• gRPC documentation service
• gRPC status monitoring with MetricCollectingService

Assumptions

This tutorial assumes that you have:

• Experience in building services in Java
• Experience in Java frameworks for server-side programming
• Understanding of gRPC and experience in implementing gRPC services

Prerequisites

To run and develop the sample service, you need JDK 11 or higher.

Sample service

The sample service provides implementations of CRUD operations as specified below.

The sample service code consists of the following folders and files.

grpc/
├─ src/
│  ├─ main/
│  │  ├─ java/
│  │  │  ├─ example.armeria.server.blog.grpc/
│  │  │  │  ├─ BlogNotFoundException.java
│  │  │  │  ├─ BlogService.java
│  │  │  │  ├─ GrpcExceptionHandler.java
│  │  │  │  └─ Main.java
│  │  ├─ proto/
│  │  │  └─ blog.proto
│  └─ test/
│     └─ java/
│        └─ example.armeria.server.blog.grpc/
│           └─ BlogServiceTest.java
└─ build.gradle

Build and run sample service

The sample service provides you implementations of CRUD operations with corresponding service methods. Have a go at running the sample gRPC service and see the outcome of this tutorial. Using Armeria's Documentation Service, you can easily verify a server is running, receiving requests and sending responses.

1. Download the code from here.
2. Build the sample service using the Gradle Wrapper.

   $ ./gradlew build

3. Run the sample service again, using the Gradle Wrapper.

   $ ./gradlew run

4. Open the Documentation service page on your web browser at http://127.0.0.1:8080/docs.

Try writing blog service yourself

Use the sample service's build.gradle file to start building the service from scratch. Below is a part of the build.gradle file for the sample service. This tutorial uses protobuf-gradle-plugin to generate stubs from proto files.

apply plugin: 'java'
apply plugin: 'idea'
apply plugin: 'eclipse'

repositories {
  mavenCentral()
}

dependencies {
  implementation "com.linecorp.armeria:armeria:1.31.1"

  implementation "com.linecorp.armeria:armeria-grpc:1.31.1"

  // Logging
  runtimeOnly "ch.qos.logback:logback-classic:1.5.12"

  testImplementation "org.junit.jupiter:junit-jupiter:5.11.3"

  testImplementation "com.linecorp.armeria:armeria-junit5:1.31.1"

  testImplementation "org.assertj:assertj-core:3.26.3"
}

Start writing the blog service yourself by following the tutorial step by step:

1. Define a service
2. Run a service
3. Implement CREATE
4. Implement READ
5. Implement UPDATE
6. Implement DELETE