0
# I/O and Wire Format
1

2
Low-level binary I/O operations for reading and writing protocol buffer wire format data, supporting all protocol buffer data types with high-performance streaming capabilities.
3

4
## Capabilities
5

6
### CodedInputStream
7

8
High-performance binary input stream for reading protocol buffer wire format data with support for all protocol buffer data types and streaming operations.
9

10
```java { .api }
11
/**
12
 * Reads protocol buffer wire format data
13
 */
14
public abstract class CodedInputStream {
15
    // Static factory methods
16
    /** Creates from InputStream */
17
    public static CodedInputStream newInstance(InputStream input);
18
    
19
    /** Creates from InputStream with buffer size */
20
    public static CodedInputStream newInstance(InputStream input, int bufferSize);
21
    
22
    /** Creates from ByteBuffer iterable */
23
    public static CodedInputStream newInstance(Iterable<ByteBuffer> input);
24
    
25
    /** Creates from byte array */
26
    public static CodedInputStream newInstance(byte[] buf);
27
    
28
    /** Creates from byte array slice */
29
    public static CodedInputStream newInstance(byte[] buf, int off, int len);
30
    
31
    /** Creates from ByteBuffer */
32
    public static CodedInputStream newInstance(ByteBuffer buf);
33
    
34
    // Tag and field operations
35
    /** Reads and returns tag (field number and wire type) */
36
    public abstract int readTag() throws IOException;
37
    
38
    /** Skips field with given tag */
39
    public abstract boolean skipField(int tag) throws IOException;
40
    
41
    /** Skips field with given tag and extension registry */
42
    public abstract boolean skipField(int tag, CodedOutputStream output) throws IOException;
43
    
44
    // Integer reading methods
45
    /** Reads int32 field */
46
    public abstract int readInt32() throws IOException;
47
    
48
    /** Reads int64 field */
49
    public abstract long readInt64() throws IOException;
50
    
51
    /** Reads uint32 field */
52
    public abstract int readUInt32() throws IOException;
53
    
54
    /** Reads uint64 field */
55
    public abstract long readUInt64() throws IOException;
56
    
57
    /** Reads sint32 field (ZigZag encoded) */
58
    public abstract int readSInt32() throws IOException;
59
    
60
    /** Reads sint64 field (ZigZag encoded) */
61
    public abstract long readSInt64() throws IOException;
62
    
63
    /** Reads fixed32 field */
64
    public abstract int readFixed32() throws IOException;
65
    
66
    /** Reads fixed64 field */
67
    public abstract long readFixed64() throws IOException;
68
    
69
    /** Reads sfixed32 field */
70
    public abstract int readSFixed32() throws IOException;
71
    
72
    /** Reads sfixed64 field */
73
    public abstract long readSFixed64() throws IOException;
74
    
75
    // Floating point reading methods
76
    /** Reads float field */
77
    public abstract float readFloat() throws IOException;
78
    
79
    /** Reads double field */
80
    public abstract double readDouble() throws IOException;
81
    
82
    // Boolean reading
83
    /** Reads bool field */
84
    public abstract boolean readBool() throws IOException;
85
    
86
    // String and bytes reading
87
    /** Reads string field */
88
    public abstract String readString() throws IOException;
89
    
90
    /** Reads UTF-8 string field with validation */
91
    public abstract String readStringRequireUtf8() throws IOException;
92
    
93
    /** Reads bytes field as ByteString */
94
    public abstract ByteString readBytes() throws IOException;
95
    
96
    /** Reads bytes field as byte array */
97
    public abstract byte[] readByteArray() throws IOException;
98
    
99
    /** Reads bytes field as ByteBuffer */
100
    public abstract ByteBuffer readByteBuffer() throws IOException;
101
    
102
    // Advanced reading operations
103
    /** Reads enum field */
104
    public abstract int readEnum() throws IOException;
105
    
106
    /** Reads raw varint32 */
107
    public abstract int readRawVarint32() throws IOException;
108
    
109
    /** Reads raw varint64 */
110
    public abstract long readRawVarint64() throws IOException;
111
    
112
    /** Reads raw little-endian 32-bit integer */
113
    public abstract int readRawLittleEndian32() throws IOException;
114
    
115
    /** Reads raw little-endian 64-bit integer */
116
    public abstract long readRawLittleEndian64() throws IOException;
117
    
118
    // Stream control methods
119
    /** Sets recursion limit for nested messages */
120
    public void setRecursionLimit(int limit);
121
    
122
    /** Sets size limit for individual messages */
123
    public void setSizeLimit(int limit);
124
    
125
    /** Resets size counter */
126
    public void resetSizeCounter();
127
    
128
    /** Gets bytes read since last reset */
129
    public int getBytesUntilLimit();
130
    
131
    /** Checks if at end of stream */
132
    public abstract boolean isAtEnd() throws IOException;
133
    
134
    /** Gets current position in stream */
135
    public abstract int getTotalBytesRead();
136
    
137
    /** Pushes limit for length-delimited fields */
138
    public abstract int pushLimit(int byteLimit) throws InvalidProtocolBufferException;
139
    
140
    /** Pops limit after reading length-delimited field */
141
    public abstract void popLimit(int oldLimit);
142
    
143
    // Message reading
144
    /** Reads embedded message */
145
    public abstract void readMessage(MessageLite.Builder messageBuilder, 
146
                                   ExtensionRegistryLite extensionRegistry) throws IOException;
147
    
148
    /** Reads group (deprecated wire type) */
149
    public abstract void readGroup(int fieldNumber, MessageLite.Builder messageBuilder,
150
                                 ExtensionRegistryLite extensionRegistry) throws IOException;
151
}
152
```
153

