0
# Core Framework
1

2
Essential classes and interfaces for Thrift object handling, serialization, processing, and configuration. This module provides the fundamental building blocks for all Thrift operations.
3

4
## Capabilities
5

6
### Serialization and Deserialization
7

8
Core utilities for converting Thrift objects to and from byte arrays or strings.
9

10
```java { .api }
11
/**
12
 * Utility for serializing Thrift objects into byte arrays or strings
13
 */
14
public class TSerializer {
15
    /** Create serializer with default binary protocol */
16
    public TSerializer() throws TTransportException;
17
    
18
    /** Create serializer with specific protocol factory */
19
    public TSerializer(TProtocolFactory protocolFactory) throws TTransportException;
20
    
21
    /** Serialize a Thrift object to byte array */
22
    public byte[] serialize(TBase<?, ?> base) throws TException;
23
    
24
    /** Serialize a Thrift object to string representation */
25
    public String toString(TBase<?, ?> base) throws TException;
26
}
27

28
/**
29
 * Utility for deserializing Thrift objects from byte arrays or strings
30
 * with support for partial deserialization
31
 */
32
public class TDeserializer {
33
    /** Create deserializer with default binary protocol */
34
    public TDeserializer() throws TTransportException;
35
    
36
    /** Create deserializer with specific protocol factory */
37
    public TDeserializer(TProtocolFactory protocolFactory) throws TTransportException;
38
    
39
    /** Create deserializer for partial deserialization with field processor */
40
    public TDeserializer(Class<? extends TBase> thriftClass, Collection<String> fieldNames, 
41
                        ThriftFieldValueProcessor processor, TProtocolFactory protocolFactory) throws TTransportException;
42
    
43
    /** Deserialize byte array into existing Thrift object */
44
    public void deserialize(TBase base, byte[] bytes) throws TException;
45
    
46
    /** Deserialize byte array subset into existing Thrift object */
47
    public void deserialize(TBase base, byte[] bytes, int offset, int length) throws TException;
48
    
49
    /** Deserialize string with specified charset into existing Thrift object */
50
    public void deserialize(TBase base, String data, String charset) throws TException;
51
    
52
    /** Deserialize string from byte array using UTF-8 encoding */
53
    public void fromString(TBase base, String data) throws TException;
54
    
55
    // Partial deserialization methods using field path
56
    /** Partially deserialize object into existing Thrift struct using field path */
57
    public void partialDeserialize(TBase tb, byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
58
    
59
    /** Partially deserialize boolean field using field path */
60
    public Boolean partialDeserializeBool(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
61
    
62
    /** Partially deserialize byte field using field path */
63
    public Byte partialDeserializeByte(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
64
    
65
    /** Partially deserialize double field using field path */
66
    public Double partialDeserializeDouble(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
67
    
68
    /** Partially deserialize 16-bit integer field using field path */
69
    public Short partialDeserializeI16(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
70
    
71
    /** Partially deserialize 32-bit integer field using field path */
72
    public Integer partialDeserializeI32(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
73
    
74
    /** Partially deserialize 64-bit integer field using field path */
75
    public Long partialDeserializeI64(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
76
    
77
    /** Partially deserialize string field using field path */
78
    public String partialDeserializeString(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
79
    
80
    /** Partially deserialize binary field using field path */
81
    public ByteBuffer partialDeserializeByteArray(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
82
    
83
    /** Partially deserialize set field ID in union using field path */
84
    public Short partialDeserializeSetFieldIdInUnion(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum... fieldIdPathRest) throws TException;
85
    
86
    /** Partially deserialize complete object from bytes */
87
    public Object partialDeserializeObject(byte[] bytes) throws TException;
88
    
89
    /** Partially deserialize complete object from bytes with offset and length */
90
    public Object partialDeserializeObject(byte[] bytes, int offset, int length) throws TException;
91
    
92
    /** Get metadata for partial deserialization */
93
    public ThriftMetadata.ThriftStruct getMetadata();
94
}
95
```
96

97
**Usage Examples:**
98

99
```java
100
import org.apache.thrift.TSerializer;
101
import org.apache.thrift.TDeserializer;
102
import org.apache.thrift.protocol.TBinaryProtocol;
103
import org.apache.thrift.protocol.TJSONProtocol;
104

105
// Basic serialization with binary protocol
106
TSerializer serializer = new TSerializer();
107
byte[] data = serializer.serialize(myThriftObject);
108

109
// Serialization with JSON protocol
110
TSerializer jsonSerializer = new TSerializer(new TJSONProtocol.Factory());
111
String jsonData = jsonSerializer.toString(myThriftObject);
112

113
// Basic deserialization
114
TDeserializer deserializer = new TDeserializer();
115
MyThriftClass obj = new MyThriftClass();
116
deserializer.deserialize(obj, data);
117

118
// Partial deserialization - extract only specific field using field enums
119
TDeserializer partialDeserializer = new TDeserializer();
120
String name = partialDeserializer.partialDeserializeString(data, MyThriftClass._Fields.NAME);
121
Integer age = partialDeserializer.partialDeserializeI32(data, MyThriftClass._Fields.AGE);
122

123
// Deserialize from JSON string
124
TDeserializer jsonDeserializer = new TDeserializer();
125
MyThriftClass objFromJson = new MyThriftClass();
126
jsonDeserializer.fromString(objFromJson, jsonString);
127
```
128

