0
# Protocol Implementations
1

2
Data serialization protocols for different use cases and requirements. Protocols define how Thrift data structures are encoded and decoded for transmission over the wire or storage.
3

4
## Capabilities
5

6
### Protocol Base Classes
7

8
Core protocol interfaces and abstract classes that all protocol implementations extend.
9

10
```java { .api }
11
/**
12
 * Abstract base class for all protocol implementations
13
 */
14
public abstract class TProtocol {
15
    /** Create protocol with transport */
16
    public TProtocol(TTransport trans);
17
    
18
    /** Get the underlying transport */
19
    public TTransport getTransport();
20
    
21
    // Message-level operations
22
    /** Begin writing a message */
23
    public abstract void writeMessageBegin(TMessage message) throws TException;
24
    
25
    /** End writing a message */
26
    public abstract void writeMessageEnd() throws TException;
27
    
28
    /** Begin reading a message */
29
    public abstract TMessage readMessageBegin() throws TException;
30
    
31
    /** End reading a message */
32
    public abstract void readMessageEnd() throws TException;
33
    
34
    // Struct-level operations
35
    /** Begin writing a struct */
36
    public abstract void writeStructBegin(TStruct struct) throws TException;
37
    
38
    /** End writing a struct */
39
    public abstract void writeStructEnd() throws TException;
40
    
41
    /** Begin reading a struct */
42
    public abstract TStruct readStructBegin() throws TException;
43
    
44
    /** End reading a struct */
45
    public abstract void readStructEnd() throws TException;
46
    
47
    // Field-level operations
48
    /** Begin writing a field */
49
    public abstract void writeFieldBegin(TField field) throws TException;
50
    
51
    /** End writing a field */
52
    public abstract void writeFieldEnd() throws TException;
53
    
54
    /** Write field stop marker */
55
    public abstract void writeFieldStop() throws TException;
56
    
57
    /** Begin reading a field */
58
    public abstract TField readFieldBegin() throws TException;
59
    
60
    /** End reading a field */
61
    public abstract void readFieldEnd() throws TException;
62
    
63
    // Container operations - Maps
64
    /** Begin writing a map */
65
    public abstract void writeMapBegin(TMap map) throws TException;
66
    
67
    /** End writing a map */
68
    public abstract void writeMapEnd() throws TException;
69
    
70
    /** Begin reading a map */
71
    public abstract TMap readMapBegin() throws TException;
72
    
73
    /** End reading a map */
74
    public abstract void readMapEnd() throws TException;
75
    
76
    // Container operations - Lists
77
    /** Begin writing a list */
78
    public abstract void writeListBegin(TList list) throws TException;
79
    
80
    /** End writing a list */
81
    public abstract void writeListEnd() throws TException;
82
    
83
    /** Begin reading a list */
84
    public abstract TList readListBegin() throws TException;
85
    
86
    /** End reading a list */
87
    public abstract void readListEnd() throws TException;
88
    
89
    // Container operations - Sets
90
    /** Begin writing a set */
91
    public abstract void writeSetBegin(TSet set) throws TException;
92
    
93
    /** End writing a set */
94
    public abstract void writeSetEnd() throws TException;
95
    
96
    /** Begin reading a set */
97
    public abstract TSet readSetBegin() throws TException;
98
    
99
    /** End reading a set */
100
    public abstract void readSetEnd() throws TException;
101
    
102
    // Primitive type operations
103
    /** Write boolean value */
104
    public abstract void writeBool(boolean b) throws TException;
105
    
106
    /** Read boolean value */
107
    public abstract boolean readBool() throws TException;
108
    
109
    /** Write byte value */
110
    public abstract void writeByte(byte b) throws TException;
111
    
112
    /** Read byte value */
113
    public abstract byte readByte() throws TException;
114
    
115
    /** Write 16-bit integer */
116
    public abstract void writeI16(short i16) throws TException;
117
    
118
    /** Read 16-bit integer */
119
    public abstract short readI16() throws TException;
120
    
121
    /** Write 32-bit integer */
122
    public abstract void writeI32(int i32) throws TException;
123
    
124
    /** Read 32-bit integer */
125
    public abstract int readI32() throws TException;
126
    
127
    /** Write 64-bit integer */
128
    public abstract void writeI64(long i64) throws TException;
129
    
130
    /** Read 64-bit integer */
131
    public abstract long readI64() throws TException;
132
    
133
    /** Write double value */
134
    public abstract void writeDouble(double dub) throws TException;
135
    
136
    /** Read double value */
137
    public abstract double readDouble() throws TException;
138
    
139
    /** Write string value */
140
    public abstract void writeString(String str) throws TException;
141
    
142
    /** Read string value */
143
    public abstract String readString() throws TException;
144
    
145
    /** Write binary data */
146
    public abstract void writeBinary(ByteBuffer bin) throws TException;
147
    
148
    /** Read binary data */
149
    public abstract ByteBuffer readBinary() throws TException;
150
    
151
    // Utility methods
152
    /** Skip field of specified type */
153
    public void skip(byte fieldType) throws TException;
154
    
155
    /** Reset protocol state */
156
    public void reset();
157
    
158
    /** Get minimum serialized size for type */
159
    public int getMinSerializedSize(byte type) throws TException;
160
}
161

162
/**
163
 * Factory interface for creating protocol instances
164
 */
165
public interface TProtocolFactory {
166
    /** Create protocol instance for the given transport */
167
    public TProtocol getProtocol(TTransport trans);
168
}
169
```
170