154
### CodedOutputStream
155

156
High-performance binary output stream for writing protocol buffer wire format data with support for all data types and efficient encoding.
157

158
```java { .api }
159
/**
160
 * Writes protocol buffer wire format data
161
 */
162
public abstract class CodedOutputStream {
163
    /** Default buffer size constant */
164
    public static final int DEFAULT_BUFFER_SIZE = 4096;
165
    
166
    // Static factory methods
167
    /** Creates from OutputStream */
168
    public static CodedOutputStream newInstance(OutputStream output);
169
    
170
    /** Creates from OutputStream with buffer size */
171
    public static CodedOutputStream newInstance(OutputStream output, int bufferSize);
172
    
173
    /** Creates from byte array */
174
    public static CodedOutputStream newInstance(byte[] flatArray);
175
    
176
    /** Creates from byte array slice */
177
    public static CodedOutputStream newInstance(byte[] flatArray, int offset, int length);
178
    
179
    /** Creates from ByteBuffer */
180
    public static CodedOutputStream newInstance(ByteBuffer buffer);
181
    
182
    // Tag and field writing
183
    /** Writes tag (field number and wire type) */
184
    public abstract void writeTag(int fieldNumber, int wireType) throws IOException;
185
    
186
    /** Writes raw varint32 */
187
    public abstract void writeRawVarint32(int value) throws IOException;
188
    
189
    /** Writes raw varint64 */
190
    public abstract void writeRawVarint64(long value) throws IOException;
191
    
192
    // Integer writing methods  
193
    /** Writes int32 field */
194
    public abstract void writeInt32(int fieldNumber, int value) throws IOException;
195
    
196
    /** Writes int64 field */
197
    public abstract void writeInt64(int fieldNumber, long value) throws IOException;
198
    
199
    /** Writes uint32 field */
200
    public abstract void writeUInt32(int fieldNumber, int value) throws IOException;
201
    
202
    /** Writes uint64 field */
203
    public abstract void writeUInt64(int fieldNumber, long value) throws IOException;
204
    
205
    /** Writes sint32 field (ZigZag encoded) */
206
    public void writeSInt32(int fieldNumber, int value) throws IOException;
207
    
208
    /** Writes sint64 field (ZigZag encoded) */
209
    public void writeSInt64(int fieldNumber, long value) throws IOException;
210
    
211
    /** Writes fixed32 field */
212
    public abstract void writeFixed32(int fieldNumber, int value) throws IOException;
213
    
214
    /** Writes fixed64 field */
215
    public abstract void writeFixed64(int fieldNumber, long value) throws IOException;
216
    
217
    /** Writes sfixed32 field */
218
    public void writeSFixed32(int fieldNumber, int value) throws IOException;
219
    
220
    /** Writes sfixed64 field */
221
    public void writeSFixed64(int fieldNumber, long value) throws IOException;
222
    
223
    // Floating point writing methods
224
    /** Writes float field */
225
    public void writeFloat(int fieldNumber, float value) throws IOException;
226
    
227
    /** Writes double field */
228
    public void writeDouble(int fieldNumber, double value) throws IOException;
229
    
230
    // Boolean writing
231
    /** Writes bool field */
232
    public abstract void writeBool(int fieldNumber, boolean value) throws IOException;
233
    
234
    // Enum writing
235
    /** Writes enum field */
236
    public void writeEnum(int fieldNumber, int value) throws IOException;
237
    
238
    // String and bytes writing
239
    /** Writes string field */
240
    public abstract void writeString(int fieldNumber, String value) throws IOException;
241
    
242
    /** Writes bytes field from ByteString */
243
    public abstract void writeBytes(int fieldNumber, ByteString value) throws IOException;
244
    
245
    /** Writes bytes field from byte array */
246
    public abstract void writeByteArray(int fieldNumber, byte[] value) throws IOException;
247
    
248
    /** Writes bytes field from byte array slice */
249
    public abstract void writeByteArray(int fieldNumber, byte[] value, int offset, int length) throws IOException;
250
    
251
    /** Writes bytes field from ByteBuffer */
252
    public abstract void writeByteBuffer(int fieldNumber, ByteBuffer value) throws IOException;
253
    
254
    // Message writing
255
    /** Writes embedded message */
256
    public abstract void writeMessage(int fieldNumber, MessageLite value) throws IOException;
257
    
258
    /** Writes group (deprecated wire type) */
259
    public abstract void writeGroup(int fieldNumber, MessageLite value) throws IOException;
260
    
261
    // Raw writing methods
262
    /** Writes raw bytes */
263
    public abstract void writeRawBytes(ByteString value) throws IOException;
264
    
265
    /** Writes raw byte array */
266
    public abstract void writeRawBytes(byte[] value) throws IOException;
267
    
268
    /** Writes raw byte array slice */
269
    public abstract void writeRawBytes(byte[] value, int offset, int length) throws IOException;
270
    
271
    /** Writes raw ByteBuffer */
272
    public abstract void writeRawBytes(ByteBuffer value) throws IOException;
273
    
274
    /** Writes raw little-endian 32-bit integer */
275
    public abstract void writeRawLittleEndian32(int value) throws IOException;
276
    
277
    /** Writes raw little-endian 64-bit integer */
278
    public abstract void writeRawLittleEndian64(long value) throws IOException;
279
    
280
    // Stream control methods
281
    /** Enables deterministic serialization */
282
    public void useDeterministicSerialization();
283
    
284
    /** Flushes output */
285
    public abstract void flush() throws IOException;
286
    
287
    /** Returns remaining space in buffer */
288
    public abstract int spaceLeft();
289
    
290
    /** Verifies no space left (for fixed-size outputs) */
291
    public void checkNoSpaceLeft();
292
    
293
    /** Gets total bytes written */
294
    public abstract int getTotalBytesWritten();
295
    
296
    // No-tag writing methods (for packed repeated fields)
297
    /** Writes int32 without tag */
298
    public abstract void writeInt32NoTag(int value) throws IOException;
299
    
300
    /** Writes uint32 without tag */
301
    public abstract void writeUInt32NoTag(int value) throws IOException;
302
    
303
    /** Writes int64 without tag */
304
    public abstract void writeInt64NoTag(long value) throws IOException;
305
    
306
    /** Writes uint64 without tag */
307
    public abstract void writeUInt64NoTag(long value) throws IOException;
308
    
309
    /** Writes sint32 without tag */
310
    public void writeSInt32NoTag(int value) throws IOException;
311
    
312
    /** Writes sint64 without tag */
313
    public void writeSInt64NoTag(long value) throws IOException;
314
    
315
    /** Writes fixed32 without tag */
316
    public abstract void writeFixed32NoTag(int value) throws IOException;
317
    
318
    /** Writes fixed64 without tag */
319
    public abstract void writeFixed64NoTag(long value) throws IOException;
320
    
321
    /** Writes sfixed32 without tag */
322
    public void writeSFixed32NoTag(int value) throws IOException;
323
    
324
    /** Writes sfixed64 without tag */
325
    public void writeSFixed64NoTag(long value) throws IOException;
326
    
327
    /** Writes float without tag */
328
    public void writeFloatNoTag(float value) throws IOException;
329
    
330
    /** Writes double without tag */
331
    public void writeDoubleNoTag(double value) throws IOException;
332
    
333
    /** Writes bool without tag */
334
    public abstract void writeBoolNoTag(boolean value) throws IOException;
335
    
336
    /** Writes enum without tag */
337
    public void writeEnumNoTag(int value) throws IOException;
338
    
339
    /** Writes string without tag */
340
    public abstract void writeStringNoTag(String value) throws IOException;
341
    
342
    /** Writes bytes without tag */
343
    public abstract void writeBytesNoTag(ByteString value) throws IOException;
344
}
345
```
346

