0
# Protocol Buffers Java
1

2
Protocol Buffers Java (protobuf-java) is Google's official Java implementation of Protocol Buffers, providing a comprehensive solution for serializing structured data. It offers high-performance, language-neutral, platform-neutral serialization with strong type safety, compact binary format, and extensive compatibility guarantees across versions.
3

4
## Package Information
5

6
- **Package Name**: protobuf-java
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: com.google.protobuf
10
- **Artifact ID**: protobuf-java
11
- **Installation**: `<dependency><groupId>com.google.protobuf</groupId><artifactId>protobuf-java</artifactId><version>4.31.1</version></dependency>`
12

13
## Core Imports
14

15
```java
16
import com.google.protobuf.Message;
17
import com.google.protobuf.MessageLite;
18
import com.google.protobuf.ByteString;
19
import com.google.protobuf.CodedInputStream;
20
import com.google.protobuf.CodedOutputStream;
21
import com.google.protobuf.InvalidProtocolBufferException;
22
```
23

24
For utility classes:
25

26
```java
27
import com.google.protobuf.util.JsonFormat;
28
import com.google.protobuf.util.Timestamps;
29
import com.google.protobuf.util.Durations;
30
import com.google.protobuf.util.FieldMaskUtil;
31
```
32

33
## Basic Usage
34

35
```java
36
import com.google.protobuf.*;
37

38
// Working with ByteString for binary data
39
ByteString data = ByteString.copyFromUtf8("Hello Protocol Buffers");
40
byte[] bytes = data.toByteArray();
41
String text = data.toStringUtf8();
42

43
// Parsing protocol buffer messages (example with generated message)
44
try {
45
    // Parse from various sources
46
    MyMessage message1 = MyMessage.parseFrom(bytes);
47
    MyMessage message2 = MyMessage.parseFrom(inputStream);
48
    MyMessage message3 = MyMessage.parseFrom(codedInputStream);
49
    
50
    // Serialize messages
51
    ByteString serialized = message1.toByteString();
52
    byte[] serializedBytes = message1.toByteArray();
53
    
54
    // Build new messages
55
    MyMessage newMessage = MyMessage.newBuilder()
56
        .setField1("value")
57
        .setField2(123)
58
        .build();
59
        
60
} catch (InvalidProtocolBufferException e) {
61
    // Handle parsing errors
62
    System.err.println("Failed to parse: " + e.getMessage());
63
}
64
```
65

66
## Architecture
67

68
Protocol Buffers Java is organized around several key components:
69

70
- **Message System**: Core interfaces (MessageLite, Message) and abstract implementations providing the foundation for all protocol buffer messages
71
- **Serialization Engine**: High-performance binary serialization using CodedInputStream/CodedOutputStream with wire format encoding
72
- **Type System**: ByteString for efficient binary data handling, with immutable operations and zero-copy optimizations where possible
73
- **Reflection API**: Complete runtime introspection through Descriptors for dynamic message handling and tooling
74
- **Extension System**: Support for protocol buffer extensions with type-safe registration and access
75
- **Utility Layer**: JSON conversion, timestamp/duration utilities, and field mask operations for common use cases
76

77
## Capabilities
78

79
### Core Message Interfaces and Serialization
80

81
Foundation interfaces and implementations for all protocol buffer messages, providing serialization, parsing, and builder patterns.
82

83
```java { .api }
84
public interface MessageLite {
85
    void writeTo(CodedOutputStream output) throws IOException;
86
    int getSerializedSize();
87
    ByteString toByteString();
88
    byte[] toByteArray();
89
    Parser<? extends MessageLite> getParserForType();
90
    Builder newBuilderForType();
91
    Builder toBuilder();
92
}
93

94
public interface Message extends MessageLite, MessageOrBuilder {
95
    Parser<? extends Message> getParserForType();
96
    Builder newBuilderForType();
97
    Builder toBuilder();
98
}
99
```
100

101
[Core Messages and Serialization](./core-messages.md)
102

103
### I/O and Wire Format Processing  
104

105
Low-level binary I/O operations for reading and writing protocol buffer wire format data with support for all protocol buffer data types.
106

