0
# Serialization and I/O
1

2
Binary serialization, deserialization, and I/O operations for protocol buffer messages. This includes ByteString utilities, coded streams, and wire format support in the shaded akka.protobufv3.internal package.
3

4
## Capabilities
5

6
### ByteString Class
7

8
Immutable sequence of bytes with rich manipulation methods. Provides efficient operations for byte data handling and string conversions.
9

10
```java { .api }
11
/**
12
 * Immutable sequence of bytes with efficient manipulation methods.
13
 * Optimized for protocol buffer operations with lazy evaluation and sharing.
14
 */
15
class ByteString {
16
    /** Create ByteString from byte array */
17
    static ByteString copyFrom(byte[] bytes);
18
    
19
    /** Create ByteString from byte array segment */
20
    static ByteString copyFrom(byte[] bytes, int offset, int size);
21
    
22
    /** Create ByteString from UTF-8 encoded string */
23
    static ByteString copyFromUtf8(String text);
24
    
25
    /** Create ByteString from string with specific charset */
26
    static ByteString copyFrom(String text, String charsetName) 
27
        throws UnsupportedEncodingException;
28
    
29
    /** Create ByteString from string with charset */
30
    static ByteString copyFrom(String text, Charset charset);
31
    
32
    /** Create ByteString from InputStream */
33
    static ByteString readFrom(InputStream streamToDrain) throws IOException;
34
    
35
    /** Create ByteString from InputStream with size limit */
36
    static ByteString readFrom(InputStream streamToDrain, int chunkSize) throws IOException;
37
    
38
    /** Empty ByteString constant */
39
    static final ByteString EMPTY;
40
    
41
    /** Convert to byte array */
42
    byte[] toByteArray();
43
    
44
    /** Convert to UTF-8 string */
45
    String toStringUtf8();
46
    
47
    /** Convert to string with specific charset */
48
    String toString(String charsetName) throws UnsupportedEncodingException;
49
    
50
    /** Convert to string with charset */
51
    String toString(Charset charset);
52
    
53
    /** Get size in bytes */
54
    int size();
55
    
56
    /** Check if empty */
57
    boolean isEmpty();
58
    
59
    /** Get byte at specific index */
60
    byte byteAt(int index);
61
    
62
    /** Create substring from begin index to end */
63
    ByteString substring(int beginIndex);
64
    
65
    /** Create substring from begin to end index */
66
    ByteString substring(int beginIndex, int endIndex);
67
    
68
    /** Concatenate with another ByteString */
69
    ByteString concat(ByteString other);
70
    
71
    /** Check if starts with specific ByteString */
72
    boolean startsWith(ByteString prefix);
73
    
74
    /** Check if ends with specific ByteString */
75
    boolean endsWith(ByteString suffix);
76
    
77
    /** Create iterator over bytes */
78
    ByteIterator iterator();
79
    
80
    /** Copy bytes to existing byte array */
81
    void copyTo(byte[] target, int offset);
82
    
83
    /** Copy bytes to ByteBuffer */
84
    void copyTo(ByteBuffer target);
85
    
86
    /** Create new CodedInputStream from this ByteString */
87
    CodedInputStream newCodedInput();
88
    
89
    /** Create InputStream from this ByteString */
90
    InputStream newInput();
91
}
92
```
93

94
### CodedInputStream Class
95

96
Reads and decodes protocol message fields from various input sources. Handles variable-length encoding and provides methods for reading all protobuf wire format types.
97

