Thrift 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 an Apache Thrift 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 start, let's swiftly go over Armeria's Thrift features:

Transport over HTTP/1.1 or HTTP/2.
Support for TBINARY, TCOMPACT, TJSON and TTEXT serialization formats.
RPC level decorator support for both client and server.
- Out of the box support for circuit breaker, retries, metric collection and more.
Full-fledged Thrift documentation service.

Assumptions

This tutorial assumes that you have:

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

Prerequisites

To run and develop the sample service, set your computer with the following requirements:

JDK 11 or higher
Thrift compiler: Install a Thrift compiler by either building from source or using a package manager like brew or apt depending on your environment.

Sample service

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

Operation	Method
Create	`createBlogPost()`
Read	`getBlogPost()`, `listBlogPosts()`
Update	`updateBlogPost()`
Delete	`deleteBlogPost()`

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

thrift/
├─ src/
│  ├─ main/
│  │  ├─ java/
│  │  │  ├─ example.armeria.server.blog.thrift/
│  │  │  │  ├─ BlogClient.java
│  │  │  │  ├─ BlogServiceExceptionHandler.java
│  │  │  │  ├─ BlogServiceImpl.java
│  │  │  │  └─ Main.java
│  │  ├─ thrift/
│  │  │  └─ blog.thrift
│  └─ test/
│     └─ java/
│        └─ example.armeria.server.blog.thrift/
│           └─ BlogServiceTest.java
└─ build.gradle

To keep our focus on Armeria, this tutorial and the sample service implement memory-based operations instead of using a database.

Build and run sample service

Try running the sample 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.

Download the code from here.
Build the sample service using the Gradle Wrapper.
```
$ ./gradlew build
```
Run the sample service again, using the Gradle Wrapper.
```
$ ./gradlew run
```
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 thrift-gradle-plugin to compile Thrift IDL files and generate stubs.

build.gradle

plugins {
  id "org.jruyi.thrift" version "0.4.2"
  id "application"
  id "idea"
  id "eclipse"
}

repositories {
  mavenCentral()
}

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

  implementation "com.linecorp.armeria:armeria-thrift0.17:1.31.2"

  // 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.2"

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

application {
  mainClass.set('example.armeria.server.blog.thrift.Main')
}

tasks.withType(Test) {
  useJUnitPlatform()
}

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