Working with Apache Thrift – 与Apache Thrift一起工作

最后修改: 2017年 2月 5日

1. Overview


In this article, we will discover how to develop cross-platform client-server applications with the help of RPC framework called Apache Thrift.

在这篇文章中,我们将发现如何在名为Apache Thrift的RPC框架的帮助下开发跨平台的客户端-服务器应用程序。

We will cover:


  • Defining data types and service interfaces with IDL
  • Installing the library and generating the sources for different languages
  • Implementing the defined interfaces in particular language
  • Implementing client/server software

If you want to go straight to examples, proceed straight to section 5.


2. Apache Thrift


Apache Thrift was originally developed by the Facebook development team and is currently maintained by Apache.

Apache Thrift最初由Facebook开发团队开发,目前由Apache维护。

In comparison to Protocol Buffers, which manage cross-platform object serialization/deserialization processes, Thrift mainly focuses on the communication layer between components of your system.

与管理跨平台对象序列化/反序列化过程的Protocol Buffers相比,Thrift主要关注系统组件间的通信层。

Thrift uses a special Interface Description Language (IDL) to define data types and service interfaces which are stored as .thrift files and used later as input by the compiler for generating the source code of client and server software that communicate over different programming languages.


To use Apache Thrift in your project, add this Maven dependency:

要在你的项目中使用Apache Thrift,需要添加这个Maven依赖。


You can find the latest version in the Maven repository.


3. Interface Description Language


As already described, IDL allows defining of communication interfaces in a neutral language. Below you will find the currently supported types.


3.1. Base Types


  • bool – a boolean value (true or false)
  • byte – an 8-bit signed integer
  • i16 – a 16-bit signed integer
  • i32 – a 32-bit signed integer
  • i64 – a 64-bit signed integer
  • double – a 64-bit floating point number
  • string – a text string encoded using UTF-8 encoding

3.2. Special Types


  • binary – a sequence of unencoded bytes
  • optional – a Java 8’s Optional type

3.3. Structs


Thrift structs are the equivalent of classes in OOP languages but without inheritance. A struct has a set of strongly typed fields, each with a unique name as an identifier. Fields may have various annotations (numeric field IDs, optional default values, etc.).

Thrift structs相当于OOP语言中的类,但没有继承性。一个结构有一组强类型的字段,每个字段有一个唯一的名字作为标识符。字段可以有各种注释(数字字段ID,可选的默认值,等等)。

3.4. Containers


Thrift containers are strongly typed containers:


  • list – an ordered list of elements
  • set – an unordered set of unique elements
  • map<type1,type2> – a map of strictly unique keys to values

Container elements may be of any valid Thrift type.


3.5. Exceptions


Exceptions are functionally equivalent to structs, except that they inherit from the native exceptions.


3.6. Services


Services are actually communication interfaces defined using Thrift types. They consist of a set of named functions, each with a list of parameters and a return type.


4. Source Code Generation


4.1. Language Support


There’s a long list of currently supported languages:


  • C++
  • C#
  • Go
  • Haskell
  • Java
  • Javascript
  • Node.js
  • Perl
  • PHP
  • Python
  • Ruby

You can check the full list here.


4.2. Using Library’s Executable File


Just download the latest version, build and install it if necessary, and use the following syntax:


cd path/to/thrift
thrift -r --gen [LANGUAGE] [FILENAME]

In the commands set above, [LANGUAGE] is one of the supported languages and [FILENAME] is a file with IDL definition.


Note the -r flag. It tells Thrift to generate code recursively once it notices includes in a given .thrift file.


4.3. Using Maven Plugin


Add the plugin in your pom.xml file:



After that just execute the following command:


mvn clean install

Note that this plugin will not have any further maintenance anymore. Please visit this page for more information.


5. Example of a Client-Server Application


5.1. Defining Thrift File


Let’s write some simple service with exceptions and structures:


namespace cpp com.baeldung.thrift.impl
namespace java com.baeldung.thrift.impl