98
```java { .api }
99
/**
100
 * Reads and decodes protocol message fields from input sources.
101
 * Handles protobuf wire format including varint encoding and length-delimited fields.
102
 */
103
class CodedInputStream {
104
    /** Create from byte array */
105
    static CodedInputStream newInstance(byte[] buf);
106
    
107
    /** Create from byte array segment */
108
    static CodedInputStream newInstance(byte[] buf, int off, int len);
109
    
110
    /** Create from ByteString */
111
    static CodedInputStream newInstance(ByteString byteString);
112
    
113
    /** Create from InputStream */
114
    static CodedInputStream newInstance(InputStream input);
115
    
116
    /** Create from InputStream with buffer size */
117
    static CodedInputStream newInstance(InputStream input, int bufferSize);
118
    
119
    /** Read a 32-bit integer */
120
    int readInt32() throws IOException;
121
    
122
    /** Read a 64-bit integer */
123
    long readInt64() throws IOException;
124
    
125
    /** Read an unsigned 32-bit integer */
126
    int readUInt32() throws IOException;
127
    
128
    /** Read an unsigned 64-bit integer */
129
    long readUInt64() throws IOException;
130
    
131
    /** Read a signed 32-bit integer */
132
    int readSInt32() throws IOException;
133
    
134
    /** Read a signed 64-bit integer */
135
    long readSInt64() throws IOException;
136
    
137
    /** Read a fixed 32-bit integer */
138
    int readFixed32() throws IOException;
139
    
140
    /** Read a fixed 64-bit integer */
141
    long readFixed64() throws IOException;
142
    
143
    /** Read a signed fixed 32-bit integer */
144
    int readSFixed32() throws IOException;
145
    
146
    /** Read a signed fixed 64-bit integer */
147
    long readSFixed64() throws IOException;
148
    
149
    /** Read a float */
150
    float readFloat() throws IOException;
151
    
152
    /** Read a double */
153
    double readDouble() throws IOException;
154
    
155
    /** Read a boolean */
156
    boolean readBool() throws IOException;
157
    
158
    /** Read a string */
159
    String readString() throws IOException;
160
    
161
    /** Read bytes as ByteString */
162
    ByteString readBytes() throws IOException;
163
    
164
    /** Read a varint field tag */
165
    int readTag() throws IOException;
166
    
167
    /** Check if at end of input */
168
    boolean isAtEnd() throws IOException;
169
    
170
    /** Skip a field with given tag */
171
    boolean skipField(int tag) throws IOException;
172
    
173
    /** Set size limit for messages */
174
    int setSizeLimit(int limit);
175
    
176
    /** Set recursion depth limit */
177
    int setRecursionLimit(int limit);
178
    
179
    /** Push a new limit for length-delimited messages */
180
    int pushLimit(int byteLimit) throws InvalidProtocolBufferException;
181
    
182
    /** Pop the current limit */
183
    void popLimit(int oldLimit);
184
    
185
    /** Get the total bytes read */
186
    int getTotalBytesRead();
187
}
188
```
189

190
### CodedOutputStream Class
191

192
Encodes and writes protocol message fields to various output destinations. Handles variable-length encoding and provides methods for writing all protobuf wire format types.
193

