Thrift tutorial introduction
Table of contents
- 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
andTTEXT
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
orapt
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
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.30.1"
implementation "com.linecorp.armeria:armeria-thrift0.17:1.30.1"
// Logging
runtimeOnly "ch.qos.logback:logback-classic:1.4.14"
testImplementation "org.junit.jupiter:junit-jupiter:5.10.3"
testImplementation "com.linecorp.armeria:armeria-junit5:1.30.1"
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: