or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async.mdcore.mdindex.mdmetadata.mdprotocols.mdschemes.mdservers.mdtransports.mdutilities.md
tile.json

tessl/maven-org-apache-thrift--libthrift

Apache Thrift Java Library - A lightweight, language-independent software stack for point-to-point RPC implementation providing clean abstractions and implementations for data transport, data serialization, and application level processing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.thrift/libthrift@0.22.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-thrift--libthrift@0.22.0

index.mddocs/

Apache Thrift Java Library

Apache Thrift Java Library (libthrift) is a comprehensive RPC framework implementation that enables cross-language communication through efficient data serialization and remote procedure calls. This library provides the core Java runtime components for Thrift, including protocol implementations (binary, compact, JSON), transport mechanisms (socket, HTTP, memory), server types (simple, threaded, non-blocking), and client-side connection management. It supports multiple serialization protocols with automatic code generation from Thrift IDL files, making it ideal for building distributed systems that need to communicate across different programming languages and platforms.

Package Information

  • Package Name: libthrift
  • Package Type: maven
  • Language: Java
  • Group ID: org.apache.thrift
  • Artifact ID: libthrift
  • Installation: Add to Maven: <dependency><groupId>org.apache.thrift</groupId><artifactId>libthrift</artifactId><version>0.22.0</version></dependency>
  • Gradle: implementation 'org.apache.thrift:libthrift:0.22.0'

Core Imports

import org.apache.thrift.TSerializer;
import org.apache.thrift.TDeserializer;
import org.apache.thrift.TException;
import org.apache.thrift.protocol.TBinaryProtocol;
import org.apache.thrift.transport.TSocket;
import org.apache.thrift.server.TSimpleServer;

Basic Usage

Simple Serialization/Deserialization

import org.apache.thrift.TSerializer;
import org.apache.thrift.TDeserializer;
import org.apache.thrift.TException;
import org.apache.thrift.protocol.TBinaryProtocol;

// Serialize a Thrift object to bytes
TSerializer serializer = new TSerializer(new TBinaryProtocol.Factory());
byte[] bytes = serializer.serialize(thriftObject);

// Deserialize bytes back to a Thrift object
TDeserializer deserializer = new TDeserializer(new TBinaryProtocol.Factory());
MyThriftObject obj = new MyThriftObject();
deserializer.deserialize(obj, bytes);

Simple Client/Server Setup

import org.apache.thrift.transport.TSocket;
import org.apache.thrift.transport.TServerSocket;
import org.apache.thrift.protocol.TBinaryProtocol;
import org.apache.thrift.server.TSimpleServer;

// Client setup
TSocket transport = new TSocket("localhost", 9090);
TBinaryProtocol protocol = new TBinaryProtocol(transport);
MyService.Client client = new MyService.Client(protocol);
transport.open();

// Server setup
TServerSocket serverTransport = new TServerSocket(9090);
MyService.Processor<MyServiceHandler> processor = new MyService.Processor<>(new MyServiceHandler());
TSimpleServer server = new TSimpleServer(new TSimpleServer.Args(serverTransport).processor(processor));
server.serve();

Architecture

Apache Thrift Java library is built around several key components:

  • Core Framework: Base interfaces (TBase, TProcessor, TSerializable) and utilities for object serialization/deserialization
  • Protocol Layer: Multiple protocol implementations (binary, compact, JSON) for data serialization with pluggable protocol factories
  • Transport Layer: Various transport mechanisms (socket, HTTP, memory, file) with layered transport support (framing, compression, SASL)
  • Server Framework: Multiple server implementations (simple, threaded, non-blocking, async) with configurable event handling
  • Async Support: Non-blocking client/server implementations with callback-based async method calls
  • Type System: Complete type support with metadata reflection and partial deserialization capabilities

Capabilities

Core Framework

Essential classes and interfaces for Thrift object handling, serialization, and processing.

// Main serialization utilities
public class TSerializer {
    public TSerializer() throws TTransportException;
    public TSerializer(TProtocolFactory protocolFactory) throws TTransportException;
    public byte[] serialize(TBase<?, ?> base) throws TException;
    public String toString(TBase<?, ?> base) throws TException;
}

public class TDeserializer {
    public TDeserializer() throws TTransportException;
    public TDeserializer(TProtocolFactory protocolFactory) throws TTransportException;
    public void deserialize(TBase base, byte[] bytes) throws TException;
    public void deserialize(TBase base, String data, String charset) throws TException;
}

// Base interfaces for generated code
public interface TBase<T extends TBase<T, F>, F extends TFieldIdEnum> extends Serializable, Cloneable, Comparable<T> {
    public F fieldForId(int fieldId);
    public boolean isSet(F field);
    public Object getFieldValue(F field);
    public void setFieldValue(F field, Object value);
    public T deepCopy();
    public void clear();
}

public interface TProcessor {
    public void process(TProtocol in, TProtocol out) throws TException;
}

Core Framework

Protocol Implementations

Data serialization protocols for different use cases and requirements.

