0
# Core Messages and Serialization
1

2
Core message interfaces and implementations providing the foundation for all protocol buffer messages, including serialization, parsing, builder patterns, and binary data handling.
3

4
## Capabilities
5

6
### MessageLite Interface
7

8
The base interface for all protocol buffer message types, providing essential serialization capabilities without reflection support.
9

10
```java { .api }
11
/**
12
 * Base interface for all protocol buffer message types
13
 */
14
public interface MessageLite extends MessageLiteOrBuilder {
15
    /** Serializes message to coded output stream */
16
    void writeTo(CodedOutputStream output) throws IOException;
17
    
18
    /** Returns the number of bytes required to encode this message */ 
19
    int getSerializedSize();
20
    
21
    /** Serializes message to ByteString */
22
    ByteString toByteString();
23
    
24
    /** Serializes message to byte array */
25
    byte[] toByteArray();
26
    
27
    /** Writes message to OutputStream */
28
    void writeTo(OutputStream output) throws IOException;
29
    
30
    /** Writes size-delimited message to OutputStream */
31
    boolean writeDelimitedTo(OutputStream output) throws IOException;
32
    
33
    /** Gets parser for messages of same type */
34
    Parser<? extends MessageLite> getParserForType();
35
    
36
    /** Gets default instance for this message type */
37
    MessageLite getDefaultInstanceForType();
38
    
39
    /** Creates new builder for this message type */
40
    Builder newBuilderForType();
41
    
42
    /** Creates builder initialized with this message's data */  
43
    Builder toBuilder();
44
    
45
    /** Interface for building MessageLite instances */
46
    public interface Builder extends MessageLiteOrBuilder, Cloneable {
47
        MessageLite build();
48
        MessageLite buildPartial();
49
        Builder clear();
50
        Builder clone();
51
        boolean isInitialized();
52
        
53
        Builder mergeFrom(CodedInputStream input) throws IOException;
54
        Builder mergeFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry) throws IOException;
55
        Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
56
        Builder mergeFrom(ByteString data, ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException;
57
        Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
58
        Builder mergeFrom(byte[] data, ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException;
59
        Builder mergeFrom(MessageLite other);
60
    }
61
}
62
```
63

64
### Message Interface
65

66
Extended interface for full protocol buffer messages with reflection support, enabling runtime field access and manipulation.
67

68
```java { .api }
69
/**
70
 * Extended interface for protocol buffer messages with reflection support
71
 */
72
public interface Message extends MessageLite, MessageOrBuilder {
73
    /** Gets parser for messages of same type (covariant return) */
74
    Parser<? extends Message> getParserForType();
75
    
76
    /** Creates new builder for this message type (covariant return) */
77
    Builder newBuilderForType();
78
    
79
    /** Creates builder initialized with this message's data (covariant return) */
80
    Builder toBuilder();
81
    
82
    /** Message equality comparison */
83
    boolean equals(Object other);
84
    
85
    /** Hash code computation */
86
    int hashCode();
87
    
88
    /** Protocol buffer text format representation */
89
    String toString();
90
    
91
    /** Interface for building Message instances with reflection support */
92
    public interface Builder extends MessageLite.Builder, MessageOrBuilder {
93
        Message build();
94
        Message buildPartial();
95
        Builder clear();
96
        Builder clone();
97
        
98
        Builder mergeFrom(Message other);
99
        Builder mergeFrom(CodedInputStream input) throws IOException; 
100
        Builder mergeFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry) throws IOException;
101
        
102
        // Field manipulation methods
103
        Builder setField(Descriptors.FieldDescriptor field, Object value);
104
        Builder addRepeatedField(Descriptors.FieldDescriptor field, Object value);
105
        Builder clearField(Descriptors.FieldDescriptor field);
106
        Builder clearOneof(Descriptors.OneofDescriptor oneof);
107
        
108
        // Nested message builders
109
        Message.Builder newBuilderForField(Descriptors.FieldDescriptor field);
110
        Message.Builder getFieldBuilder(Descriptors.FieldDescriptor field);
111
        Message.Builder getRepeatedFieldBuilder(Descriptors.FieldDescriptor field, int index);
112
    }
113
}
114
```
115

116
### MessageOrBuilder Interface
117

118
Common interface for messages and builders providing field access methods for reflection-based operations.
119

