0
# Protocol Code Generation
1
2
Generate Java interfaces and classes from Avro protocol definitions, supporting RPC-style service definitions with message types and error handling.
3
4
## Capabilities
5
6
### SpecificCompiler Protocol Support
7
8
The SpecificCompiler class supports protocol compilation in addition to schema compilation.
9
10
```java { .api }
11
/**
12
* Create compiler from Protocol
13
* @param protocol Avro protocol definition
14
*/
15
public SpecificCompiler(Protocol protocol);
16
```
17
18
### Static Protocol Compilation Methods
19
20
Convenience methods for compiling protocol files directly.
21
22
```java { .api }
23
/**
24
* Compile single protocol file to Java interfaces and classes
25
* @param src Source protocol file (.avpr)
26
* @param dest Destination directory for generated code
27
* @throws IOException if compilation fails
28
*/
29
public static void compileProtocol(File src, File dest) throws IOException;
30
31
/**
32
* Compile multiple protocol files to Java interfaces and classes
33
* @param srcFiles Array of source protocol files
34
* @param dest Destination directory for generated code
35
* @throws IOException if compilation fails
36
*/
37
public static void compileProtocol(File[] srcFiles, File dest) throws IOException;
38
```
39
40
### Protocol Compilation Process
41
42
When compiling protocols, the compiler generates:
43
44
1. **Service Interface**: Java interface representing the protocol's messages
45
2. **Message Classes**: Java classes for request/response message types
46
3. **Error Classes**: Java classes for protocol-defined error types
47
4. **Callback Interface**: Asynchronous callback interface for non-blocking RPC
48
49
All protocol compilation uses the same configuration options as schema compilation (field visibility, setters, optional getters, etc.).
50
51
## Usage Examples
52
53
### Basic Protocol Compilation
54
55
```java
56
import org.apache.avro.Protocol;
57
import org.apache.avro.compiler.specific.SpecificCompiler;
58
import java.io.File;
59
60
// Parse and compile a protocol
61
Protocol.Parser parser = new Protocol.Parser();
62
Protocol protocol = parser.parse(new File("email-service.avpr"));
63
64
SpecificCompiler compiler = new SpecificCompiler(protocol);
65
compiler.compileToDestination(new File("email-service.avpr"), new File("src/main/java"));
66
```
67
68
### Static Protocol Compilation
69
70
```java
71
import org.apache.avro.compiler.specific.SpecificCompiler;
72
import java.io.File;
73
74
// Direct protocol compilation
75
SpecificCompiler.compileProtocol(
76
new File("email-service.avpr"),
77
new File("src/main/java")
78
);
79
```
80
81
### Multiple Protocol Compilation
82
83
```java
84
import org.apache.avro.compiler.specific.SpecificCompiler;
85
import java.io.File;
86
87
// Compile multiple protocols
88
File[] protocolFiles = {
89
new File("user-service.avpr"),
90
new File("order-service.avpr"),
91
new File("inventory-service.avpr")
92
};
93
94
SpecificCompiler.compileProtocol(protocolFiles, new File("src/main/java"));
95
```
96
97
### Configured Protocol Compilation
98
99
```java
100
import org.apache.avro.Protocol;
101
import org.apache.avro.compiler.specific.SpecificCompiler;
102
import org.apache.avro.compiler.specific.SpecificCompiler.FieldVisibility;
103
104
Protocol protocol = new Protocol.Parser().parse(new File("service.avpr"));
105
SpecificCompiler compiler = new SpecificCompiler(protocol);
106
107
// Configure the same options as schema compilation
108
compiler.setFieldVisibility(FieldVisibility.PRIVATE);
109
compiler.setCreateSetters(true);
110
compiler.setCreateOptionalGetters(true);
111
112
compiler.compileToDestination(new File("service.avpr"), new File("src/main/java"));
113
```
114
115
### Example Protocol Definition
116
117
A typical Avro protocol file (.avpr) might look like:
118
119
```json
120
{
121
"protocol": "EmailService",
122
"namespace": "com.example.email",
123
"types": [
124
{
125
"name": "EmailMessage",
126
"type": "record",
127
"fields": [
128
{"name": "to", "type": "string"},
129
{"name": "from", "type": "string"},
130
{"name": "subject", "type": "string"},
131
{"name": "body", "type": "string"}
132
]
133
},
134
{
135
"name": "SendResult",
136
"type": "record",
137
"fields": [
138
{"name": "messageId", "type": "string"},
139
{"name": "success", "type": "boolean"}
140
]
141
}
142
],
143
"messages": {
144
"sendEmail": {
145
"request": [{"name": "message", "type": "EmailMessage"}],
146
"response": "SendResult",
147
"errors": ["string"]
148
}
149
}
150
}
151
```
152
153
This generates:
154
- `EmailService` interface with `sendEmail` method
155
- `EmailMessage` record class
156
- `SendResult` record class
157
- `EmailServiceCallback` interface for async operations
158
159
### Generated Code Structure
160
161
For the protocol above, the compiler generates:
162
163
```java
164
// Service interface
165
public interface EmailService {
166
SendResult sendEmail(EmailMessage message) throws org.apache.avro.AvroRemoteException;
167
}
168
169
// Callback interface
170
public interface EmailServiceCallback {
171
void sendEmail(EmailMessage message,
172
org.apache.avro.ipc.Callback<SendResult> callback);
173
}
174
175
// Record classes (EmailMessage, SendResult) with configured options
176
```
177
178
## Integration with RPC
179
180
Generated protocol classes integrate with Avro's RPC system:
181
182
```java
183
// Server-side implementation
184
public class EmailServiceImpl implements EmailService {
185
@Override
186
public SendResult sendEmail(EmailMessage message) throws AvroRemoteException {
187
// Implementation logic
188
return SendResult.newBuilder()
189
.setMessageId(UUID.randomUUID().toString())
190
.setSuccess(true)
191
.build();
192
}
193
}
194
195
// Client-side usage (with Avro RPC framework)
196
// EmailService client = SpecificRequestor.getClient(EmailService.class, transceiver);
197
// SendResult result = client.sendEmail(emailMessage);
198
```