194
```java { .api }
195
/**
196
 * Encodes and writes protocol message fields to output destinations.
197
 * Handles protobuf wire format encoding including varint and length-delimited fields.
198
 */
199
class CodedOutputStream {
200
    /** Create writing to byte array */
201
    static CodedOutputStream newInstance(byte[] flatArray);
202
    
203
    /** Create writing to byte array segment */
204
    static CodedOutputStream newInstance(byte[] flatArray, int offset, int length);
205
    
206
    /** Create writing to OutputStream */
207
    static CodedOutputStream newInstance(OutputStream output);
208
    
209
    /** Create writing to OutputStream with buffer size */
210
    static CodedOutputStream newInstance(OutputStream output, int bufferSize);
211
    
212
    /** Write a 32-bit integer field */
213
    void writeInt32(int fieldNumber, int value) throws IOException;
214
    
215
    /** Write a 64-bit integer field */
216
    void writeInt64(int fieldNumber, long value) throws IOException;
217
    
218
    /** Write an unsigned 32-bit integer field */
219
    void writeUInt32(int fieldNumber, int value) throws IOException;
220
    
221
    /** Write an unsigned 64-bit integer field */
222
    void writeUInt64(int fieldNumber, long value) throws IOException;
223
    
224
    /** Write a signed 32-bit integer field */
225
    void writeSInt32(int fieldNumber, int value) throws IOException;
226
    
227
    /** Write a signed 64-bit integer field */
228
    void writeSInt64(int fieldNumber, long value) throws IOException;
229
    
230
    /** Write a fixed 32-bit integer field */
231
    void writeFixed32(int fieldNumber, int value) throws IOException;
232
    
233
    /** Write a fixed 64-bit integer field */
234
    void writeFixed64(int fieldNumber, long value) throws IOException;
235
    
236
    /** Write a signed fixed 32-bit integer field */
237
    void writeSFixed32(int fieldNumber, int value) throws IOException;
238
    
239
    /** Write a signed fixed 64-bit integer field */
240
    void writeSFixed64(int fieldNumber, long value) throws IOException;
241
    
242
    /** Write a float field */
243
    void writeFloat(int fieldNumber, float value) throws IOException;
244
    
245
    /** Write a double field */
246
    void writeDouble(int fieldNumber, double value) throws IOException;
247
    
248
    /** Write a boolean field */
249
    void writeBool(int fieldNumber, boolean value) throws IOException;
250
    
251
    /** Write a string field */
252
    void writeString(int fieldNumber, String value) throws IOException;
253
    
254
    /** Write bytes field */
255
    void writeBytes(int fieldNumber, ByteString value) throws IOException;
256
    
257
    /** Write a message field */
258
    void writeMessage(int fieldNumber, MessageLite value) throws IOException;
259
    
260
    /** Write field tag */
261
    void writeTag(int fieldNumber, int wireType) throws IOException;
262
    
263
    /** Write raw varint */
264
    void writeRawVarint32(int value) throws IOException;
265
    
266
    /** Write raw varint64 */
267
    void writeRawVarint64(long value) throws IOException;
268
    
269
    /** Write raw bytes */
270
    void writeRawBytes(ByteString value) throws IOException;
271
    
272
    /** Flush any buffered output */
273
    void flush() throws IOException;
274
    
275
    /** Get the current buffer space */
276
    int spaceLeft();
277
    
278
    /** Compute the size needed for a field */
279
    static int computeInt32Size(int fieldNumber, int value);
280
    static int computeStringSize(int fieldNumber, String value);
281
    static int computeMessageSize(int fieldNumber, MessageLite value);
282
}
283
```
284

285
### WireFormat Class
286

287
Constants and helper functions for protocol buffer wire format. Defines wire types and provides utilities for working with field tags.
288