120
```java { .api }
121
/**
122
 * Common interface for messages and builders providing field access
123
 */
124
public interface MessageOrBuilder extends MessageLiteOrBuilder {
125
    /** Get field value by descriptor */
126
    Object getField(Descriptors.FieldDescriptor field);
127
    
128
    /** Check if field is set */
129
    boolean hasField(Descriptors.FieldDescriptor field);
130
    
131
    /** Get repeated field count */
132
    int getRepeatedFieldCount(Descriptors.FieldDescriptor field);
133
    
134
    /** Get repeated field element by index */
135
    Object getRepeatedField(Descriptors.FieldDescriptor field, int index);
136
    
137
    /** Get all fields as map */
138
    Map<Descriptors.FieldDescriptor, Object> getAllFields();
139
    
140
    /** Check if oneof case is set */
141
    boolean hasOneof(Descriptors.OneofDescriptor oneof);
142
    
143
    /** Get active oneof field descriptor */
144
    Descriptors.FieldDescriptor getOneofFieldDescriptor(Descriptors.OneofDescriptor oneof);
145
    
146
    /** Get message descriptor */
147
    Descriptors.Descriptor getDescriptorForType();
148
    
149
    /** Get unknown fields */
150
    UnknownFieldSet getUnknownFields();
151
    
152
    /** Check if all required fields are set */
153
    boolean isInitialized();
154
    
155
    /** Find missing required fields */
156
    List<String> findInitializationErrors();
157
    
158
    /** Get initialization error string */
159
    String getInitializationErrorString();
160
}
161
```
162

163
### Abstract Message Classes
164

165
Base implementations providing common functionality for generated message classes.
166

167
```java { .api }
168
/**
169
 * Partial implementation of Message interface providing common functionality
170
 */
171
public abstract class AbstractMessage implements Message {
172
    /** Check if all required fields are set */
173
    public boolean isInitialized();
174
    
175
    /** Find missing required fields */
176
    public List<String> findInitializationErrors();
177
    
178
    /** Get initialization error string */
179
    public String getInitializationErrorString();
180
    
181
    /** Check if oneof case is set */
182
    public boolean hasOneof(Descriptors.OneofDescriptor oneof);
183
    
184
    /** Get active oneof field descriptor */
185
    public Descriptors.FieldDescriptor getOneofFieldDescriptor(Descriptors.OneofDescriptor oneof);
186
    
187
    /** Generate text format string */
188
    public String toString();
189
    
190
    /** Write to coded output stream */
191
    public void writeTo(CodedOutputStream output) throws IOException;
192
    
193
    /** Get serialized size in bytes */
194
    public int getSerializedSize();
195
    
196
    /** Compare messages for equality */
197
    public boolean equals(Object other);
198
    
199
    /** Generate hash code */
200
    public int hashCode();
201
    
202
    /**
203
     * Abstract builder implementation for Message types
204
     */
205
    public abstract static class Builder<BuilderType extends Builder<BuilderType>>
206
            implements Message.Builder {
207
        /** Clone the builder */
208
        public BuilderType clone();
209
        
210
        /** Check if oneof case is set */
211
        public boolean hasOneof(Descriptors.OneofDescriptor oneof);
212
        
213
        /** Clear oneof field */
214
        public BuilderType clearOneof(Descriptors.OneofDescriptor oneof);
215
        
216
        /** Clear all fields */
217
        public BuilderType clear();
218
        
219
        /** Find missing required fields */
220
        public List<String> findInitializationErrors();
221
        
222
        /** Merge from another message */
223
        public BuilderType mergeFrom(Message other);
224
        
225
        /** Merge from coded input stream */
226
        public BuilderType mergeFrom(CodedInputStream input) throws IOException;
227
        
228
        /** Merge from coded input stream with extension registry */
229
        public BuilderType mergeFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry) throws IOException;
230
        
231
        /** Merge unknown fields */
232
        public BuilderType mergeUnknownFields(UnknownFieldSet unknownFields);
233
    }
234
}
235

236
/**
237
 * Partial implementation of MessageLite providing common serialization functionality
238
 */
239
public abstract class AbstractMessageLite implements MessageLite {
240
    /** Serialize to ByteString */
241
    public ByteString toByteString();
242
    
243
    /** Serialize to byte array */
244
    public byte[] toByteArray();
245
    
246
    /** Write to output stream */
247
    public void writeTo(OutputStream output) throws IOException;
248
    
249
    /** Write with length delimiter */
250
    public void writeDelimitedTo(OutputStream output) throws IOException;
251
    
252
    /**
253
     * Abstract builder implementation for MessageLite types
254
     */
255
    public abstract static class Builder<MessageType extends AbstractMessageLite, BuilderType extends Builder<MessageType, BuilderType>>
256
            implements MessageLite.Builder {
257
        /** Clone the builder */
258
        public abstract BuilderType clone();
259
        
260
        /** Merge from coded input stream */
261
        public BuilderType mergeFrom(CodedInputStream input) throws IOException;
262
        
263
        /** Merge from coded input stream with extension registry */
264
        public abstract BuilderType mergeFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry) throws IOException;
265
        
266
        /** Merge from ByteString */
267
        public BuilderType mergeFrom(ByteString data) throws InvalidProtocolBufferException;
268
        
269
        /** Merge from ByteString with extension registry */
270
        public BuilderType mergeFrom(ByteString data, ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException;
271
        
272
        /** Merge from byte array */
273
        public BuilderType mergeFrom(byte[] data) throws InvalidProtocolBufferException;
274
        
275
        /** Merge from byte array with extension registry */ 
276
        public BuilderType mergeFrom(byte[] data, ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException;
277
        
278
        /** Merge from input stream */
279
        public BuilderType mergeFrom(InputStream input) throws IOException;
280
        
281
        /** Merge delimited from input stream */
282
        public boolean mergeDelimitedFrom(InputStream input) throws IOException;
283
        
284
        /** Merge from another message */
285
        public BuilderType mergeFrom(MessageLite other);
286
    }
287
}
288
```
289