171
### Binary Protocol
172

173
Efficient binary protocol implementation for high-performance scenarios.
174

175
```java { .api }
176
/**
177
 * Binary protocol implementation with optional strict mode
178
 */
179
public class TBinaryProtocol extends TProtocol {
180
    /** Version information for protocol compatibility */
181
    public static final long VERSION_MASK = 0xffff0000;
182
    public static final int VERSION_1 = 0x80010000;
183
    
184
    /** Create binary protocol with transport and default settings */
185
    public TBinaryProtocol(TTransport trans);
186
    
187
    /** Create binary protocol with strict read/write settings */
188
    public TBinaryProtocol(TTransport trans, boolean strictRead, boolean strictWrite);
189
    
190
    /** Create binary protocol with size limits and strict settings */
191
    public TBinaryProtocol(TTransport trans, long stringLengthLimit, long containerLengthLimit, 
192
                          boolean strictRead, boolean strictWrite);
193
    
194
    /** Factory for creating binary protocol instances */
195
    public static class Factory implements TProtocolFactory {
196
        /** Create factory with default settings */
197
        public Factory();
198
        
199
        /** Create factory with strict read/write settings */
200
        public Factory(boolean strictRead, boolean strictWrite);
201
        
202
        /** Create factory with size limits and strict settings */
203
        public Factory(long stringLengthLimit, long containerLengthLimit, 
204
                      boolean strictRead, boolean strictWrite);
205
        
206
        public TProtocol getProtocol(TTransport trans);
207
    }
208
}
209
```
210

211
**Usage Examples:**
212

213
```java
214
import org.apache.thrift.protocol.TBinaryProtocol;
215
import org.apache.thrift.transport.TSocket;
216

217
// Create binary protocol with default settings
218
TSocket transport = new TSocket("localhost", 9090);
219
TBinaryProtocol protocol = new TBinaryProtocol(transport);
220

221
// Create binary protocol with strict mode enabled
222
TBinaryProtocol strictProtocol = new TBinaryProtocol(transport, true, true);
223

224
// Use factory for creating protocols
225
TBinaryProtocol.Factory factory = new TBinaryProtocol.Factory();
226
TBinaryProtocol protocolFromFactory = (TBinaryProtocol) factory.getProtocol(transport);
227

228
// Factory with strict mode and size limits
229
TBinaryProtocol.Factory strictFactory = new TBinaryProtocol.Factory(1024 * 1024, 1024, true, true);
230
```
231