107
```java { .api }
108
public abstract class CodedInputStream {
109
    static CodedInputStream newInstance(InputStream input);
110
    static CodedInputStream newInstance(byte[] buf);
111
    abstract int readTag();
112
    abstract int readInt32();
113
    abstract long readInt64();
114
    abstract String readString();
115
    abstract ByteString readBytes();
116
}
117

118
public abstract class CodedOutputStream {
119
    static CodedOutputStream newInstance(OutputStream output);
120
    static CodedOutputStream newInstance(byte[] flatArray);
121
    abstract void writeTag(int fieldNumber, int wireType);
122
    abstract void writeInt32(int fieldNumber, int value);
123
    abstract void writeString(int fieldNumber, String value);
124
    abstract void flush();
125
}
126
```
127

128
[I/O and Wire Format](./io-wire-format.md)
129

130
### Binary Data Handling
131

132
Efficient immutable binary data operations with ByteString, providing string-like operations optimized for protocol buffer usage.
133

134
```java { .api }
135
public abstract class ByteString {
136
    static final ByteString EMPTY;
137
    static ByteString copyFrom(byte[] bytes);
138
    static ByteString copyFromUtf8(String text);
139
    static ByteString readFrom(InputStream streamToDrain);
140
    
141
    abstract byte byteAt(int index);
142
    abstract int size();
143
    boolean isEmpty();
144
    ByteString substring(int beginIndex, int endIndex);
145
    ByteString concat(ByteString other);
146
    byte[] toByteArray();
147
    String toStringUtf8();
148
    boolean isValidUtf8();
149
}
150
```
151

152
[Core Messages and Serialization](./core-messages.md)
153

154
### Runtime Reflection and Type Discovery
155

156
Comprehensive reflection API for runtime introspection of protocol buffer types, enabling dynamic message handling and tooling.
157

158
```java { .api }
159
public static class Descriptors.FileDescriptor {
160
    String getName();
161
    String getPackage();
162
    List<Descriptor> getMessageTypes();
163
    List<EnumDescriptor> getEnumTypes();
164
    List<ServiceDescriptor> getServices();
165
    Descriptor findMessageTypeByName(String name);
166
}
167

168
public static class Descriptors.Descriptor {
169
    String getName();
170
    String getFullName();
171
    List<FieldDescriptor> getFields();
172
    List<Descriptor> getNestedTypes();
173
    FieldDescriptor findFieldByName(String name);
174
    FieldDescriptor findFieldByNumber(int number);
175
}
176

177
public static class Descriptors.FieldDescriptor {
178
    String getName();
179
    int getNumber();
180
    Type getType();
181
    boolean isRepeated();
182
    Object getDefaultValue();
183
}
184
```
185

186
[Reflection and Descriptors](./reflection-descriptors.md)
187

188
### JSON Format Conversion
189

190
Bidirectional conversion between protocol buffers and JSON format with configurable options for field naming, default values, and type handling.
191

192
```java { .api }
193
public static class JsonFormat.Printer {
194
    static Printer printer();
195
    Printer includingDefaultValueFields();
196
    Printer preservingProtoFieldNames();
197
    Printer omittingInsignificantWhitespace();
198
    String print(MessageOrBuilder message) throws InvalidProtocolBufferException;
199
}
200

201
public static class JsonFormat.Parser {
202
    static Parser parser();
203
    Parser ignoringUnknownFields();
204
    void merge(String json, Message.Builder builder) throws InvalidProtocolBufferException;
205
}
206
```
207

208
[JSON and Text Format](./json-text-format.md)
209

210
### Well-Known Types Utilities
211

212
Utility classes for working with protocol buffer well-known types like timestamps, durations, and field masks.
213

214
```java { .api }
215
public class Timestamps {
216
    static final Timestamp EPOCH;
217
    static Timestamp fromMillis(long millis);
218
    static long toMillis(Timestamp timestamp);
219
    static Timestamp parseTimestamp(String value) throws ParseException;
220
    static String toString(Timestamp timestamp);
221
}
222

223
public class Durations {
224
    static final Duration ZERO;
225
    static Duration fromMillis(long millis);
226
    static long toMillis(Duration duration);
227
    static Duration parseDuration(String value) throws ParseException;
228
}
229

230
public class FieldMaskUtil {
231
    static FieldMask fromString(String value);
232
    static String toString(FieldMask fieldMask);
233
    static void merge(FieldMask mask, Message source, Message.Builder destination);
234
}
235
```
236

