0
# Serialization
1

2
Apache Dubbo provides a pluggable serialization framework supporting multiple serialization protocols for efficient data transmission. The serialization system handles object marshalling/unmarshalling between different data formats and provides extensible mechanisms for custom serialization implementations.
3

4
## Capabilities
5

6
### Serialization Interface
7

8
Core serialization abstraction for data marshalling and unmarshalling.
9

10
```java { .api }
11
/**
12
 * Serialization interface for data marshalling
13
 */
14
@SPI("hessian2")
15
public interface Serialization {
16
    /**
17
     * Get content type identifier
18
     * @return Content type ID
19
     */
20
    byte getContentTypeId();
21
    
22
    /**
23
     * Get content type
24
     * @return Content type string
25
     */
26
    String getContentType();
27
    
28
    /**
29
     * Create object output for serialization
30
     * @param url Configuration URL
31
     * @param output Output stream
32
     * @return Object output for writing objects
33
     * @throws IOException if output creation fails
34
     */
35
    ObjectOutput serialize(URL url, OutputStream output) throws IOException;
36
    
37
    /**
38
     * Create object input for deserialization
39
     * @param url Configuration URL
40
     * @param input Input stream
41
     * @return Object input for reading objects
42
     * @throws IOException if input creation fails
43
     */
44
    ObjectInput deserialize(URL url, InputStream input) throws IOException;
45
}
46
```
47

48
### Object Input/Output
49

50
Interfaces for reading and writing serialized objects.
51

52
```java { .api }
53
/**
54
 * Object output interface for writing serialized data
55
 */
56
public interface ObjectOutput extends DataOutput {
57
    /**
58
     * Write object
59
     * @param obj Object to write
60
     * @throws IOException if write fails
61
     */
62
    void writeObject(Object obj) throws IOException;
63
    
64
    /**
65
     * Write UTF string
66
     * @param s String to write
67
     * @throws IOException if write fails
68
     */
69
    void writeUTF(String s) throws IOException;
70
    
71
    /**
72
     * Write byte array
73
     * @param b Byte array
74
     * @throws IOException if write fails
75
     */
76
    void writeBytes(byte[] b) throws IOException;
77
    
78
    /**
79
     * Write byte array with offset and length
80
     * @param b Byte array
81
     * @param off Offset
82
     * @param len Length
83
     * @throws IOException if write fails
84
     */
85
    void writeBytes(byte[] b, int off, int len) throws IOException;
86
    
87
    /**
88
     * Flush output
89
     * @throws IOException if flush fails
90
     */
91
    void flushBuffer() throws IOException;
92
}
93

94
/**
95
 * Object input interface for reading serialized data
96
 */
97
public interface ObjectInput extends DataInput {
98
    /**
99
     * Read object
100
     * @return Deserialized object
101
     * @throws IOException if read fails
102
     * @throws ClassNotFoundException if class not found
103
     */
104
    Object readObject() throws IOException, ClassNotFoundException;
105
    
106
    /**
107
     * Read object with specific class
108
     * @param cls Expected class type
109
     * @return Deserialized object
110
     * @throws IOException if read fails
111
     * @throws ClassNotFoundException if class not found
112
     */
113
    <T> T readObject(Class<T> cls) throws IOException, ClassNotFoundException;
114
    
115
    /**
116
     * Read object with type and class
117
     * @param cls Expected class type
118
     * @param type Generic type
119
     * @return Deserialized object
120
     * @throws IOException if read fails
121
     * @throws ClassNotFoundException if class not found
122
     */
123
    <T> T readObject(Class<T> cls, Type type) throws IOException, ClassNotFoundException;
124
    
125
    /**
126
     * Read UTF string
127
     * @return String value
128
     * @throws IOException if read fails
129
     */
130
    String readUTF() throws IOException;
131
    
132
    /**
133
     * Read byte array
134
     * @return Byte array
135
     * @throws IOException if read fails
136
     */
137
    byte[] readBytes() throws IOException;
138
}
139
```
140

