0
# Transport Mechanisms
1

2
Apache Avro IPC provides multiple transport implementations to support different networking requirements, from simple HTTP communication to secure socket connections and in-process communication.
3

4
## Capabilities
5

6
### HTTP Transport
7

8
HTTP-based transport using standard HTTP POST requests with binary Avro data. Suitable for web environments and when working through firewalls and proxies.
9

10
#### HTTP Client Transport
11

12
```java { .api }
13
public class HttpTransceiver extends Transceiver {
14
    public static final String CONTENT_TYPE = "avro/binary";
15
    
16
    // Constructors
17
    public HttpTransceiver(URL url) throws IOException;
18
    public HttpTransceiver(URL url, Proxy proxy) throws IOException;
19
    
20
    // Configuration
21
    public void setTimeout(int timeout);
22
    
23
    // Inherited from Transceiver
24
    public String getRemoteName() throws IOException;
25
    public List<ByteBuffer> readBuffers() throws IOException;
26
    public void writeBuffers(List<ByteBuffer> buffers) throws IOException;
27
    public void close() throws IOException;
28
    
29
    // Static utility methods
30
    public static int getLength(List<ByteBuffer> buffers);
31
    public static List<ByteBuffer> readBuffers(InputStream in) throws IOException;
32
    public static void writeBuffers(List<ByteBuffer> buffers, OutputStream out) throws IOException;
33
}
34
```
35

36
#### HTTP Server Transport
37

38
```java { .api }
39
public class ResponderServlet extends HttpServlet {
40
    // Constructor
41
    public ResponderServlet(Responder responder);
42
    
43
    // HTTP handling
44
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
45
        throws ServletException, IOException;
46
}
47
```
48

49
#### Usage Examples
50

51
```java
52
// HTTP client setup
53
URL serverUrl = new URL("http://localhost:8080/rpc");
54
HttpTransceiver transceiver = new HttpTransceiver(serverUrl);
55
transceiver.setTimeout(30000); // 30 second timeout
56

57
// With proxy
58
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.company.com", 8080));
59
HttpTransceiver transceiver = new HttpTransceiver(serverUrl, proxy);
60

61
// HTTP server setup (servlet deployment)
62
MyServiceImpl implementation = new MyServiceImpl();  
63
SpecificResponder responder = new SpecificResponder(MyService.class, implementation);
64
ResponderServlet servlet = new ResponderServlet(responder);
65

66
// Deploy to servlet container (example with Jetty)
67
ServletContextHandler context = new ServletContextHandler();
68
context.addServlet(new ServletHolder(servlet), "/rpc");
69
```
70

71
### Socket Transport
72

73
Socket-based transport implementations providing persistent connections with optional SASL authentication and encryption.
74

75
#### SASL Socket Client Transport
76

77
```java { .api }
78
public class SaslSocketTransceiver extends Transceiver {
79
    // Constructors
80
    public SaslSocketTransceiver(SocketAddress address) throws IOException; // Anonymous SASL
81
    public SaslSocketTransceiver(SocketAddress address, SaslClient saslClient) throws IOException;
82
    public SaslSocketTransceiver(SocketChannel channel, SaslServer saslServer) throws IOException;
83
    
84
    // Inherited from Transceiver
85
    public String getRemoteName() throws IOException;
86
    public List<ByteBuffer> readBuffers() throws IOException;
87
    public void writeBuffers(List<ByteBuffer> buffers) throws IOException;
88
    public boolean isConnected();
89
    public void close() throws IOException;
90
}
91
```
92

93
#### Legacy Socket Client Transport (Deprecated)
94

95
```java { .api }
96
@Deprecated
97
public class SocketTransceiver extends Transceiver {
98
    // Constructors  
99
    public SocketTransceiver(SocketAddress address) throws IOException;
100
    public SocketTransceiver(SocketChannel channel) throws IOException;
101
    
102
    // Inherited from Transceiver
103
    public String getRemoteName() throws IOException;
104
    public List<ByteBuffer> readBuffers() throws IOException;
105
    public void writeBuffers(List<ByteBuffer> buffers) throws IOException;
106
    public boolean isConnected();
107
    public void close() throws IOException;
108
}
109
```
110

111
#### SASL Socket Server
112

