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:

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.

OperationMethod
CreatecreateBlogPost()
ReadgetBlogPost(), listBlogPosts()
UpdateupdateBlogPost()
DeletedeleteBlogPost()

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

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.

  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 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.28.0"

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

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

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

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

  testImplementation "org.assertj:assertj-core:3.25.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:

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