232
### Compact Protocol
233

234
Space-efficient protocol with variable-length encoding for reduced bandwidth usage.
235

236
```java { .api }
237
/**
238
 * Compact binary protocol with variable-length encoding
239
 */
240
public class TCompactProtocol extends TProtocol {
241
    /** Protocol identifier and version */
242
    public static final byte VERSION = 1;
243
    public static final byte VERSION_MASK = 0x1f;
244
    public static final byte TYPE_MASK = (byte) 0xE0;
245
    public static final int TYPE_SHIFT_AMOUNT = 5;
246
    
247
    /** Create compact protocol with transport */
248
    public TCompactProtocol(TTransport transport);
249
    
250
    /** Create compact protocol with size limits */
251
    public TCompactProtocol(TTransport transport, long stringLengthLimit, long containerLengthLimit);
252
    
253
    /** Factory for creating compact protocol instances */
254
    public static class Factory implements TProtocolFactory {
255
        /** Create factory with default settings */
256
        public Factory();
257
        
258
        /** Create factory with size limits */
259
        public Factory(long stringLengthLimit, long containerLengthLimit);
260
        
261
        public TProtocol getProtocol(TTransport trans);
262
    }
263
}
264
```
265

266
**Usage Examples:**
267

268
```java
269
import org.apache.thrift.protocol.TCompactProtocol;
270
import org.apache.thrift.transport.TSocket;
271

272
// Create compact protocol
273
TSocket transport = new TSocket("localhost", 9090);
274
TCompactProtocol protocol = new TCompactProtocol(transport);
275

276
// Use factory
277
TCompactProtocol.Factory factory = new TCompactProtocol.Factory();
278
TCompactProtocol compactProtocol = (TCompactProtocol) factory.getProtocol(transport);
279

280
// Factory with size limits
281
TCompactProtocol.Factory limitedFactory = new TCompactProtocol.Factory(1024 * 1024, 1024);
282
```
283

284
### JSON Protocol
285

286
Human-readable JSON protocol for debugging and web services.
287

288
```java { .api }
289
/**
290
 * JSON protocol implementation for human-readable output
291
 */
292
public class TJSONProtocol extends TProtocol {
293
    /** Create JSON protocol with transport */
294
    public TJSONProtocol(TTransport trans);
295
    
296
    /** Create JSON protocol with configuration */
297
    public TJSONProtocol(TTransport trans, TConfiguration config);
298
    
299
    /** Factory for creating JSON protocol instances */
300
    public static class Factory implements TProtocolFactory {
301
        /** Create factory with default settings */
302
        public Factory();
303
        
304
        public TProtocol getProtocol(TTransport trans);
305
    }
306
}
307

308
/**
309
 * Simple JSON protocol (write-only) for one-way serialization
310
 */
311
public class TSimpleJSONProtocol extends TProtocol {
312
    /** Create simple JSON protocol with transport */
313
    public TSimpleJSONProtocol(TTransport trans);
314
    
315
    /** Factory for creating simple JSON protocol instances */
316
    public static class Factory implements TProtocolFactory {
317
        /** Create factory */
318
        public Factory();
319
        
320
        public TProtocol getProtocol(TTransport trans);
321
    }
322
}
323
```
324

325
**Usage Examples:**
326

327
```java
328
import org.apache.thrift.protocol.TJSONProtocol;
329
import org.apache.thrift.protocol.TSimpleJSONProtocol;
330
import org.apache.thrift.transport.TMemoryBuffer;
331

332
// Create JSON protocol for bidirectional serialization
333
TMemoryBuffer buffer = new TMemoryBuffer(1024);
334
TJSONProtocol jsonProtocol = new TJSONProtocol(buffer);
335

336
// Create simple JSON protocol for write-only serialization
337
TSimpleJSONProtocol simpleJsonProtocol = new TSimpleJSONProtocol(buffer);
338

339
// Use factories
340
TJSONProtocol.Factory jsonFactory = new TJSONProtocol.Factory();
341
TSimpleJSONProtocol.Factory simpleFactory = new TSimpleJSONProtocol.Factory();
342
```
343