347
### Size Computation Methods
348

349
Static methods for computing the serialized size of protocol buffer fields without actually serializing them.
350

351
```java { .api }
352
/**
353
 * Static methods for computing field sizes in CodedOutputStream
354
 */
355
public abstract class CodedOutputStream {
356
    // Tag size computation
357
    /** Computes tag size */
358
    public static int computeTagSize(int fieldNumber);
359
    
360
    // Integer field size computation
361
    /** Computes int32 field size */
362
    public static int computeInt32Size(int fieldNumber, int value);
363
    
364
    /** Computes int64 field size */
365
    public static int computeInt64Size(int fieldNumber, long value);
366
    
367
    /** Computes uint32 field size */
368
    public static int computeUInt32Size(int fieldNumber, int value);
369
    
370
    /** Computes uint64 field size */
371
    public static int computeUInt64Size(int fieldNumber, long value);
372
    
373
    /** Computes sint32 field size */
374
    public static int computeSInt32Size(int fieldNumber, int value);
375
    
376
    /** Computes sint64 field size */
377
    public static int computeSInt64Size(int fieldNumber, long value);
378
    
379
    /** Computes fixed32 field size */
380
    public static int computeFixed32Size(int fieldNumber, int value);
381
    
382
    /** Computes fixed64 field size */
383
    public static int computeFixed64Size(int fieldNumber, long value);
384
    
385
    /** Computes sfixed32 field size */
386
    public static int computeSFixed32Size(int fieldNumber, int value);
387
    
388
    /** Computes sfixed64 field size */
389
    public static int computeSFixed64Size(int fieldNumber, long value);
390
    
391
    // Floating point field size computation
392
    /** Computes float field size */
393
    public static int computeFloatSize(int fieldNumber, float value);
394
    
395
    /** Computes double field size */
396
    public static int computeDoubleSize(int fieldNumber, double value);
397
    
398
    // Boolean field size computation
399
    /** Computes bool field size */
400
    public static int computeBoolSize(int fieldNumber, boolean value);
401
    
402
    // Enum field size computation
403
    /** Computes enum field size */
404
    public static int computeEnumSize(int fieldNumber, int value);
405
    
406
    // String and bytes field size computation
407
    /** Computes string field size */
408
    public static int computeStringSize(int fieldNumber, String value);
409
    
410
    /** Computes bytes field size */
411
    public static int computeBytesSize(int fieldNumber, ByteString value);
412
    
413
    /** Computes byte array field size */
414
    public static int computeByteArraySize(int fieldNumber, byte[] value);
415
    
416
    /** Computes ByteBuffer field size */
417
    public static int computeByteBufferSize(int fieldNumber, ByteBuffer value);
418
    
419
    // Message field size computation
420
    /** Computes message field size */
421
    public static int computeMessageSize(int fieldNumber, MessageLite value);
422
    
423
    /** Computes group field size */
424
    public static int computeGroupSize(int fieldNumber, MessageLite value);
425
    
426
    // Raw size computation methods
427
    /** Computes raw varint32 size */
428
    public static int computeRawVarint32Size(int value);
429
    
430
    /** Computes raw varint64 size */
431
    public static int computeRawVarint64Size(long value);
432
    
433
    /** Computes raw string size (UTF-8 encoded) */
434
    public static int computeRawStringSize(String str);
435
    
436
    // No-tag size computation (for packed repeated fields)
437
    /** Computes int32 size without tag */
438
    public static int computeInt32SizeNoTag(int value);
439
    
440
    /** Computes uint32 size without tag */
441
    public static int computeUInt32SizeNoTag(int value);
442
    
443
    /** Computes int64 size without tag */
444
    public static int computeInt64SizeNoTag(long value);
445
    
446
    /** Computes uint64 size without tag */
447
    public static int computeUInt64SizeNoTag(long value);
448
    
449
    /** Computes sint32 size without tag */
450
    public static int computeSInt32SizeNoTag(int value);
451
    
452
    /** Computes sint64 size without tag */
453
    public static int computeSInt64SizeNoTag(long value);
454
}
455
```
456