290
### ByteString Binary Data Handling
291

292
Immutable wrapper around byte arrays providing string-like operations optimized for protocol buffer usage.
293

294
```java { .api }
295
/**
296
 * Immutable wrapper around byte arrays for efficient operations
297
 */
298
public abstract class ByteString {
299
    /** Empty ByteString constant */
300
    public static final ByteString EMPTY;
301
    
302
    // Static factory methods
303
    /** Creates ByteString from byte array */
304
    public static ByteString copyFrom(byte[] bytes);
305
    
306
    /** Creates ByteString from byte array slice */
307
    public static ByteString copyFrom(byte[] bytes, int offset, int size);
308
    
309
    /** Creates ByteString from ByteBuffer */
310
    public static ByteString copyFrom(ByteBuffer bytes);
311
    
312
    /** Creates ByteString from UTF-8 encoded string */
313
    public static ByteString copyFromUtf8(String text);
314
    
315
    /** Reads all bytes from InputStream */
316
    public static ByteString readFrom(InputStream streamToDrain) throws IOException;
317
    
318
    // Instance methods
319
    /** Gets byte at specified index */
320
    public abstract byte byteAt(int index);
321
    
322
    /** Returns the number of bytes */
323
    public abstract int size();
324
    
325
    /** Checks if ByteString is empty */
326
    public boolean isEmpty();
327
    
328
    /** Creates substring from beginIndex to end */
329
    public ByteString substring(int beginIndex);
330
    
331
    /** Creates substring with explicit end index */
332
    public ByteString substring(int beginIndex, int endIndex);
333
    
334
    /** Checks if starts with prefix */
335
    public boolean startsWith(ByteString prefix);
336
    
337
    /** Checks if ends with suffix */
338
    public boolean endsWith(ByteString suffix);
339
    
340
    /** Concatenates with another ByteString */
341
    public ByteString concat(ByteString other);
342
    
343
    /** Converts to byte array (copies data) */
344
    public byte[] toByteArray();
345
    
346
    /** Decodes as UTF-8 string */
347
    public String toStringUtf8();
348
    
349
    /** Checks if contains valid UTF-8 */
350
    public boolean isValidUtf8();
351
    
352
    /** Creates CodedInputStream from this ByteString */
353
    public CodedInputStream newCodedInput();
354
    
355
    /** Creates InputStream from this ByteString */
356
    public InputStream newInput();
357
    
358
    /** Creates iterator over bytes */
359
    public ByteIterator iterator();
360
    
361
    /** Writes contents to OutputStream */
362
    public void writeTo(OutputStream out) throws IOException;
363
    
364
    /** Writes contents to ByteBuffer */
365
    public void copyTo(ByteBuffer target);
366
    
367
    /** Copies to byte array at offset */
368
    public void copyTo(byte[] target, int offset);
369
    
370
    /** Copies to byte array with source and target offsets */
371
    public void copyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy);
372
    
373
    // Comparison and hashing
374
    public boolean equals(Object other);
375
    public int hashCode();
376
    public String toString();
377
}
378
```
379