141
### Built-in Serialization Implementations
142

143
Apache Dubbo provides several built-in serialization protocols.
144

145
**Hessian2 Serialization:**
146
```java { .api }
147
/**
148
 * Hessian2 serialization implementation (default)
149
 */
150
public class Hessian2Serialization implements Serialization {
151
    public static final String NAME = "hessian2";
152
    public static final byte ID = 1;
153
    
154
    @Override
155
    public byte getContentTypeId() {
156
        return ID;
157
    }
158
    
159
    @Override
160
    public String getContentType() {
161
        return "x-application/hessian2";
162
    }
163
    
164
    @Override
165
    public ObjectOutput serialize(URL url, OutputStream output) throws IOException {
166
        return new Hessian2ObjectOutput(output);
167
    }
168
    
169
    @Override
170
    public ObjectInput deserialize(URL url, InputStream input) throws IOException {
171
        return new Hessian2ObjectInput(input);
172
    }
173
}
174
```
175

176
**Java Serialization:**
177
```java { .api }
178
/**
179
 * Java native serialization implementation
180
 */
181
public class JavaSerialization implements Serialization {
182
    public static final String NAME = "java";
183
    public static final byte ID = 3;
184
    
185
    @Override
186
    public byte getContentTypeId() {
187
        return ID;
188
    }
189
    
190
    @Override
191
    public String getContentType() {
192
        return "x-application/java";
193
    }
194
}
195
```
196

197
**JSON Serialization:**
198
```java { .api }
199
/**
200
 * JSON serialization implementation
201
 */
202
public class JsonSerialization implements Serialization {
203
    public static final String NAME = "json";
204
    public static final byte ID = 5;
205
    
206
    @Override
207
    public String getContentType() {
208
        return "text/json";
209
    }
210
}
211
```
212

213
**Protobuf Serialization:**
214
```java { .api }
215
/**
216
 * Protocol Buffers serialization implementation
217
 */
218
public class ProtobufSerialization implements Serialization {
219
    public static final String NAME = "protobuf";
220
    public static final byte ID = 21;
221
    
222
    @Override
223
    public String getContentType() {
224
        return "application/x-protobuf";
225
    }
226
}
227
```
228

229
### Serialization Configuration
230

231
Configure serialization for services and references.
232

233
**Service-level Configuration:**
234
```java
235
// Configure serialization for service provider
236
ServiceConfig<GreeterService> service = new ServiceConfig<>();
237
service.setInterface(GreeterService.class);
238
service.setRef(new GreeterServiceImpl());
239
service.setSerialization("hessian2"); // Set serialization protocol
240

241
// Configure serialization for service consumer
242
ReferenceConfig<GreeterService> reference = new ReferenceConfig<>();
243
reference.setInterface(GreeterService.class);
244
reference.setSerialization("protobuf"); // Set serialization protocol
245
```
246

247
**Protocol-level Configuration:**
248
```java
249
// Configure serialization at protocol level
250
ProtocolConfig protocol = new ProtocolConfig();
251
protocol.setName("dubbo");
252
protocol.setPort(20880);
253
protocol.setSerialization("hessian2"); // Default serialization for protocol
254

255
DubboBootstrap.getInstance()
256
    .protocol(protocol)
257
    .start();
258
```
259

260
**URL-based Configuration:**
261
```java
262
// Configure via URL parameters
263
String url = "dubbo://localhost:20880/GreeterService?serialization=protobuf";
264
```
265

266
### Custom Serialization
267

268
Implement custom serialization protocols.
269