// Protocol base class and factories
public abstract class TProtocol {
    public abstract void writeMessageBegin(TMessage message) throws TException;
    public abstract void writeMessageEnd() throws TException;
    public abstract void writeStructBegin(TStruct struct) throws TException;
    public abstract void writeStructEnd() throws TException;
    public abstract void writeFieldBegin(TField field) throws TException;
    public abstract void writeFieldEnd() throws TException;
    public abstract void writeFieldStop() throws TException;
    public abstract void writeBool(boolean b) throws TException;
    public abstract void writeByte(byte b) throws TException;
    public abstract void writeI16(short i16) throws TException;
    public abstract void writeI32(int i32) throws TException;
    public abstract void writeI64(long i64) throws TException;
    public abstract void writeDouble(double dub) throws TException;
    public abstract void writeString(String str) throws TException;
    public abstract void writeBinary(ByteBuffer bin) throws TException;
}

// Main protocol implementations
public class TBinaryProtocol extends TProtocol {
    public TBinaryProtocol(TTransport trans);
    public TBinaryProtocol(TTransport trans, boolean strictRead, boolean strictWrite);
    
    public static class Factory implements TProtocolFactory {
        public Factory();
        public Factory(boolean strictRead, boolean strictWrite);
    }
}

public class TCompactProtocol extends TProtocol {
    public TCompactProtocol(TTransport transport);
    
    public static class Factory implements TProtocolFactory {
        public Factory();
    }
}

public class TJSONProtocol extends TProtocol {
    public TJSONProtocol(TTransport trans);
    
    public static class Factory implements TProtocolFactory {
        public Factory();
    }
}

Protocol Implementations

Transport Mechanisms

Various transport implementations for different communication needs.

// Transport base classes
public abstract class TTransport implements Closeable {
    public abstract boolean isOpen();
    public abstract void open() throws TTransportException;
    public abstract void close();
    public abstract int read(byte[] buf, int off, int len) throws TTransportException;
    public abstract void write(byte[] buf, int off, int len) throws TTransportException;
    public abstract void flush() throws TTransportException;
}

// Main transport implementations
public class TSocket extends TEndpointTransport {
    public TSocket(String host, int port) throws TTransportException;
    public TSocket(String host, int port, int timeout) throws TTransportException;
    public void setTimeout(int timeout);
}

public class THttpClient extends TEndpointTransport {
    public THttpClient(String url) throws TTransportException;
    public THttpClient(URL url) throws TTransportException;
    public void setConnectTimeout(int timeout);
    public void setReadTimeout(int timeout);
}

public class TMemoryBuffer extends TTransport {
    public TMemoryBuffer(int size);
    public TMemoryBuffer(byte[] bytes);
    public byte[] getArray();
    public int length();
}

// Layered transports
public class TFramedTransport extends TLayeredTransport {
    public TFramedTransport(TTransport transport);
    public TFramedTransport(TTransport transport, int maxLength);
}

Transport Mechanisms

Server Implementations

Various server types for different performance and scalability requirements.

// Server base class
public abstract class TServer {
    public abstract void serve();
    public void stop();
    public boolean isServing();
    public void setServerEventHandler(TServerEventHandler eventHandler);
    
    public static abstract class AbstractServerArgs<T extends AbstractServerArgs<T>> {
        public T processor(TProcessor processor);
        public T serverTransport(TServerTransport serverTransport);
        public T protocolFactory(TProtocolFactory protocolFactory);
        public T transportFactory(TTransportFactory transportFactory);
    }
}

// Server implementations
public class TSimpleServer extends TServer {
    public TSimpleServer(AbstractServerArgs args);
    
    public static class Args extends AbstractServerArgs<Args> {
        public Args(TServerTransport transport);
    }
}

public class TThreadPoolServer extends TServer {
    public TThreadPoolServer(AbstractServerArgs args);
    
    public static class Args extends AbstractServerArgs<Args> {
        public Args(TServerTransport transport);
        public Args executorService(ExecutorService executorService);
        public Args minWorkerThreads(int n);
        public Args maxWorkerThreads(int n);
    }
}

public class TNonblockingServer extends AbstractNonblockingServer {
    public TNonblockingServer(AbstractNonblockingServerArgs args);
    
    public static class Args extends AbstractNonblockingServerArgs<Args> {
        public Args(TNonblockingServerTransport transport);
    }
}

Server Implementations

Asynchronous Operations

Non-blocking client and server implementations for high-performance applications.

// Async client base
public abstract class TAsyncClient {
    public TAsyncClient(TProtocolFactory protocolFactory, TAsyncClientManager manager, TNonblockingTransport transport);
    public TAsyncClient(TProtocolFactory protocolFactory, TAsyncClientManager manager, TNonblockingTransport transport, long timeout);
    
    public long getTimeout();
    public void setTimeout(long timeout);
    public boolean hasError();
    public Exception getError();
}

// Async client manager
public class TAsyncClientManager {
    public TAsyncClientManager();
    public TAsyncClientManager(int selectThreadCount, int selectorThreadPoolSize, long timeoutCheckInterval);
    