380
**Usage Examples:**
381

382
```java
383
import com.google.protobuf.ByteString;
384

385
// Creating ByteString instances
386
ByteString empty = ByteString.EMPTY;
387
ByteString fromBytes = ByteString.copyFrom(new byte[]{1, 2, 3, 4});
388
ByteString fromString = ByteString.copyFromUtf8("Hello Protocol Buffers");
389

390
// String-like operations
391
ByteString prefix = fromString.substring(0, 5); // "Hello"
392
ByteString suffix = fromString.substring(6);     // "Protocol Buffers"
393
ByteString combined = prefix.concat(ByteString.copyFromUtf8(" World"));
394

395
// Conversions
396
byte[] bytes = fromString.toByteArray();
397
String text = fromString.toStringUtf8();
398
boolean isValidUtf8 = fromString.isValidUtf8();
399
```
400

401
### Generated Message Classes
402

403
Base classes for code-generated message implementations providing optimized serialization and builder patterns.
404

405
```java { .api }
406
/**
407
 * Base class for generated protocol buffer message classes
408
 */
409
public abstract class GeneratedMessage extends AbstractMessage {
410
    /** Gets parser for message type (abstract method) */
411
    public abstract Parser<? extends GeneratedMessage> getParserForType();
412
    
413
    /** Testing configuration for field builders */
414
    public static void setAlwaysUseFieldBuildersForTesting(boolean useBuilders);
415
    
416
    /** Unknown fields storage */
417
    protected UnknownFieldSet unknownFields;
418
    
419
    /** Protected constructors */
420
    protected GeneratedMessage();
421
    protected GeneratedMessage(Builder<?> builder);
422
    
423
    /**
424
     * Base builder class for generated messages
425
     */
426
    public abstract static class Builder<BuilderType extends Builder<BuilderType>>
427
            extends AbstractMessage.Builder<BuilderType> {
428
        // Generated builders extend this class with type-safe field accessors
429
    }
430
}
431

432
/**
433
 * Base class for generated lite message classes (Android/constrained environments)
434
 */
435
public abstract class GeneratedMessageLite<MessageType extends GeneratedMessageLite<MessageType, BuilderType>, 
436
                                          BuilderType extends GeneratedMessageLite.Builder<MessageType, BuilderType>>
437
        extends AbstractMessageLite implements MessageLiteOrBuilder {
438
    
439
    /** Gets parser for message type */
440
    public final Parser<MessageType> getParserForType();
441
    
442
    /** Gets default instance */
443
    public final MessageType getDefaultInstanceForType();
444
    
445
    /** Creates new builder */
446
    public final BuilderType newBuilderForType();
447
    
448
    /** Creates builder from message */
449
    public final BuilderType toBuilder();
450
    
451
    /**
452
     * Base builder class for generated lite messages
453
     */
454
    public abstract static class Builder<MessageType extends GeneratedMessageLite<MessageType, BuilderType>,
455
                                        BuilderType extends Builder<MessageType, BuilderType>>
456
            extends AbstractMessageLite.Builder<MessageType, BuilderType>
457
            implements MessageLiteOrBuilder {
458
        // Generated lite builders extend this class
459
    }
460
}
461
```
462

463
### Dynamic Message Support
464

465
Runtime message creation and manipulation for messages without generated classes.
466