237
[Utility Classes](./utilities.md)
238

239
### Text Format and Debugging
240

241
Human-readable text format support for debugging, configuration files, and development workflows.
242

243
```java { .api }
244
public static class TextFormat.Printer {
245
    static Printer printer();
246
    Printer escapingNonAscii(boolean escapeNonAscii);
247
    Printer usingTypeRegistry(TypeRegistry typeRegistry);
248
    String printToString(MessageOrBuilder message);
249
    void print(MessageOrBuilder message, Appendable output) throws IOException;
250
}
251

252
public static class TextFormat.Parser {
253
    static Parser getParser();
254
    void merge(Readable input, Message.Builder builder) throws IOException;
255
}
256
```
257

258
[JSON and Text Format](./json-text-format.md)
259

260
## Exception Handling
261

262
Protocol buffer operations can throw several specific exceptions:
263

264
```java { .api }
265
public class InvalidProtocolBufferException extends IOException {
266
    InvalidProtocolBufferException(String description);
267
    MessageLite getUnfinishedMessage();
268
    InvalidProtocolBufferException setUnfinishedMessage(MessageLite unfinishedMessage);
269
}
270
```
271

272
**Common scenarios:**
273
- **InvalidProtocolBufferException**: Thrown during parsing when data is malformed or incompatible
274
- **IOException**: Thrown during I/O operations with streams
275
- **IllegalArgumentException**: Thrown for invalid field numbers, null arguments, or malformed input
276

277
## Performance Considerations
278

279
- Use **CodedInputStream/CodedOutputStream** for high-performance streaming operations
280
- **ByteString** provides zero-copy operations where possible - prefer over byte arrays for repeated operations
281
- **Lite runtime** (protobuf-javalite) available for Android and memory-constrained environments
282
- Message builders reuse internal arrays when possible - prefer builder patterns for construction
283
- **UnsafeByteOperations** available for extreme performance scenarios (use with caution)
284

285
## Thread Safety
286

287
- **Messages** are immutable after construction and fully thread-safe
288
- **Builders** are NOT thread-safe and should not be shared across threads
289
- **ByteString** instances are immutable and thread-safe
290
- **Parsers** are stateless and thread-safe
291
- **Extension registries** should be configured before use and not modified during parsing
292

293
## Types
294

295
```java { .api }
296
// Core message lifecycle interfaces
297
public interface MessageLiteOrBuilder {}
298
public interface MessageOrBuilder extends MessageLiteOrBuilder {
299
    Object getField(Descriptors.FieldDescriptor field);
300
    boolean hasField(Descriptors.FieldDescriptor field);
301
    Descriptors.Descriptor getDescriptorForType();
302
}
303

304
// Builder interfaces
305
public interface MessageLite.Builder extends MessageLiteOrBuilder, Cloneable {
306
    MessageLite build();
307
    MessageLite buildPartial();
308
    MessageLite.Builder clear();
309
    MessageLite.Builder clone();
310
}
311

312
public interface Message.Builder extends MessageLite.Builder, MessageOrBuilder {
313
    Message build();
314
    Message buildPartial();
315
    Message.Builder clear();
316
    Message.Builder clone();
317
}
318

319
// Parsing interface
320
public interface Parser<MessageType extends MessageLite> {
321
    MessageType parseFrom(CodedInputStream input) throws InvalidProtocolBufferException;
322
    MessageType parseFrom(ByteString data) throws InvalidProtocolBufferException;
323
    MessageType parseFrom(byte[] data) throws InvalidProtocolBufferException;
324
}
325

326
// Extension support
327
public abstract class Extension<ContainingType extends MessageLite, Type> 
328
    extends ExtensionLite<ContainingType, Type> {}
329

330
public class ExtensionRegistryLite {
331
    static ExtensionRegistryLite newInstance();
332
    static ExtensionRegistryLite getEmptyRegistry();
333
}
334
```