289
```java { .api }
290
/**
291
 * Constants and helper functions for protocol buffer wire format.
292
 * Defines wire types and tag manipulation utilities.
293
 */
294
class WireFormat {
295
    /** Wire type constants */
296
    static final int WIRETYPE_VARINT = 0;
297
    static final int WIRETYPE_FIXED64 = 1;
298
    static final int WIRETYPE_LENGTH_DELIMITED = 2;
299
    static final int WIRETYPE_START_GROUP = 3;
300
    static final int WIRETYPE_END_GROUP = 4;
301
    static final int WIRETYPE_FIXED32 = 5;
302
    
303
    /** Extract field number from tag */
304
    static int getTagFieldNumber(int tag);
305
    
306
    /** Extract wire type from tag */
307
    static int getTagWireType(int tag);
308
    
309
    /** Create tag from field number and wire type */
310
    static int makeTag(int fieldNumber, int wireType);
311
    
312
    /** JavaType enumeration for field types */
313
    enum JavaType {
314
        INT, LONG, FLOAT, DOUBLE, BOOLEAN, STRING, BYTE_STRING, ENUM, MESSAGE;
315
    }
316
    
317
    /** FieldType enumeration with wire format details */
318
    enum FieldType {
319
        DOUBLE(JavaType.DOUBLE, WIRETYPE_FIXED64),
320
        FLOAT(JavaType.FLOAT, WIRETYPE_FIXED32),
321
        INT64(JavaType.LONG, WIRETYPE_VARINT),
322
        UINT64(JavaType.LONG, WIRETYPE_VARINT),
323
        INT32(JavaType.INT, WIRETYPE_VARINT),
324
        FIXED64(JavaType.LONG, WIRETYPE_FIXED64),
325
        FIXED32(JavaType.INT, WIRETYPE_FIXED32),
326
        BOOL(JavaType.BOOLEAN, WIRETYPE_VARINT),
327
        STRING(JavaType.STRING, WIRETYPE_LENGTH_DELIMITED),
328
        MESSAGE(JavaType.MESSAGE, WIRETYPE_LENGTH_DELIMITED),
329
        BYTES(JavaType.BYTE_STRING, WIRETYPE_LENGTH_DELIMITED),
330
        UINT32(JavaType.INT, WIRETYPE_VARINT),
331
        ENUM(JavaType.ENUM, WIRETYPE_VARINT),
332
        SFIXED32(JavaType.INT, WIRETYPE_FIXED32),
333
        SFIXED64(JavaType.LONG, WIRETYPE_FIXED64),
334
        SINT32(JavaType.INT, WIRETYPE_VARINT),
335
        SINT64(JavaType.LONG, WIRETYPE_VARINT);
336
        
337
        /** Get the Java type for this field type */
338
        JavaType getJavaType();
339
        
340
        /** Get the wire type for this field type */
341
        int getWireType();
342
    }
343
}
344
```
345

346
### TextFormat Class
347

348
Provides text parsing and formatting for protocol buffers. Enables human-readable representation of messages for debugging and configuration.
349

350
```java { .api }
351
/**
352
 * Utilities for converting protocol buffer messages to/from text format.
353
 * Useful for debugging, logging, and human-readable configuration files.
354
 */
355
class TextFormat {
356
    /** Convert message to text format string */
357
    static String printToString(MessageOrBuilder message);
358
    
359
    /** Print message to Appendable */
360
    static void print(MessageOrBuilder message, Appendable output) throws IOException;
361
    
362
    /** Parse text format into message builder */
363
    static void merge(Readable input, Message.Builder builder) throws IOException;
364
    
365
    /** Parse text format string into message builder */
366
    static void merge(CharSequence input, Message.Builder builder) 
367
        throws TextFormatParseException;
368
    
369
    /** Parse text format with extension registry */
370
    static void merge(Readable input, ExtensionRegistry extensionRegistry, 
371
                     Message.Builder builder) throws IOException;
372
    
373
    /** Printer class for customizable text format output */
374
    static class Printer {
375
        /** Create printer that includes default value fields */
376
        Printer includingDefaultValueFields();
377
        
378
        /** Create printer that preserves proto field names */
379
        Printer preservingProtoFieldNames();
380
        
381
        /** Create printer with custom type registry */
382
        Printer usingTypeRegistry(JsonFormat.TypeRegistry registry);
383
        
384
        /** Print message to string */
385
        String print(MessageOrBuilder message);
386
        
387
        /** Print message to Appendable */
388
        void print(MessageOrBuilder message, Appendable output) throws IOException;
389
    }
390
    
391
    /** Parser class for customizable text format parsing */
392
    static class Parser {
393
        /** Create parser that ignores unknown fields */
394
        Parser ignoringUnknownFields();
395
        
396
        /** Create parser that allows missing required fields */
397
        Parser allowingMissingRequiredFields();
398
        
399
        /** Create parser with custom type registry */
400
        Parser usingTypeRegistry(JsonFormat.TypeRegistry registry);
401
        
402
        /** Parse from Readable into builder */
403
        void merge(Readable input, Message.Builder builder) throws IOException;
404
        
405
        /** Parse from string into builder */
406
        void merge(CharSequence input, Message.Builder builder) 
407
            throws TextFormatParseException;
408
    }
409
    
410
    /** Create default printer */
411
    static Printer printer();
412
    
413
    /** Create default parser */
414
    static Parser parser();
415
}
416
```
417