113
```java { .api }
114
public class SaslSocketServer extends SocketServer {
115
    // Constructors
116
    public SaslSocketServer(Responder responder, SocketAddress addr) throws IOException; // Anonymous SASL
117
    public SaslSocketServer(Responder responder, SocketAddress addr, String mechanism, 
118
        String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) throws IOException;
119
    
120
    // Inherited from SocketServer and Server interface
121
    public int getPort();
122
    public void start();
123
    public void close();
124
    public void join() throws InterruptedException;
125
    public void run(); // From Thread
126
}
127
```
128

129
#### Legacy Socket Server (Deprecated)
130

131
```java { .api }
132
@Deprecated
133
public class SocketServer extends Thread implements Server {
134
    // Constructor
135
    public SocketServer(Responder responder, SocketAddress addr) throws IOException;
136
    
137
    // Server interface
138
    public int getPort();
139
    public void start();
140
    public void close();
141
    public void join() throws InterruptedException;
142
    
143
    // Thread methods
144
    public void run();
145
    
146
    // Protected methods for customization
147
    protected Transceiver getTransceiver(SocketChannel channel) throws IOException;
148
}
149
```
150

151
#### Usage Examples
152

153
```java
154
// SASL Socket client (Anonymous authentication)
155
InetSocketAddress serverAddress = new InetSocketAddress("localhost", 65001);
156
SaslSocketTransceiver transceiver = new SaslSocketTransceiver(serverAddress);
157

158
// SASL Socket client with custom authentication
159
Map<String, String> props = new HashMap<>();
160
props.put(Sasl.QOP, "auth-conf"); // Authentication and confidentiality
161
SaslClient saslClient = Sasl.createSaslClient(
162
    new String[]{"DIGEST-MD5"}, "client", "avro", "server.example.com", props, 
163
    new MyCallbackHandler());
164
SaslSocketTransceiver transceiver = new SaslSocketTransceiver(serverAddress, saslClient);
165

166
// SASL Socket server
167
SpecificResponder responder = new SpecificResponder(MyService.class, implementation);
168
SaslSocketServer server = new SaslSocketServer(responder, 
169
    new InetSocketAddress(65001));
170
server.start();
171

172
// SASL Socket server with custom authentication
173
SaslSocketServer server = new SaslSocketServer(responder, 
174
    new InetSocketAddress(65001), "DIGEST-MD5", "avro", "server.example.com", 
175
    props, new MyServerCallbackHandler());
176
server.start();
177
```
178

179
### Datagram Transport
180

181
UDP datagram-based transport for connectionless communication. Note that this uses a non-standard wire protocol.
182

183
#### Datagram Client Transport
184

185
```java { .api }
186
public class DatagramTransceiver extends Transceiver {
187
    // Constructors
188
    public DatagramTransceiver(SocketAddress remote) throws IOException;
189
    public DatagramTransceiver(DatagramChannel channel) throws IOException;
190
    
191
    // Inherited from Transceiver
192
    public String getRemoteName() throws IOException;
193
    public List<ByteBuffer> readBuffers() throws IOException;
194
    public void writeBuffers(List<ByteBuffer> buffers) throws IOException;
195
    public void close() throws IOException;
196
}
197
```
198

199
#### Datagram Server
200

201
```java { .api }
202
public class DatagramServer extends Thread implements Server {
203
    // Constructor
204
    public DatagramServer(Responder responder, SocketAddress addr) throws IOException;
205
    
206
    // Server interface
207
    public int getPort();
208
    public void start();
209
    public void close();
210
    public void join() throws InterruptedException;
211
    
212
    // Thread methods
213
    public void run();
214
}
215
```
216

217
#### Usage Examples
218

219
```java
220
// Datagram client
221
DatagramTransceiver transceiver = new DatagramTransceiver(
222
    new InetSocketAddress("localhost", 65002));
223

224
// Datagram server
225
GenericResponder responder = new MyGenericResponder(protocol);
226
DatagramServer server = new DatagramServer(responder, 
227
    new InetSocketAddress(65002));
228
server.start();
229
```
230

231
### Local Transport
232

233
In-process transport for same-JVM communication, eliminating network overhead.
234

235
#### Local Transceiver
236

237
```java { .api }
238
public class LocalTransceiver extends Transceiver {
239
    // Constructor
240
    public LocalTransceiver(Responder responder);
241
    
242
    // Inherited from Transceiver
243
    public String getRemoteName();
244
    public List<ByteBuffer> readBuffers() throws IOException;
245
    public void writeBuffers(List<ByteBuffer> buffers) throws IOException;
246
    public void close() throws IOException;
247
}
248
```
249