457
### Encoding Utilities
458

459
Static utility methods for ZigZag encoding and other wire format operations.
460

461
```java { .api }
462
/**
463
 * Encoding utility methods in CodedOutputStream
464
 */
465
public abstract class CodedOutputStream {
466
    /** Encodes signed 32-bit integer using ZigZag encoding */
467
    public static int encodeZigZag32(int n);
468
    
469
    /** Encodes signed 64-bit integer using ZigZag encoding */
470
    public static long encodeZigZag64(long n);
471
}
472

473
/**
474
 * Decoding utility methods in CodedInputStream  
475
 */
476
public abstract class CodedInputStream {
477
    /** Decodes ZigZag-encoded 32-bit integer */
478
    public static int decodeZigZag32(int n);
479
    
480
    /** Decodes ZigZag-encoded 64-bit integer */
481
    public static long decodeZigZag64(long n);
482
}
483
```
484

485
### Wire Format Constants
486

487
Wire type constants and utilities for working with protocol buffer wire format.
488

489
```java { .api }
490
/**
491
 * Constants and utilities for protocol buffer wire format
492
 */
493
public final class WireFormat {
494
    // Wire type constants
495
    /** Varint wire type (int32, int64, uint32, uint64, sint32, sint64, bool, enum) */
496
    public static final int WIRETYPE_VARINT = 0;
497
    
498
    /** Fixed64 wire type (fixed64, sfixed64, double) */
499
    public static final int WIRETYPE_FIXED64 = 1;
500
    
501
    /** Length-delimited wire type (string, bytes, embedded messages, packed repeated fields) */
502
    public static final int WIRETYPE_LENGTH_DELIMITED = 2;
503
    
504
    /** Start group wire type (deprecated) */
505
    public static final int WIRETYPE_START_GROUP = 3;
506
    
507
    /** End group wire type (deprecated) */
508
    public static final int WIRETYPE_END_GROUP = 4;
509
    
510
    /** Fixed32 wire type (fixed32, sfixed32, float) */
511
    public static final int WIRETYPE_FIXED32 = 5;
512
    
513
    // Utility methods
514
    /** Extract wire type from tag */
515
    public static int getTagWireType(int tag);
516
    
517
    /** Extract field number from tag */
518
    public static int getTagFieldNumber(int tag);
519
    
520
    /** Create tag from field number and wire type */
521
    public static int makeTag(int fieldNumber, int wireType);
522
    
523
    // Enums for type information
524
    public enum JavaType {
525
        INT, LONG, FLOAT, DOUBLE, BOOLEAN, STRING, BYTE_STRING, ENUM, MESSAGE
526
    }
527
    
528
    public enum FieldType {
529
        DOUBLE, FLOAT, INT64, UINT64, INT32, FIXED64, FIXED32, BOOL, STRING,
530
        GROUP, MESSAGE, BYTES, UINT32, ENUM, SFIXED32, SFIXED64, SINT32, SINT64
531
    }
532
}
533
```
534