exception InvalidOperationException {
    1: i32 code,
    2: string description

struct CrossPlatformResource {
    1: i32 id,
    2: string name,
    3: optional string salutation

service CrossPlatformService {

    CrossPlatformResource get(1:i32 id) throws (1:InvalidOperationException e),

    void save(1:CrossPlatformResource resource) throws (1:InvalidOperationException e),

    list <CrossPlatformResource> getList() throws (1:InvalidOperationException e),

    bool ping() throws (1:InvalidOperationException e)

As you can see, the syntax is pretty simple and self-explanatory. We define a set of namespaces (per implementation language), an exception type, a struct, and finally a service interface which will be shared across different components.


Then just store it as a service.thrift file.


5.2. Compiling and Generating a Code


Now it’s time to run a compiler which will generate the code for us:


thrift -r -out generated --gen java /path/to/service.thrift

As you might see, we added a special flag -out to specify the output directory for generated files. If you did not get any errors, the generated directory will contain 3 files:



Let’s generate a C++ version of the service by running:


thrift -r -out generated --gen cpp /path/to/service.thrift

Now we get 2 different valid implementations (Java and C++) of the same service interface.


5.3. Adding a Service Implementation


Although Thrift has done most of the work for us, we still need to write our own implementations of the CrossPlatformService. In order to do that, we just need to implement a CrossPlatformService.Iface interface:


public class CrossPlatformServiceImpl implements CrossPlatformService.Iface {

    public CrossPlatformResource get(int id) 
      throws InvalidOperationException, TException {
        return new CrossPlatformResource();

    public void save(CrossPlatformResource resource) 
      throws InvalidOperationException, TException {

    public List<CrossPlatformResource> getList() 
      throws InvalidOperationException, TException {
        return Collections.emptyList();

    public boolean ping() throws InvalidOperationException, TException {
        return true;

5.4. Writing a Server


As we said, we want to build a cross-platform client-server application, so we need a server for it. The great thing about Apache Thrift is that it has its own client-server communication framework which makes communication a piece of cake:

正如我们所说,我们想建立一个跨平台的客户-服务器应用程序,所以我们需要一个服务器。Apache Thrift的伟大之处在于它有自己的客户-服务器通信框架,这使得通信变得小菜一碟。

public class CrossPlatformServiceServer {
    public void start() throws TTransportException {
        TServerTransport serverTransport = new TServerSocket(9090);
        server = new TSimpleServer(new TServer.Args(serverTransport)
          .processor(new CrossPlatformService.Processor<>(new CrossPlatformServiceImpl())));

        System.out.print("Starting the server... ");



    public void stop() {
        if (server != null && server.isServing()) {
            System.out.print("Stopping the server... ");



First thing is to define a transport layer with the implementation of TServerTransport interface (or abstract class, to be more precise). Since we are talking about server, we need to provide a port to listen to. Then we need to define a TServer instance and choose one of the available implementations:


  • TSimpleServer – for simple server
  • TThreadPoolServer – for multi-threaded server
  • TNonblockingServer – for non-blocking multi-threaded server

And finally, provide a processor implementation for chosen server which was already generated for us by Thrift, i.e. CrossPlatofformService.Processor class.


5.5. Writing a Client


And here is the client’s implementation:


TTransport transport = new TSocket("localhost", 9090);;

TProtocol protocol = new TBinaryProtocol(transport);
CrossPlatformService.Client client = new CrossPlatformService.Client(protocol);

boolean result =;


From a client perspective, the actions are pretty similar.


First of all, define the transport and point it to our server instance, then choose the suitable protocol. The only difference is that here we initialize the client instance which was, once again, already generated by Thrift, i.e. CrossPlatformService.Client class.


Since it is based on .thrift file definitions we can directly call methods described there. In this particular example, will make a remote call to the server which will respond with true.

由于它是基于.thrift文件定义的,我们可以直接调用其中描述的方法。在这个特殊的例子中, 将对服务器进行远程调用,服务器将回应true

6. Conclusion


In this article, we’ve shown you the basic concepts and steps in working with Apache Thrift, and we’ve shown how to create a working example which utilizes Thrift library.

在这篇文章中,我们向你展示了使用Apache Thrift的基本概念和步骤,我们还展示了如何利用Thrift库创建一个工作实例。

As usually, all the examples can be always found over in the GitHub repository.