Running a Thrift service

tip

Visit armeria-examples to find a fully working example.

Let's assume we have the following Thrift IDL:

namespace java com.example.thrift.hello

service HelloService {
    string hello(1:string name)
}

The Apache Thrift compiler will produce some Java code under the com.example.thrift.hello package. The most noteworthy one is HelloService.java which defines the service interfaces we will implement:

import org.apache.thrift.TException;
import org.apache.thrift.async.AsyncMethodCallback;

public class HelloService {
    public interface Iface {
        public String hello(String name) throws TException;
    }

    public interface AsyncIface {
        public void hello(String name, AsyncMethodCallback<String> resultHandler) throws TException;
    }
    ...
}

If you are interested in going fully asynchronous, it is recommended to implement the AsyncIface interface, although it is easier to implement the synchronous Iface interface:

import org.apache.thrift.TException;
import org.apache.thrift.async.AsyncMethodCallback;

public class MyHelloService implements HelloService.AsyncIface {
    @Override
    public void hello(String name, AsyncMethodCallback<String> resultHandler) {
        resultHandler.onComplete("Hello, " + name + '!');
    }
}

// or synchronously:
public class MySynchronousHelloService implements HelloService.Iface {
    @Override
    public String hello(String name) throws TException {
        return "Hello, " + name + '!';
    }
}

THttpService

Once you've finished the implementation of the interface, you need to wrap it with a THttpService and add it to the ServerBuilder:

ServerBuilder sb = Server.builder();
...
sb.service("/hello", THttpService.of(new MyHelloService()));
...
Server server = sb.build();
server.start();

Serialization formats

THttpService supports four Thrift serialization formats: TBINARY, TCOMPACT, TJSON and TTEXT. It chooses the serialization format based on the value of the content-type HTTP header.

Header value	Serialization format
Unspecified or application/x-thrift	Use the default serialization format (TBINARY unless specified)
application/x-thrift; protocol=TBINARY or vnd.apache.thrift.binary	TBINARY
application/x-thrift; protocol=TCOMPACT or vnd.apache.thrift.compact	TCOMPACT
application/x-thrift; protocol=TJSON or vnd.apache.thrift.json	TJSON
application/x-thrift; protocol=TTEXT or vnd.apache.thrift.text	TTEXT

To change the default serialization format from TBINARY to something else, specify it when creating a THttpService:

import com.linecorp.armeria.common.thrift.ThriftSerializationFormats;

ServerBuilder sb = Server.builder();
// Use TCOMPACT as the default serialization format.
sb.service("/hello", THttpService.of(new MyHelloService(),
                                     ThriftSerializationFormats.COMPACT));

You can also choose the list of allowed serialization formats:

ServerBuilder sb = Server.builder();
// Use TBINARY as the default serialization format.
// Allow TBINARY and TCOMPACT only.
sb.service("/hello", THttpService.of(new MyHelloService(),
                                     ThriftSerializationFormats.BINARY,
                                     ThriftSerializationFormats.COMPACT));

warning

TTEXT is not designed for efficiency and is recommended to be only used for debugging. It's best to serve from a separate path only accessible internally.

Service multiplexing

THttpService supports service multiplexing fully compatible with Apache Thrift TMultiplexedProcessor.

Map<String, Object> impls = new HashMap<>();
impls.put("foo", new MyFooService());
impls.put("bar", new MyBarService());
// Use MyHelloService for non-multiplexed requests.
impls.put("", new MyHelloService());

sb.service("/thrift", THttpService.of(impls));

See also

• Calling a Thrift service