535
**Usage Examples:**
536

537
```java
538
import com.google.protobuf.*;
539
import java.io.*;
540

541
// Writing protocol buffer data
542
try (OutputStream output = new FileOutputStream("message.pb")) {
543
    CodedOutputStream codedOutput = CodedOutputStream.newInstance(output);
544
    
545
    // Write fields manually
546
    codedOutput.writeString(1, "Hello Protocol Buffers");
547
    codedOutput.writeInt32(2, 42);
548
    codedOutput.writeBool(3, true);
549
    codedOutput.writeBytes(4, ByteString.copyFromUtf8("Binary data"));
550
    
551
    codedOutput.flush();
552
} catch (IOException e) {
553
    System.err.println("Write error: " + e.getMessage());
554
}
555

556
// Reading protocol buffer data
557
try (InputStream input = new FileInputStream("message.pb")) {
558
    CodedInputStream codedInput = CodedInputStream.newInstance(input);
559
    
560
    while (!codedInput.isAtEnd()) {
561
        int tag = codedInput.readTag();
562
        int fieldNumber = WireFormat.getTagFieldNumber(tag);
563
        int wireType = WireFormat.getTagWireType(tag);
564
        
565
        switch (fieldNumber) {
566
            case 1:
567
                String stringValue = codedInput.readString();
568
                System.out.println("String field: " + stringValue);
569
                break;
570
            case 2:
571
                int intValue = codedInput.readInt32();
572
                System.out.println("Int field: " + intValue);
573
                break;
574
            case 3:
575
                boolean boolValue = codedInput.readBool();
576
                System.out.println("Bool field: " + boolValue);
577
                break;
578
            case 4:
579
                ByteString bytesValue = codedInput.readBytes();
580
                System.out.println("Bytes field: " + bytesValue.toStringUtf8());
581
                break;
582
            default:
583
                codedInput.skipField(tag);
584
                break;
585
        }
586
    }
587
} catch (IOException e) {
588
    System.err.println("Read error: " + e.getMessage());
589
}
590

591
// Size computation example
592
String text = "Hello Protocol Buffers";
593
int fieldSize = CodedOutputStream.computeStringSize(1, text);
594
int totalSize = fieldSize; // Add sizes of other fields
595
byte[] buffer = new byte[totalSize];
596

597
CodedOutputStream output = CodedOutputStream.newInstance(buffer);
598
output.writeString(1, text);
599
```
600