    public void call(TAsyncMethodCall method) throws TException;
    public void stop();
}

// Async method callback
public interface AsyncMethodCallback<T> {
    public void onComplete(T response);
    public void onError(Exception exception);
}

// Async processor
public interface TAsyncProcessor {
    public void process(AsyncProcessFunction<?, ?, ?> function, TProtocol iproto, TProtocol oproto, AsyncMethodCallback callback) throws TException;
}

Asynchronous Operations

Serialization Schemes

Pluggable serialization strategies that control how Thrift objects are encoded and decoded, with support for standard field-based and memory-efficient tuple-based schemes.

public interface IScheme<T extends TBase> {
    public void read(TProtocol iproto, T struct) throws TException;
    public void write(TProtocol oproto, T struct) throws TException;
}

public class StandardScheme<T extends TBase> implements IScheme<T> {
    // Standard field-by-field serialization with full metadata
}

public class TupleScheme<T extends TBase> implements IScheme<T> {
    // Memory-efficient tuple serialization without field metadata
}

Serialization Schemes

Metadata and Reflection

Runtime metadata support for Thrift objects, enabling reflection, introspection, and dynamic handling of structures with field type information and requirements.

public class FieldMetaData {
    public final String fieldName;
    public final byte requirementType;
    public final FieldValueMetaData valueMetaData;
    
    public static <T extends TBase<T, F>, F extends TFieldIdEnum> Map<F, FieldMetaData> getStructMetaDataMap(Class<T> sClass);
    public static <T extends TBase<T, F>, F extends TFieldIdEnum> void addStructMetaDataMap(Class<T> sClass, Map<F, FieldMetaData> map);
}

public class FieldValueMetaData {
    public final byte type;
    public final String typedefName;
    
    public boolean isTypedef();
    public boolean isBinary();
}

Metadata and Reflection

Utilities and Annotations

Utility classes and annotations for enhanced Thrift operations, including string processing, partial deserialization support, and field annotations.

public class StringUtils {
    public static String toString(Object obj);
    public static String toBinaryString(byte[] bytes);
    public static byte[] fastBinaryDecode(String str);
    public static String fastBinaryEncode(byte[] bytes);
}

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
public @interface Nullable {
    String value() default "";
}

Utilities and Annotations

Error Handling

Apache Thrift provides a hierarchy of exceptions for different error conditions:

// Base exception
public class TException extends Exception {
    public TException();
    public TException(String message);
    public TException(Throwable cause);
    public TException(String message, Throwable cause);
}

// Application-level exceptions
public class TApplicationException extends TException {
    public static final int UNKNOWN = 0;
    public static final int UNKNOWN_METHOD = 1;
    public static final int INVALID_MESSAGE_TYPE = 2;
    public static final int WRONG_METHOD_NAME = 3;
    public static final int BAD_SEQUENCE_ID = 4;
    public static final int MISSING_RESULT = 5;
    public static final int INTERNAL_ERROR = 6;
    public static final int PROTOCOL_ERROR = 7;
    
    public TApplicationException();
    public TApplicationException(int type);
    public TApplicationException(int type, String message);
    public int getType();
}

Configuration

public class TConfiguration {
    public static final int DEFAULT_MAX_MESSAGE_SIZE = 100 * 1024 * 1024;
    public static final int DEFAULT_MAX_FRAME_SIZE = 16384000;
    public static final int DEFAULT_RECURSION_DEPTH = 64;
    
    public TConfiguration();
    public TConfiguration(int maxMessageSize, int maxFrameSize, int recursionLimit);
    
    public int getMaxMessageSize();
    public void setMaxMessageSize(int maxMessageSize);
    public int getMaxFrameSize();
    public void setMaxFrameSize(int maxFrameSize);
    public int getRecursionLimit();
    public void setRecursionLimit(int recursionLimit);
    
    public static Builder custom();
}

Common Types

// Field requirement types
public final class TFieldRequirementType {
    public static final byte REQUIRED = 1;
    public static final byte OPTIONAL = 2;
    public static final byte DEFAULT = 3;
}

// Thrift data types
public final class TType {
    public static final byte STOP = 0;
    public static final byte VOID = 1;
    public static final byte BOOL = 2;
    public static final byte BYTE = 3;
    public static final byte I08 = 3;
    public static final byte DOUBLE = 4;
    public static final byte I16 = 6;
    public static final byte I32 = 8;
    public static final byte I64 = 10;
    public static final byte STRING = 11;
    public static final byte UTF7 = 11;
    public static final byte STRUCT = 12;
    public static final byte MAP = 13;
    public static final byte SET = 14;
    public static final byte LIST = 15;
    public static final byte UTF8 = 16;
    public static final byte UTF16 = 17;
    public static final byte UUID = 18;
}

// Message types
public final class TMessageType {
    public static final byte CALL = 1;
    public static final byte REPLY = 2;
    public static final byte EXCEPTION = 3;
    public static final byte ONEWAY = 4;
}