250
#### Usage Examples
251

252
```java
253
// Local in-process communication
254
MyServiceImpl implementation = new MyServiceImpl();
255
SpecificResponder responder = new SpecificResponder(MyService.class, implementation);
256
LocalTransceiver transceiver = new LocalTransceiver(responder);
257

258
// Use with any requestor
259
SpecificRequestor requestor = new SpecificRequestor(MyService.class, transceiver);
260
MyService client = SpecificRequestor.getClient(MyService.class, transceiver);
261
```
262

263
## Factory Utilities
264

265
### URI-Based Transport Creation
266

267
```java { .api }
268
public class Ipc {
269
    // Factory methods
270
    public static Transceiver createTransceiver(URI uri) throws IOException;
271
    public static Server createServer(Responder responder, URI uri) throws IOException;
272
}
273
```
274

275
#### Usage Examples
276

277
```java
278
// Create transceiver from URI
279
Transceiver transceiver = Ipc.createTransceiver(URI.create("http://localhost:8080/rpc"));
280
Transceiver transceiver = Ipc.createTransceiver(URI.create("sasl://localhost:65001"));
281

282
// Create server from URI  
283
Server server = Ipc.createServer(responder, URI.create("sasl://localhost:65001"));
284
server.start();
285
```
286

287
## Transport Selection Guidelines
288

289
### HTTP Transport
290
- **Use when**: Web environments, through firewalls, with load balancers
291
- **Pros**: Firewall-friendly, standard protocol, proxy support
292
- **Cons**: Higher overhead, stateless (connection per request)
293
- **Authentication**: Use HTTPS with client certificates or application-level auth
294

295
### SASL Socket Transport  
296
- **Use when**: Direct network access, need persistent connections, authentication required
297
- **Pros**: Persistent connections, SASL authentication, encryption support
298
- **Cons**: Firewall complexity, connection management needed
299
- **Authentication**: Built-in SASL mechanisms (Anonymous, DIGEST-MD5, GSSAPI, etc.)
300

301
### Datagram Transport
302
- **Use when**: Low latency required, can tolerate message loss, simple request/response
303
- **Pros**: Low latency, connectionless
304
- **Cons**: Non-standard wire protocol, message size limits, no reliability guarantees
305

306
### Local Transport
307
- **Use when**: Same JVM communication, testing, microservice within same process
308
- **Pros**: Zero network overhead, same-JVM optimizations
309
- **Cons**: Limited to same JVM
310

311
## Advanced Configuration
312

313
### Connection Pooling
314

315
HTTP transport supports connection pooling through the underlying HTTP client:
316

317
```java
318
// System properties for HTTP client configuration
319
System.setProperty("http.maxConnections", "10");
320
System.setProperty("http.keepAlive", "true");
321
```
322

323
### SSL/TLS Configuration
324

325
For HTTPS transport:
326

327
```java
328
// Configure SSL context
329
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore");  
330
System.setProperty("javax.net.ssl.trustStorePassword", "password");
331

332
URL httpsUrl = new URL("https://secure.example.com:8443/rpc");
333
HttpTransceiver transceiver = new HttpTransceiver(httpsUrl);
334
```
335

336
### Custom Socket Configuration
337

338
For socket transports, configure socket options:
339

340
```java
341
// Example custom socket server
342
public class CustomSocketServer extends SaslSocketServer {
343
    @Override
344
    protected Transceiver getTransceiver(SocketChannel channel) throws IOException {
345
        // Configure socket options
346
        channel.socket().setTcpNoDelay(true);
347
        channel.socket().setReceiveBufferSize(65536);
348
        channel.socket().setSendBufferSize(65536);
349
        return super.getTransceiver(channel);
350
    }
351
}
352
```
353

354
## Error Handling
355

356
Transport-level errors are typically IOException or its subclasses:
357

358
```java
359
try {
360
    Object result = requestor.request("method", request);
361
} catch (ConnectException e) {
362
    // Server not available
363
    System.err.println("Cannot connect to server: " + e.getMessage());
364
} catch (SocketTimeoutException e) {
365
    // Request timeout
366
    System.err.println("Request timed out: " + e.getMessage());
367
} catch (IOException e) {
368
    // General network error
369
    System.err.println("Network error: " + e.getMessage());
370
}
371
```