467
```java { .api }
468
/**
469
 * Implementation of Message that can represent arbitrary message types
470
 */
471
public final class DynamicMessage extends AbstractMessage {
472
    // Static factory methods
473
    /** Gets default instance for message type */
474
    public static DynamicMessage getDefaultInstance(Descriptors.Descriptor type);
475
    
476
    /** Creates builder for message type */
477
    public static Builder newBuilder(Descriptors.Descriptor type);
478
    
479
    // Parsing methods
480
    /** Parses from coded input stream */
481
    public static DynamicMessage parseFrom(Descriptors.Descriptor type, CodedInputStream input) 
482
        throws InvalidProtocolBufferException;
483
        
484
    /** Parses from coded input stream with extension registry */
485
    public static DynamicMessage parseFrom(Descriptors.Descriptor type, CodedInputStream input,
486
                                         ExtensionRegistryLite extensionRegistry) 
487
        throws InvalidProtocolBufferException;
488
        
489
    /** Parses from ByteString */
490
    public static DynamicMessage parseFrom(Descriptors.Descriptor type, ByteString data)
491
        throws InvalidProtocolBufferException;
492
        
493
    /** Parses from byte array */
494
    public static DynamicMessage parseFrom(Descriptors.Descriptor type, byte[] data)
495
        throws InvalidProtocolBufferException;
496
    
497
    /**
498
     * Builder for dynamic messages
499
     */
500
    public static final class Builder extends AbstractMessage.Builder<Builder> {
501
        /** Creates builder for message type */
502
        public static Builder newBuilder(Descriptors.Descriptor type);
503
        
504
        /** Builds the dynamic message */
505
        public DynamicMessage build();
506
        
507
        /** Builds partial dynamic message */
508
        public DynamicMessage buildPartial();
509
    }
510
}
511
```
512

513
**Usage Examples:**
514

515
```java
516
import com.google.protobuf.*;
517

518
// Working with generated messages (example)
519
try {
520
    // Parsing messages
521
    MyMessage message = MyMessage.parseFrom(inputData);
522
    
523
    // Building messages
524
    MyMessage newMessage = MyMessage.newBuilder()
525
        .setStringField("value")
526
        .setIntField(42)
527
        .addRepeatedField("item1")
528
        .addRepeatedField("item2")
529
        .build();
530
        
531
    // Serialization
532
    ByteString serialized = newMessage.toByteString();
533
    byte[] bytes = newMessage.toByteArray();
534
    
535
} catch (InvalidProtocolBufferException e) {
536
    System.err.println("Parse error: " + e.getMessage());
537
}
538

539
// Working with dynamic messages
540
Descriptors.Descriptor messageType = getMessageDescriptor();
541
DynamicMessage dynamicMessage = DynamicMessage.newBuilder(messageType)
542
    .setField(fieldDescriptor1, "value")
543
    .setField(fieldDescriptor2, 123)
544
    .build();
545
```
546

547
## Exception Handling
548

549
```java { .api }
550
/**
551
 * Exception thrown when protocol buffer parsing fails
552
 */
553
public class InvalidProtocolBufferException extends IOException {
554
    /** Creates with description */
555
    public InvalidProtocolBufferException(String description);
556
    
557
    /** Creates from exception */
558
    public InvalidProtocolBufferException(Exception e);
559
    
560
    /** Creates with description and cause */
561
    public InvalidProtocolBufferException(String description, Exception e);
562
    
563
    /** Attaches unfinished message for partial parsing recovery */
564
    public InvalidProtocolBufferException setUnfinishedMessage(MessageLite unfinishedMessage);
565
    
566
    /** Gets unfinished message if available */
567
    public MessageLite getUnfinishedMessage();
568
    
569
    /** Unwraps underlying IOException */
570
    public IOException unwrapIOException();
571
}
572
```
573

574
Common exception scenarios:
575
- **Malformed wire format data**: Invalid varint encoding, unexpected end of data
576
- **Required field violations**: Missing required fields during parsing  
577
- **Type mismatches**: Wrong field types in wire format
578
- **Recursion limits**: Deeply nested messages exceeding limits
579
- **Unknown extensions**: Extension fields without proper registry
580

581
## Types
582

583
```java { .api }
584
// Core lifecycle interfaces
585
public interface MessageLiteOrBuilder {}
586

587
public interface Parser<MessageType extends MessageLite> {
588
    MessageType parseFrom(CodedInputStream input) throws InvalidProtocolBufferException;
589
    MessageType parseFrom(ByteString data) throws InvalidProtocolBufferException;
590
    MessageType parseFrom(byte[] data) throws InvalidProtocolBufferException;
591
    MessageType parseFrom(InputStream input) throws IOException;
592
    MessageType parseDelimitedFrom(InputStream input) throws IOException;
593
}
594

595
// Lite extension support
596
public abstract class ExtensionLite<ContainingType extends MessageLite, Type> {
597
    // Extension field definition base class
598
}
599

600
public class ExtensionRegistryLite {
601
    public static ExtensionRegistryLite newInstance();
602
    public static ExtensionRegistryLite getEmptyRegistry();
603
}
604
```