129
### Base Interfaces
130

131
Core interfaces that all generated Thrift classes implement.
132

133
```java { .api }
134
/**
135
 * Generic base interface for all generated Thrift objects
136
 * @param <T> The concrete type of the implementing class
137
 * @param <F> The field enum type for this class
138
 */
139
public interface TBase<T extends TBase<T, F>, F extends TFieldIdEnum> extends Serializable, Cloneable, Comparable<T> {
140
    /** Get field enum for the given field ID */
141
    public F fieldForId(int fieldId);
142
    
143
    /** Check if the specified field is set (has a value) */
144
    public boolean isSet(F field);
145
    
146
    /** Get the value of the specified field */
147
    public Object getFieldValue(F field);
148
    
149
    /** Set the value of the specified field */
150
    public void setFieldValue(F field, Object value);
151
    
152
    /** Create a deep copy of this object */
153
    public T deepCopy();
154
    
155
    /** Clear all fields (set them to null/default values) */
156
    public void clear();
157
}
158

159
/**
160
 * Interface for serializable Thrift objects
161
 */
162
public interface TSerializable {
163
    /** Read object data from protocol */
164
    public void read(TProtocol iprot) throws TException;
165
    
166
    /** Write object data to protocol */
167
    public void write(TProtocol oprot) throws TException;
168
}
169

170
/**
171
 * Interface for Thrift enum types
172
 */
173
public interface TEnum {
174
    /** Get the integer value of this enum */
175
    public int getValue();
176
}
177

178
/**
179
 * Interface for generated struct field enums
180
 */
181
public interface TFieldIdEnum {
182
    /** Get the Thrift field ID */
183
    public short getThriftFieldId();
184
    
185
    /** Get the field name */
186
    public String getFieldName();
187
}
188
```
189

190
### Processing Framework
191

192
Interfaces and base classes for handling Thrift service requests.
193

194
```java { .api }
195
/**
196
 * Interface for processing Thrift requests
197
 */
198
public interface TProcessor {
199
    /** Process a request from input protocol and write response to output protocol */
200
    public void process(TProtocol in, TProtocol out) throws TException;
201
}
202

203
/**
204
 * Factory for creating processor instances
205
 */
206
public interface TProcessorFactory {
207
    /** Create a new processor instance for the given transport */
208
    public TProcessor getProcessor(TTransport trans);
209
}
210

211
/**
212
 * Base implementation for synchronous processors
213
 */
214
public class TBaseProcessor implements TProcessor {
215
    /** Process request using registered process functions */
216
    public void process(TProtocol in, TProtocol out) throws TException;
217
    
218
    /** Register a process function for a method name */
219
    protected void registerProcessor(String methodName, ProcessFunction<?, ?> fn);
220
}
221

222
/**
223
 * Interface for asynchronous processing
224
 */
225
public interface TAsyncProcessor {
226
    /** Process async request with callback */
227
    public void process(AsyncProcessFunction<?, ?, ?> function, TProtocol iproto, TProtocol oproto, AsyncMethodCallback callback) throws TException;
228
}
229

230
/**
231
 * Base implementation for asynchronous processors
232
 */
233
public class TBaseAsyncProcessor implements TAsyncProcessor {
234
    /** Process async request using registered async process functions */
235
    public void process(AsyncProcessFunction<?, ?, ?> function, TProtocol iproto, TProtocol oproto, AsyncMethodCallback callback) throws TException;
236
    
237
    /** Register an async process function for a method name */
238
    protected void registerProcessor(String methodName, AsyncProcessFunction<?, ?, ?> fn);
239
}
240
```
241

242
### Service Client Framework
243

244
Base classes for generated service clients.
245