601
### Advanced I/O Features
602

603
```java { .api }
604
/**
605
 * Advanced I/O configuration and limits
606
 */
607
public abstract class CodedInputStream {
608
    /** Default recursion limit for nested messages */
609
    public static final int DEFAULT_RECURSION_LIMIT = 100;
610
    
611
    /** Default size limit for individual messages */  
612
    public static final int DEFAULT_SIZE_LIMIT = 64 << 20; // 64MB
613
    
614
    /** Sets recursion limit to prevent stack overflow */
615
    public void setRecursionLimit(int limit);
616
    
617
    /** Gets current recursion limit */
618
    public int getRecursionLimit();
619
    
620
    /** Sets size limit for individual messages */
621
    public void setSizeLimit(int limit);
622
    
623
    /** Gets current size limit */
624
    public int getSizeLimit();
625
}
626

627
/**
628
 * Advanced output configuration
629
 */
630
public abstract class CodedOutputStream {
631
    /** Enables deterministic serialization (affects map ordering) */
632
    public void useDeterministicSerialization();
633
    
634
    /** Checks if deterministic serialization is enabled */
635
    public boolean isSerializationDeterministic();
636
}
637
```
638

639
## Types
640

641
```java { .api }
642
// Input/Output buffer management
643
public abstract class AllocatedBuffer {
644
    // Buffer allocation interface for advanced memory management
645
}
646

647
public abstract class BufferAllocator {
648
    // Buffer allocator interface for custom memory management
649
}
650

651
// Unsafe operations for extreme performance (use with caution)
652
public final class UnsafeByteOperations {
653
    /** Wraps byte array without copying (unsafe) */
654
    public static ByteString unsafeWrap(byte[] buffer);
655
    
656
    /** Wraps byte array region without copying (unsafe) */
657
    public static ByteString unsafeWrap(byte[] buffer, int offset, int length);
658
    
659
    /** Wraps ByteBuffer without copying (unsafe) */
660
    public static ByteString unsafeWrap(ByteBuffer buffer);
661
    
662
    /** Writes ByteString without copying (unsafe) */
663
    public static void unsafeWriteTo(ByteString bytes, ByteOutput output) throws IOException;
664
}
665
```