0
# Protostuff Core
1

2
Protostuff Core is a high-performance Java serialization library that provides efficient Protocol Buffer-compatible serialization for Java objects. It offers both protobuf-compatible format and protostuff's own optimized format, with support for object graphs, cyclic dependencies, and forward/backward compatibility for schema evolution.
3

4
This documentation covers both the core serialization implementations (protostuff-core module) and the foundational APIs they depend on (protostuff-api module).
5

6
## Package Information
7

8
- **Package Name**: protostuff-core
9
- **Package Type**: maven
10
- **Group ID**: io.protostuff
11
- **Language**: Java
12
- **Installation**: Add to your Maven pom.xml:
13
  ```xml
14
  <dependency>
15
    <groupId>io.protostuff</groupId>
16
    <artifactId>protostuff-core</artifactId>
17
    <version>1.8.0</version>
18
  </dependency>
19
  ```
20

21
## Core Imports
22

23
```java
24
// Core serialization utilities (protostuff-core)
25
import io.protostuff.ProtostuffIOUtil;
26
import io.protostuff.ProtobufIOUtil;
27
import io.protostuff.GraphIOUtil;
28

29
// Foundational APIs (protostuff-api, included as dependency)
30
import io.protostuff.Schema;
31
import io.protostuff.LinkedBuffer;
32
import io.protostuff.Input;
33
import io.protostuff.Output;
34
```
35

36
## Basic Usage
37

38
```java
39
import io.protostuff.*;
40

41
// Example message class with schema
42
public class Person {
43
    String name;
44
    int age;
45
    String email;
46
    
47
    // Constructors, getters, setters...
48
}
49

50
// Serialize using Protostuff format
51
LinkedBuffer buffer = LinkedBuffer.allocate(LinkedBuffer.DEFAULT_BUFFER_SIZE);
52
byte[] data = ProtostuffIOUtil.toByteArray(person, schema, buffer);
53

54
// Deserialize using Protostuff format  
55
Person deserializedPerson = schema.newMessage();
56
ProtostuffIOUtil.mergeFrom(data, deserializedPerson, schema);
57

58
// Or use Protocol Buffer format
59
byte[] protobufData = ProtobufIOUtil.toByteArray(person, schema, buffer);
60
Person protobufPerson = schema.newMessage();
61
ProtobufIOUtil.mergeFrom(protobufData, protobufPerson, schema);
62
```
63

64
## Architecture
65

66
Protostuff Core is built around several key components:
67

68
- **Serialization Utilities**: Main entry points (`ProtostuffIOUtil`, `ProtobufIOUtil`, `GraphIOUtil`) providing high-level serialization/deserialization operations
69
- **Input/Output System**: Low-level streaming classes for reading and writing data in various formats
70
- **Buffer Management**: Efficient memory management through linked buffer structures to minimize allocations
71
- **Graph Processing**: Support for object references and cyclic dependencies through specialized graph-aware serializers
72
- **Format Compatibility**: Both native Protostuff format (optimized) and Protocol Buffer format (interoperable) support
73

74
## Capabilities
75

76
### Serialization Utilities
77

78
High-level utilities for common serialization tasks including byte array conversion, stream I/O, and message merging. The primary entry points for most applications.
79

80
```java { .api }
81
// Protostuff format utilities
82
public final class ProtostuffIOUtil {
83
    // Serialization
84
    public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer);
85
    public static <T> int writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
86
    public static <T> int writeDelimitedTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
87
    public static <T> int writeListTo(OutputStream out, List<T> messages, Schema<T> schema, LinkedBuffer buffer);
88
    
89
    // Deserialization
90
    public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema);
91
    public static <T> void mergeFrom(byte[] data, int offset, int length, T message, Schema<T> schema);
92
    public static <T> void mergeFrom(InputStream in, T message, Schema<T> schema);
93
    public static <T> int mergeDelimitedFrom(InputStream in, T message, Schema<T> schema);
94
    public static <T> List<T> parseListFrom(InputStream in, Schema<T> schema);
95
}
96

97
// Protocol Buffer format utilities  
98
public final class ProtobufIOUtil {
99
    public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer);
100
    public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema);
101
    public static <T> int writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
102
}
103
```
104

105
[Serialization Utilities](./serialization-utilities.md)
106

107
### Input and Output Streams
108

109
Low-level streaming interfaces for reading and writing protobuf-encoded data from various sources including byte arrays, ByteBuffers, and InputStreams.
110

111
```java { .api }
112
public abstract class CodedInput {
113
    public abstract int readRawByte() throws IOException;
114
    public abstract String readString() throws IOException;
115
    public abstract int readTag() throws IOException;
116
    public abstract boolean isAtEnd() throws IOException;
117
}
118

119
public final class ProtobufOutput implements Output {
120
    public ProtobufOutput(LinkedBuffer buffer);
121
    public void writeString(int fieldNumber, CharSequence value, boolean repeated) throws IOException;
122
    public void writeInt32(int fieldNumber, int value, boolean repeated) throws IOException;
123
}
124
```
125

126
[Input and Output Streams](./input-output-streams.md)
127

128
### Graph Processing
129

130
Specialized serialization for object graphs containing references and cyclic dependencies, which standard protocol buffers cannot handle natively.
131

132
```java { .api }
133
public final class GraphIOUtil {
134
    // Serialization
135
    public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer);
136
    public static <T> int writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
137
    public static <T> int writeDelimitedTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
138
    
139
    // Deserialization  
140
    public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema);
141
    public static <T> void mergeFrom(byte[] data, int offset, int length, T message, Schema<T> schema);
142
    public static <T> void mergeFrom(InputStream in, T message, Schema<T> schema);
143
    public static <T> int mergeDelimitedFrom(InputStream in, T message, Schema<T> schema);
144
}
145
```
146

147
[Graph Processing](./graph-processing.md)
148

149
### Buffer Management
150

151
Efficient memory management through linked buffer structures that minimize memory allocations and provide reusable buffer pools.
152

153
```java { .api }
154
public final class LinkedBuffer {
155
    public static final int MIN_BUFFER_SIZE = 256;
156
    public static final int DEFAULT_BUFFER_SIZE = 512;
157
    
158
    // Allocation methods
159
    public static LinkedBuffer allocate();
160
    public static LinkedBuffer allocate(int size);
161
    public static LinkedBuffer allocate(int size, LinkedBuffer previous);
162
    public static LinkedBuffer wrap(byte[] array, int offset, int length);
163
    public static LinkedBuffer use(byte[] buffer);
164
    
165
    // Utility methods
166
    public static int writeTo(OutputStream out, LinkedBuffer node) throws IOException;
167
    public LinkedBuffer clear();
168
}
169
```
170

171
[Buffer Management](./buffer-management.md)
172

173
### Advanced Input/Output Classes
174

175
Specialized input and output implementations for different data sources and memory optimization scenarios.
176

177
```java { .api }
178
public final class ByteBufferInput extends CodedInput;
179
public final class ProtostuffOutput implements Output;
180
public final class LowCopyProtostuffOutput implements Output;
181
public final class LowCopyProtobufOutput implements Output;
182
```
183

184
These classes provide optimized implementations for specific use cases like ByteBuffer sources and memory-efficient output operations.
185

186
## Exception Handling
187

188
```java { .api }
189
public class ProtobufException extends ProtostuffException {
190
    public ProtobufException(String description);
191
    public ProtobufException(String description, Throwable cause);
192
}
193
```
194

195
Protostuff Core throws `ProtobufException` for protocol-level errors such as malformed data, invalid tags, or truncated messages. I/O related errors are propagated as standard `IOException`.