246
```java { .api }
247
/**
248
 * Base class for generated service clients
249
 */
250
public class TServiceClient {
251
    /** Create client with single protocol for both input and output */
252
    public TServiceClient(TProtocol prot);
253
    
254
    /** Create client with separate input and output protocols */
255
    public TServiceClient(TProtocol iprot, TProtocol oprot);
256
    
257
    /** Get the input protocol */
258
    protected TProtocol getInputProtocol();
259
    
260
    /** Get the output protocol */
261
    protected TProtocol getOutputProtocol();
262
}
263

264
/**
265
 * Factory for creating service client instances
266
 * @param <T> The service client type
267
 */
268
public class TServiceClientFactory<T extends TServiceClient> {
269
    /** Create client with single protocol */
270
    public T getClient(TProtocol prot);
271
    
272
    /** Create client with separate input/output protocols */
273
    public T getClient(TProtocol iprot, TProtocol oprot);
274
}
275
```
276

277
### Configuration Management
278

279
Configuration settings and options for Thrift operations.
280

281
```java { .api }
282
/**
283
 * Configuration settings for Thrift operations with size and recursion limits
284
 */
285
public class TConfiguration {
286
    /** Default maximum message size (100MB) */
287
    public static final int DEFAULT_MAX_MESSAGE_SIZE = 100 * 1024 * 1024;
288
    
289
    /** Default maximum frame size (~16MB) */
290
    public static final int DEFAULT_MAX_FRAME_SIZE = 16384000;
291
    
292
    /** Default recursion depth limit */
293
    public static final int DEFAULT_RECURSION_DEPTH = 64;
294
    
295
    /** Create configuration with default values */
296
    public TConfiguration();
297
    
298
    /** Create configuration with specified limits */
299
    public TConfiguration(int maxMessageSize, int maxFrameSize, int recursionLimit);
300
    
301
    /** Default configuration instance */
302
    public static final TConfiguration DEFAULT = new Builder().build();
303
    
304
    /** Get maximum message size */
305
    public int getMaxMessageSize();
306
    
307
    /** Get maximum frame size */
308
    public int getMaxFrameSize();
309
    
310
    /** Get recursion limit */
311
    public int getRecursionLimit();
312
    
313
    /** Create a builder for custom configuration */
314
    public static Builder custom();
315
    
316
    public static class Builder {
317
        /** Set maximum message size */
318
        public Builder setMaxMessageSize(int maxMessageSize);
319
        
320
        /** Set maximum frame size */
321
        public Builder setMaxFrameSize(int maxFrameSize);
322
        
323
        /** Set recursion limit */
324
        public Builder setRecursionLimit(int recursionLimit);
325
        
326
        /** Build the configuration */
327
        public TConfiguration build();
328
    }
329
}
330
```
331

332
### Multiplexed Service Support
333

334
Support for running multiple services on a single transport.
335

336
```java { .api }
337
/**
338
 * Processor that supports multiplexed services
339
 */
340
public class TMultiplexedProcessor implements TProcessor {
341
    /** Create multiplexed processor */
342
    public TMultiplexedProcessor();
343
    
344
    /** Register a processor for a service name */
345
    public void registerProcessor(String serviceName, TProcessor processor);
346
    
347
    /** Process request, routing to appropriate service processor */
348
    public void process(TProtocol in, TProtocol out) throws TException;
349
}
350
```
351

352
### Union Support
353

354
Base class for Thrift union types.
355

356
```java { .api }
357
/**
358
 * Abstract base class for generated union types
359
 * @param <T> The concrete type of the implementing union class
360
 * @param <F> The field enum type for this union
361
 */
362
public abstract class TUnion<T extends TUnion<T, F>, F extends TFieldIdEnum> implements TBase<T, F> {
363
    /** Default constructor */
364
    protected TUnion();
365
    
366
    /** Constructor with initial field and value */
367
    protected TUnion(F setField, Object value);
368
    
369
    /** Copy constructor */
370
    protected TUnion(TUnion<T, F> other);
371
    
372
    /** Check if any field is set */
373
    public boolean isSet();
374
    
375
    /** Get the currently set field */
376
    public F getSetField();
377
    
378
    /** Get the value of the currently set field */
379
    public Object getFieldValue();
380
    
381
    /** Set a field value (clears other fields) */
382
    public void setFieldValue(F field, Object value);
383
    
384
    /** Get the value of the specified field */
385
    public Object getFieldValue(F field);
386
    
387
    /** Clear all fields */
388
    public void clear();
389
    
390
    /** Create a deep copy */
391
    public T deepCopy();
392
}
393
```
394

395
### Exception Handling
396

397
Core exception types for Thrift operations.
398