418
## Usage Examples
419

420
### ByteString Operations
421

422
```java
423
import akka.protobufv3.internal.ByteString;
424

425
// Create ByteString from string
426
ByteString data = ByteString.copyFromUtf8("Hello Protocol Buffers");
427

428
// Create from byte array
429
byte[] bytes = {1, 2, 3, 4, 5};
430
ByteString fromBytes = ByteString.copyFrom(bytes);
431

432
// Convert back to string and bytes
433
String text = data.toStringUtf8();
434
byte[] backToBytes = data.toByteArray();
435

436
// Concatenation and substring
437
ByteString part1 = ByteString.copyFromUtf8("Hello ");
438
ByteString part2 = ByteString.copyFromUtf8("World");
439
ByteString combined = part1.concat(part2);
440
ByteString substring = combined.substring(0, 5); // "Hello"
441

442
// Check properties
443
boolean isEmpty = data.isEmpty();
444
int size = data.size();
445
byte firstByte = data.byteAt(0);
446
```
447

448
### CodedInputStream Usage
449

450
```java
451
import akka.protobufv3.internal.*;
452

453
// Read from byte array
454
byte[] data = getSerializedData();
455
CodedInputStream input = CodedInputStream.newInstance(data);
456

457
try {
458
    while (!input.isAtEnd()) {
459
        int tag = input.readTag();
460
        int fieldNumber = WireFormat.getTagFieldNumber(tag);
461
        int wireType = WireFormat.getTagWireType(tag);
462
        
463
        switch (wireType) {
464
            case WireFormat.WIRETYPE_VARINT:
465
                long value = input.readInt64();
466
                break;
467
            case WireFormat.WIRETYPE_LENGTH_DELIMITED:
468
                ByteString bytes = input.readBytes();
469
                break;
470
            default:
471
                input.skipField(tag);
472
        }
473
    }
474
} catch (IOException e) {
475
    // Handle parsing error
476
}
477
```
478

479
### CodedOutputStream Usage
480

481
```java
482
import akka.protobufv3.internal.*;
483

484
// Write to byte array
485
byte[] buffer = new byte[1024];
486
CodedOutputStream output = CodedOutputStream.newInstance(buffer);
487

488
try {
489
    // Write various field types
490
    output.writeInt32(1, 42);                    // Field 1: int32
491
    output.writeString(2, "Hello");              // Field 2: string
492
    output.writeBool(3, true);                   // Field 3: bool
493
    output.writeBytes(4, ByteString.copyFromUtf8("data")); // Field 4: bytes
494
    
495
    output.flush();
496
    
497
    // Get the actual size written
498
    int bytesWritten = output.getTotalBytesWritten();
499
    
500
} catch (IOException e) {
501
    // Handle write error
502
}
503
```
504

505
### Text Format Operations
506

507
```java
508
import akka.protobufv3.internal.TextFormat;
509

510
// Convert message to text (assumes MyMessage exists)
511
// MyMessage message = MyMessage.newBuilder()
512
//     .setName("example")
513
//     .setId(123)
514
//     .build();
515

516
// String textFormat = TextFormat.printToString(message);
517
// System.out.println(textFormat);
518

519
// Parse text format back to message
520
// MyMessage.Builder builder = MyMessage.newBuilder();
521
// TextFormat.merge("name: \"parsed\" id: 456", builder);
522
// MyMessage parsed = builder.build();
523

524
// Use custom printer
525
TextFormat.Printer printer = TextFormat.printer()
526
    .includingDefaultValueFields()
527
    .preservingProtoFieldNames();
528

529
// String customFormat = printer.print(message);
530
```