344
### Tuple Protocol
345

346
Memory-efficient protocol for use with tuple schemes.
347

348
```java { .api }
349
/**
350
 * Tuple protocol for efficient serialization with tuple schemes
351
 */
352
public class TTupleProtocol extends TProtocol {
353
    /** Create tuple protocol with transport */
354
    public TTupleProtocol(TTransport transport);
355
}
356
```
357

358
### Multiplexed Protocol
359

360
Protocol decorator that adds service name information for multiplexed services.
361

362
```java { .api }
363
/**
364
 * Protocol decorator for multiplexed services
365
 */
366
public class TMultiplexedProtocol extends TProtocolDecorator {
367
    /** Service name separator */
368
    public static final String SEPARATOR = ":";
369
    
370
    /** Create multiplexed protocol with base protocol and service name */
371
    public TMultiplexedProtocol(TProtocol protocol, String serviceName);
372
    
373
    /** Write message begin with service name prefix */
374
    public void writeMessageBegin(TMessage tMessage) throws TException;
375
}
376
```
377

378
**Usage Examples:**
379

380
```java
381
import org.apache.thrift.protocol.TMultiplexedProtocol;
382
import org.apache.thrift.protocol.TBinaryProtocol;
383
import org.apache.thrift.transport.TSocket;
384

385
// Create multiplexed protocol for specific service
386
TSocket transport = new TSocket("localhost", 9090);
387
TBinaryProtocol baseProtocol = new TBinaryProtocol(transport);
388
TMultiplexedProtocol multiplexedProtocol = new TMultiplexedProtocol(baseProtocol, "MyService");
389

390
// Use with generated client
391
MyService.Client client = new MyService.Client(multiplexedProtocol);
392
```
393

394
### Protocol Data Structures
395

396
Data structures used by protocols to represent Thrift elements.
397

398
```java { .api }
399
/**
400
 * Represents a Thrift message
401
 */
402
public class TMessage {
403
    /** Message name */
404
    public final String name;
405
    /** Message type (call, reply, exception, oneway) */
406
    public final byte type;
407
    /** Sequence ID for request/response correlation */
408
    public final int seqid;
409
    
410
    /** Create message */
411
    public TMessage(String name, byte type, int seqid);
412
    
413
    /** Create empty message */
414
    public TMessage();
415
    
416
    public String toString();
417
    public boolean equals(Object other);
418
    public int hashCode();
419
}
420

421
/**
422
 * Represents a Thrift struct
423
 */
424
public class TStruct {
425
    /** Struct name */
426
    public final String name;
427
    
428
    /** Create struct */
429
    public TStruct(String name);
430
    
431
    /** Create empty struct */
432
    public TStruct();
433
}
434

435
/**
436
 * Represents a Thrift field
437
 */
438
public class TField {
439
    /** Field name */
440
    public final String name;
441
    /** Field type */
442
    public final byte type;
443
    /** Field ID */
444
    public final short id;
445
    
446
    /** Create field */
447
    public TField(String name, byte type, short id);
448
    
449
    /** Create empty field */
450
    public TField();
451
    
452
    public String toString();
453
    public boolean equals(Object other);
454
    public int hashCode();
455
}
456

457
/**
458
 * Represents a Thrift map
459
 */
460
public class TMap {
461
    /** Key type */
462
    public final byte keyType;
463
    /** Value type */
464
    public final byte valueType;
465
    /** Map size */
466
    public final int size;
467
    
468
    /** Create map */
469
    public TMap(byte keyType, byte valueType, int size);
470
    
471
    /** Create empty map */
472
    public TMap();
473
    
474
    public String toString();
475
    public boolean equals(Object other);
476
    public int hashCode();
477
}
478

479
/**
480
 * Represents a Thrift list
481
 */
482
public class TList {
483
    /** Element type */
484
    public final byte elemType;
485
    /** List size */
486
    public final int size;
487
    
488
    /** Create list */
489
    public TList(byte elemType, int size);
490
    
491
    /** Create empty list */
492
    public TList();
493
    
494
    public String toString();
495
    public boolean equals(Object other);
496
    public int hashCode();
497
}
498

499
/**
500
 * Represents a Thrift set
501
 */
502
public class TSet {
503
    /** Element type */
504
    public final byte elemType;
505
    /** Set size */
506
    public final int size;
507
    
508
    /** Create set */
509
    public TSet(byte elemType, int size);
510
    
511
    /** Create empty set */
512
    public TSet();
513
    
514
    public String toString();
515
    public boolean equals(Object other);
516
    public int hashCode();
517
}
518
```
519

