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
```