270
```java { .api }
271
/**
272
 * Custom serialization implementation example
273
 */
274
public class CustomSerialization implements Serialization {
275
    public static final String NAME = "custom";
276
    public static final byte ID = 100;
277
    
278
    @Override
279
    public byte getContentTypeId() {
280
        return ID;
281
    }
282
    
283
    @Override
284
    public String getContentType() {
285
        return "application/x-custom";
286
    }
287
    
288
    @Override
289
    public ObjectOutput serialize(URL url, OutputStream output) throws IOException {
290
        return new CustomObjectOutput(output);
291
    }
292
    
293
    @Override
294
    public ObjectInput deserialize(URL url, InputStream input) throws IOException {
295
        return new CustomObjectInput(input);
296
    }
297
}
298

299
/**
300
 * Custom object output implementation
301
 */
302
public class CustomObjectOutput implements ObjectOutput {
303
    private final OutputStream output;
304
    
305
    public CustomObjectOutput(OutputStream output) {
306
        this.output = output;
307
    }
308
    
309
    @Override
310
    public void writeObject(Object obj) throws IOException {
311
        // Custom serialization logic
312
        byte[] data = customSerialize(obj);
313
        output.write(data);
314
    }
315
    
316
    private byte[] customSerialize(Object obj) {
317
        // Implement custom serialization algorithm
318
        return new byte[0];
319
    }
320
    
321
    // Implement other DataOutput methods...
322
}
323

324
/**
325
 * Custom object input implementation
326
 */
327
public class CustomObjectInput implements ObjectInput {
328
    private final InputStream input;
329
    
330
    public CustomObjectInput(InputStream input) {
331
        this.input = input;
332
    }
333
    
334
    @Override
335
    public Object readObject() throws IOException, ClassNotFoundException {
336
        // Custom deserialization logic
337
        byte[] data = readBytes();
338
        return customDeserialize(data);
339
    }
340
    
341
    private Object customDeserialize(byte[] data) {
342
        // Implement custom deserialization algorithm
343
        return null;
344
    }
345
    
346
    // Implement other DataInput methods...
347
}
348
```
349

350
**Register Custom Serialization:**
351
```
352
# META-INF/dubbo/org.apache.dubbo.common.serialize.Serialization
353
custom=com.example.CustomSerialization
354
```
355

356
### Serialization Security
357

358
Security considerations and configuration for serialization.
359

360
```java { .api }
361
/**
362
 * Serialization security configuration
363
 */
364
public class SerializationSecurity {
365
    /** Enable serialization security check */
366
    public static final String SERIALIZATION_SECURITY_CHECK = "dubbo.security.serialization.check";
367
    
368
    /** Allowed serialization classes */
369
    public static final String ALLOWED_SERIALIZATION_CLASSES = "dubbo.security.serialization.allowed";
370
    
371
    /** Blocked serialization classes */
372
    public static final String BLOCKED_SERIALIZATION_CLASSES = "dubbo.security.serialization.blocked";
373
}
374
```
375

376
**Security Configuration:**
377
```properties
378
# Enable serialization security
379
dubbo.security.serialization.check=true
380

381
# Allow specific classes
382
dubbo.security.serialization.allowed=com.example.SafeClass,com.example.model.*
383

384
# Block dangerous classes
385
dubbo.security.serialization.blocked=java.lang.Runtime,java.lang.ProcessBuilder
386
```
387

388
### Generic Serialization
389

390
Support for generic object serialization without compiled stubs.
391

392
```java { .api }
393
/**
394
 * Generic serialization for dynamic invocation
395
 */
396
public interface GenericSerialization extends Serialization {
397
    /**
398
     * Serialize generic object
399
     * @param obj Generic object
400
     * @param output Output stream
401
     * @throws IOException if serialization fails
402
     */
403
    void writeGenericObject(Object obj, ObjectOutput output) throws IOException;
404
    
405
    /**
406
     * Deserialize generic object
407
     * @param input Input stream
408
     * @return Generic object
409
     * @throws IOException if deserialization fails
410
     */
411
    Object readGenericObject(ObjectInput input) throws IOException;
412
}
413
```
414