520
### Protocol Constants
521

522
Constants used across protocol implementations.
523

524
```java { .api }
525
/**
526
 * Thrift data type constants
527
 */
528
public final class TType {
529
    public static final byte STOP = 0;
530
    public static final byte VOID = 1;
531
    public static final byte BOOL = 2;
532
    public static final byte BYTE = 3;
533
    public static final byte I08 = 3;  // Same as BYTE
534
    public static final byte DOUBLE = 4;
535
    public static final byte I16 = 6;
536
    public static final byte I32 = 8;
537
    public static final byte I64 = 10;
538
    public static final byte STRING = 11;
539
    public static final byte UTF7 = 11;  // Same as STRING
540
    public static final byte STRUCT = 12;
541
    public static final byte MAP = 13;
542
    public static final byte SET = 14;
543
    public static final byte LIST = 15;
544
    public static final byte UTF8 = 16;
545
    public static final byte UTF16 = 17;
546
    public static final byte UUID = 18;
547
}
548

549
/**
550
 * Message type constants
551
 */
552
public final class TMessageType {
553
    public static final byte CALL = 1;     // Request message
554
    public static final byte REPLY = 2;    // Response message
555
    public static final byte EXCEPTION = 3; // Exception response
556
    public static final byte ONEWAY = 4;   // One-way call (no response expected)
557
}
558
```
559

560
### Protocol Exceptions
561

562
Specific exception types for protocol-related errors.
563

564
```java { .api }
565
/**
566
 * Exception for protocol-specific errors
567
 */
568
public class TProtocolException extends TException {
569
    public static final int UNKNOWN = 0;
570
    public static final int INVALID_DATA = 1;
571
    public static final int NEGATIVE_SIZE = 2;
572
    public static final int SIZE_LIMIT = 3;
573
    public static final int BAD_VERSION = 4;
574
    public static final int NOT_IMPLEMENTED = 5;
575
    public static final int DEPTH_LIMIT = 6;
576
    
577
    /** Create exception with unknown type */
578
    public TProtocolException();
579
    
580
    /** Create exception with specific type */
581
    public TProtocolException(int type);
582
    
583
    /** Create exception with type and message */
584
    public TProtocolException(int type, String message);
585
    
586
    /** Create exception with message */
587
    public TProtocolException(String message);
588
    
589
    /** Get the exception type */
590
    public int getType();
591
}
592
```
593

594
### Protocol Utilities
595

596
Utility classes for protocol operations.
597

598
```java { .api }
599
/**
600
 * Utility methods for protocol operations
601
 */
602
public class TProtocolUtil {
603
    /** Skip field of specified type in protocol */
604
    public static void skip(TProtocol prot, byte type) throws TException;
605
    
606
    /** Convert protocol data to string representation */
607
    public static String toString(TProtocol protocol, String indent) throws TException;
608
}
609

610
/**
611
 * Base class for protocol decorators
612
 */
613
public abstract class TProtocolDecorator extends TProtocol {
614
    /** The wrapped protocol */
615
    protected final TProtocol protocol;
616
    
617
    /** Create decorator wrapping another protocol */
618
    public TProtocolDecorator(TProtocol protocol);
619
    
620
    /** Get the wrapped protocol */
621
    public TProtocol getProtocol();
622
}
623
```