399
```java { .api }
400
/**
401
 * Base exception class for all Thrift-related errors
402
 */
403
public class TException extends Exception {
404
    /** Create exception with no message */
405
    public TException();
406
    
407
    /** Create exception with message */
408
    public TException(String message);
409
    
410
    /** Create exception wrapping another throwable */
411
    public TException(Throwable cause);
412
    
413
    /** Create exception with message and cause */
414
    public TException(String message, Throwable cause);
415
}
416

417
/**
418
 * Application-level exception with specific error types
419
 */
420
public class TApplicationException extends TException {
421
    /** Unknown error */
422
    public static final int UNKNOWN = 0;
423
    /** Unknown method name */
424
    public static final int UNKNOWN_METHOD = 1;
425
    /** Invalid message type */
426
    public static final int INVALID_MESSAGE_TYPE = 2;
427
    /** Wrong method name in response */
428
    public static final int WRONG_METHOD_NAME = 3;
429
    /** Bad sequence ID in response */
430
    public static final int BAD_SEQUENCE_ID = 4;
431
    /** Missing result in response */
432
    public static final int MISSING_RESULT = 5;
433
    /** Internal server error */
434
    public static final int INTERNAL_ERROR = 6;
435
    /** Protocol error */
436
    public static final int PROTOCOL_ERROR = 7;
437
    /** Invalid data transform */
438
    public static final int INVALID_TRANSFORM = 8;
439
    /** Invalid protocol */
440
    public static final int INVALID_PROTOCOL = 9;
441
    /** Unsupported client type */
442
    public static final int UNSUPPORTED_CLIENT_TYPE = 10;
443
    
444
    /** Create exception with unknown type */
445
    public TApplicationException();
446
    
447
    /** Create exception with specific type */
448
    public TApplicationException(int type);
449
    
450
    /** Create exception with type and message */
451
    public TApplicationException(int type, String message);
452
    
453
    /** Create exception with message */
454
    public TApplicationException(String message);
455
    
456
    /** Get the exception type */
457
    public int getType();
458
    
459
    /** Read exception from protocol */
460
    public static TApplicationException readFrom(TProtocol iprot) throws TException;
461
    
462
    /** Write exception to protocol */
463
    public void write(TProtocol oprot) throws TException;
464
}
465
```
466

467
### Utility Classes
468

469
Helper classes for common Thrift operations.
470

471
```java { .api }
472
/**
473
 * Encoding and decoding utilities
474
 */
475
public final class EncodingUtils {
476
    /** Set bit in integer value */
477
    public static int setBit(int n, int pos, boolean value);
478
    
479
    /** Clear bit in integer value */
480
    public static int clearBit(int n, int pos);
481
    
482
    /** Test if bit is set in integer value */
483
    public static boolean testBit(int n, int pos);
484
    
485
    /** Encode integer as big-endian bytes */
486
    public static void encodeBigEndian(int val, byte[] buf, int offset);
487
    
488
    /** Decode big-endian bytes as integer */
489
    public static int decodeBigEndian(byte[] buf, int offset);
490
}
491

492
/**
493
 * Helper methods for TBase objects
494
 */
495
public final class TBaseHelper {
496
    /** Compare two objects (null-safe) */
497
    public static int compareTo(Object a, Object b);
498
    
499
    /** Convert object to string representation */
500
    public static String toString(Object o, StringBuilder sb);
501
    
502
    /** Copy binary data */
503
    public static ByteBuffer copyBinary(ByteBuffer orig);
504
    
505
    /** Compare binary data */
506
    public static int compareBinary(ByteBuffer a, ByteBuffer b);
507
    
508
    /** Deep copy a TBase object */
509
    public static <T extends TBase<T, F>, F extends TFieldIdEnum> T deepCopy(T orig);
510
}
511

512
/**
513
 * Helper methods for TEnum objects
514
 */
515
public final class TEnumHelper {
516
    /** Find enum value by integer value */
517
    public static <T extends TEnum> T findByValue(Class<T> enumClass, int value);
518
    
519
    /** Read enum value using standard scheme */
520
    public static <T extends TEnum> T standardSchemeReadValue(TProtocol iprot, Class<T> enumClass) throws TException;
521
    
522
    /** Write enum value using standard scheme */
523
    public static void standardSchemeWriteValue(TProtocol oprot, TEnum enumValue) throws TException;
524
}
525

526
/**
527
 * Optional value container
528
 */
529
public class Option<T> {
530
    /** Create empty option */
531
    public static <T> Option<T> fromNullable(T value);
532
    
533
    /** Check if value is present */
534
    public boolean has();
535
    
536
    /** Get the value (throws if not present) */
537
    public T get();
538
    
539
    /** Get the value or return alternative */
540
    public T or(T alternative);
541
}
542
```
543

544
### Constants
545

546
```java { .api }
547
/**
548
 * Field requirement type constants
549
 */
550
public final class TFieldRequirementType {
551
    public static final byte REQUIRED = 1;
552
    public static final byte OPTIONAL = 2;
553
    public static final byte DEFAULT = 3;
554
}
555
```