415
### Serialization Optimization
416

417
Performance optimization techniques for serialization.
418

419
**Serialization Optimizers:**
420
```java { .api }
421
/**
422
 * Serialization optimizer interface
423
 */
424
public interface SerializationOptimizer {
425
    /**
426
     * Get serializable classes for optimization
427
     * @return Collection of classes to optimize
428
     */
429
    Collection<Class<?>> getSerializableClasses();
430
}
431

432
/**
433
 * Custom serialization optimizer
434
 */
435
public class MySerializationOptimizer implements SerializationOptimizer {
436
    @Override
437
    public Collection<Class<?>> getSerializableClasses() {
438
        return Arrays.asList(
439
            User.class,
440
            Order.class,
441
            Product.class
442
        );
443
    }
444
}
445
```
446

447
**Configuration:**
448
```properties
449
# Configure serialization optimizer
450
dubbo.protocol.optimizer=com.example.MySerializationOptimizer
451
```
452

453
### Serialization Comparison
454

455
Comparison of different serialization protocols:
456

457
| Protocol | Performance | Size | Cross-Language | Type Safety |
458
|----------|-------------|------|----------------|-------------|
459
| Hessian2 | High | Medium | Yes | Good |
460
| Protobuf | Very High | Small | Yes | Excellent |
461
| Java | Medium | Large | No | Excellent |
462
| JSON | Low | Large | Yes | Poor |
463
| Avro | High | Small | Yes | Good |
464
| Kryo | Very High | Small | No | Good |
465
466
### Usage Examples
467

468
**Basic Serialization Configuration:**
469
```java
470
import org.apache.dubbo.config.ProtocolConfig;
471
import org.apache.dubbo.config.ServiceConfig;
472

473
// Configure Hessian2 serialization (default)
474
ProtocolConfig protocol = new ProtocolConfig();
475
protocol.setName("dubbo");
476
protocol.setSerialization("hessian2");
477

478
// Configure Protobuf for high performance
479
ServiceConfig<OrderService> service = new ServiceConfig<>();
480
service.setInterface(OrderService.class);
481
service.setRef(new OrderServiceImpl());
482
service.setSerialization("protobuf");
483
```
484

485
**Multiple Protocols with Different Serialization:**
486
```java
487
// Protocol 1: Dubbo with Hessian2 (default)
488
ProtocolConfig dubboProtocol = new ProtocolConfig();
489
dubboProtocol.setName("dubbo");
490
dubboProtocol.setPort(20880);
491
dubboProtocol.setSerialization("hessian2");
492

493
// Protocol 2: REST with JSON
494
ProtocolConfig restProtocol = new ProtocolConfig();
495
restProtocol.setName("rest");
496
restProtocol.setPort(8080);
497
restProtocol.setSerialization("json");
498

499
DubboBootstrap.getInstance()
500
    .protocols(Arrays.asList(dubboProtocol, restProtocol))
501
    .start();
502
```
503

504
**Serialization in Properties:**
505
```properties
506
# Global serialization configuration
507
dubbo.protocol.serialization=protobuf
508

509
# Service-specific serialization
510
dubbo.provider.serialization=hessian2
511
dubbo.consumer.serialization=hessian2
512

513
# Protocol-specific serialization
514
dubbo.protocols.dubbo.serialization=hessian2
515
dubbo.protocols.rest.serialization=json
516
```
517

518
**Performance Tuning:**
519
```java
520
// High-performance setup with Protobuf
521
ProtocolConfig protocol = new ProtocolConfig();
522
protocol.setName("dubbo");
523
protocol.setPort(20880);
524
protocol.setSerialization("protobuf");
525
protocol.setOptimizer("com.example.ProtobufOptimizer");
526

527
// Configure buffer sizes for better performance
528
protocol.setBuffer(8192);
529
protocol.setPayload(10485760); // 10MB
530
```