0
# Akka Protobuf V3
1
2
Akka Protobuf V3 is a shaded version of the Google protobuf runtime library that renames `com.google.protobuf.**` to `akka.protobufv3.internal.**` to avoid conflicts with other protobuf versions used in applications. This is an internal utility library used by other Akka modules that require protobuf serialization.
3
4
## Package Information
5
6
- **Package Name**: akka-protobuf-v3_2.13
7
- **Package Type**: Maven
8
- **Language**: Java (compatible with Scala)
9
- **Group ID**: com.typesafe.akka
10
- **Artifact ID**: akka-protobuf-v3_2.13
11
- **Version**: 2.8.8
12
- **Installation**: Add dependency to your build configuration (SBT, Maven, Gradle)
13
14
## Core Imports
15
16
All classes are in the `akka.protobufv3.internal` package namespace (shaded from `com.google.protobuf`).
17
18
```java
19
import akka.protobufv3.internal.Message;
20
import akka.protobufv3.internal.ByteString;
21
import akka.protobufv3.internal.CodedInputStream;
22
import akka.protobufv3.internal.CodedOutputStream;
23
```
24
25
For Scala projects:
26
27
```scala
28
import akka.protobufv3.internal.{Message, ByteString, CodedInputStream, CodedOutputStream}
29
```
30
31
## Basic Usage
32
33
```java
34
import akka.protobufv3.internal.*;
35
36
// Create a ByteString from UTF-8 text
37
ByteString data = ByteString.copyFromUtf8("Hello, Protocol Buffers!");
38
39
// Convert back to string
40
String text = data.toStringUtf8();
41
42
// Serialize ByteString to byte array
43
byte[] bytes = data.toByteArray();
44
45
// Create ByteString from byte array
46
ByteString restored = ByteString.copyFrom(bytes);
47
48
// Parse a message from bytes (example with a hypothetical UserMessage)
49
// UserMessage message = UserMessage.parseFrom(bytes);
50
```
51
52
## Architecture
53
54
Akka Protobuf V3 provides the complete Protocol Buffers Java runtime with several key components:
55
56
- **Message System**: Core interfaces and classes for protocol buffer messages (`Message`, `MessageLite`, builders)
57
- **Serialization**: Binary I/O operations (`CodedInputStream`, `CodedOutputStream`, `ByteString`)
58
- **Reflection API**: Runtime descriptors for dynamic message handling (`Descriptors.*`)
59
- **Well-Known Types**: Standard protobuf types like `Timestamp`, `Duration`, `Any`, wrapper types
60
- **JSON Support**: JSON format conversion utilities (`JsonFormat`)
61
- **Extension System**: Support for protobuf extensions (`ExtensionRegistry`)
62
- **Text Format**: Human-readable text representation (`TextFormat`)
63
64
All functionality is identical to the original Google protobuf-java 3.16.3 library, but with package names changed from `com.google.protobuf.**` to `akka.protobufv3.internal.**` to avoid version conflicts in the Akka ecosystem.
65
66
## Capabilities
67
68
### Core Message API
69
70
Core interfaces and abstract classes for protocol buffer messages, builders, and parsing. Provides the foundation for all protobuf message operations.
71
72
```java { .api }
73
interface Message extends MessageLite, MessageOrBuilder {
74
// Core message interface with full functionality
75
}
76
77
interface MessageLite {
78
// Lite message interface with minimal functionality
79
}
80
81
abstract class AbstractMessage implements Message {
82
// Partial implementation of Message interface
83
}
84
85
abstract class GeneratedMessageV3 extends AbstractMessage {
86
// Base class for generated protocol buffer messages
87
}
88
```
89
90
[Core Message API](./core-message-api.md)
91
92
### Serialization and I/O
93
94
Binary serialization, deserialization, and I/O operations for protocol buffer messages. Includes ByteString utilities and coded streams.
95
96
```java { .api }
97
class ByteString {
98
static ByteString copyFrom(byte[] bytes);
99
static ByteString copyFromUtf8(String text);
100
byte[] toByteArray();
101
String toStringUtf8();
102
ByteString substring(int beginIndex);
103
ByteString concat(ByteString other);
104
}
105
106
class CodedInputStream {
107
static CodedInputStream newInstance(byte[] buf);
108
static CodedInputStream newInstance(InputStream input);
109
// Read methods for various protobuf types
110
}
111
112
class CodedOutputStream {
113
static CodedOutputStream newInstance(byte[] flatArray);
114
static CodedOutputStream newInstance(OutputStream output);
115
// Write methods for various protobuf types
116
}
117
```
118
119
[Serialization and I/O](./serialization-io.md)
120
121
### Descriptors and Reflection
122
123
Runtime reflection API for dynamically working with protocol buffer message types, fields, and schemas without generated code.
124
125
```java { .api }
126
class Descriptors {
127
static class Descriptor {
128
// Describes a message type
129
String getName();
130
String getFullName();
131
List<FieldDescriptor> getFields();
132
}
133
134
static class FieldDescriptor {
135
// Describes a field in a message
136
String getName();
137
FieldType getType();
138
boolean isRepeated();
139
}
140
141
static class FileDescriptor {
142
// Describes a .proto file
143
String getName();
144
List<Descriptor> getMessageTypes();
145
}
146
}
147
148
class DynamicMessage implements Message {
149
// Can represent arbitrary message types given a Descriptor
150
static DynamicMessage newBuilder(Descriptor type);
151
}
152
```
153
154
[Descriptors and Reflection](./descriptors-reflection.md)
155
156
### Well-Known Types
157
158
Standard protocol buffer types including timestamps, durations, Any messages, and wrapper types for primitives.
159
160
```java { .api }
161
class Timestamp implements Message {
162
// Represents a point in time
163
long getSeconds();
164
int getNanos();
165
static Builder newBuilder();
166
}
167
168
class Duration implements Message {
169
// Represents a span of time
170
long getSeconds();
171
int getNanos();
172
static Builder newBuilder();
173
}
174
175
class Any implements Message {
176
// Contains an arbitrary serialized message
177
String getTypeUrl();
178
ByteString getValue();
179
static Builder newBuilder();
180
}
181
```
182
183
[Well-Known Types](./well-known-types.md)
184
185
### JSON Format Support
186
187
Utilities for converting protocol buffer messages to and from JSON format, with configurable options and type registry support.
188
189
```java { .api }
190
class JsonFormat {
191
static class Parser {
192
// Parse JSON to protobuf message
193
Parser ignoringUnknownFields();
194
Parser usingTypeRegistry(TypeRegistry registry);
195
void merge(String json, Message.Builder builder);
196
}
197
198
static class Printer {
199
// Convert protobuf message to JSON
200
Printer includingDefaultValueFields();
201
Printer preservingProtoFieldNames();
202
String print(MessageOrBuilder message);
203
}
204
205
static Parser parser();
206
static Printer printer();
207
}
208
```
209
210
[JSON Format Support](./json-format.md)
211
212
### Text Format Support
213
214
Human-readable text representation of protocol buffer messages for debugging, logging, and configuration files.
215
216
```java { .api }
217
class TextFormat {
218
// Utilities for converting messages to/from text format
219
static String printToString(MessageOrBuilder message);
220
static void merge(Readable input, Message.Builder builder) throws IOException;
221
static Printer printer();
222
static Parser parser();
223
}
224
225
class TextFormatParseException extends IOException {
226
// Exception thrown when text format parsing fails
227
String getMessage();
228
int getLine();
229
int getColumn();
230
}
231
```
232
233
### Extension System
234
235
Support for protocol buffer extensions allowing fields to be added to messages without modifying the original .proto files.
236
237
```java { .api }
238
class Extension<ContainingType, Type> {
239
// Represents a protocol buffer extension
240
}
241
242
class ExtensionRegistry {
243
// Registry for protocol buffer extensions
244
static ExtensionRegistry newInstance();
245
void add(Extension<?, ?> extension);
246
ExtensionRegistry getUnmodifiable();
247
}
248
249
class ExtensionRegistryLite {
250
// Lite version of extension registry
251
static ExtensionRegistryLite newInstance();
252
}
253
```
254
255
[Extension System](./extensions.md)
256
257
### Error Handling
258
259
Exception types and error handling mechanisms for protocol buffer operations.
260
261
```java { .api }
262
class InvalidProtocolBufferException extends IOException {
263
// Exception thrown when parsing invalid protocol buffer data
264
static InvalidProtocolBufferException truncatedMessage();
265
static InvalidProtocolBufferException negativeSize();
266
static InvalidProtocolBufferException malformedVarint();
267
static InvalidProtocolBufferException invalidTag();
268
static InvalidProtocolBufferException invalidEndTag();
269
static InvalidProtocolBufferException invalidWireType();
270
static InvalidProtocolBufferException recursionLimitExceeded();
271
static InvalidProtocolBufferException sizeLimitExceeded();
272
}
273
274
class UnknownFieldSet implements MessageLite {
275
// Container for fields that were parsed but not recognized
276
static UnknownFieldSet getDefaultInstance();
277
static Builder newBuilder();
278
Map<Integer, Field> asMap();
279
boolean hasField(int number);
280
Field getField(int number);
281
}
282
```