Thrift tutorial introduction

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

tip

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.

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

repositories {
mavenCentral()
}

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

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

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

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

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

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

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:

Background​

Assumptions​

Prerequisites​

Sample service​

Build and run sample service​

Try writing blog service yourself​