0
# RPC Core
1

2
The RPC core system provides the foundation abstractions for remote procedure calls in Apache Dubbo, including service invocation, proxy creation, filtering, and context management.
3

4
## Capabilities
5

6
### Service Invoker
7

8
The `Invoker` interface represents a callable service endpoint and provides the core abstraction for RPC invocation.
9

10
```java { .api }
11
/**
12
 * Service invoker representing a callable service endpoint
13
 * @param <T> Service interface type
14
 */
15
public interface Invoker<T> {
16
    /** 
17
     * Invoke a service method
18
     * @param invocation RPC invocation context
19
     * @return Result of the invocation
20
     * @throws RpcException if invocation fails
21
     */
22
    Result invoke(Invocation invocation) throws RpcException;
23
    
24
    /** Get the service interface class */
25
    Class<T> getInterface();
26
    
27
    /** Get the service URL configuration */
28
    URL getUrl();
29
    
30
    /** Check if the invoker is available for invocation */
31
    boolean isAvailable();
32
    
33
    /** Destroy the invoker and release resources */
34
    void destroy();
35
}
36
```
37

38
**Usage Examples:**
39

40
```java
41
import org.apache.dubbo.rpc.Invoker;
42
import org.apache.dubbo.rpc.RpcInvocation;
43

44
// Create invocation
45
RpcInvocation invocation = new RpcInvocation();
46
invocation.setMethodName("sayHello");
47
invocation.setParameterTypes(new Class<?>[]{String.class});
48
invocation.setArguments(new Object[]{"World"});
49

50
// Invoke service
51
Result result = invoker.invoke(invocation);
52
String response = (String) result.getValue();
53
```
54

55
### RPC Invocation
56

57
Represents an RPC invocation with method information, parameters, and attachments.
58

59
```java { .api }
60
/**
61
 * RPC invocation context containing method information and parameters
62
 */
63
public interface Invocation {
64
    /** Get target service unique name */
65
    String getTargetServiceUniqueName();
66
    
67
    /** Get method name being invoked */
68
    String getMethodName();
69
    
70
    /** Get service name */
71
    String getServiceName();
72
    
73
    /** Get parameter types of the method */
74
    Class<?>[] getParameterTypes();
75
    
76
    /** Get method arguments */
77
    Object[] getArguments();
78
    
79
    /** Get all attachments */
80
    Map<String, String> getAttachments();
81
    
82
    /** Get attachment value by key */
83
    String getAttachment(String key);
84
    
85
    /** Get attachment value with default */
86
    String getAttachment(String key, String defaultValue);
87
}
88

89
/**
90
 * Concrete RPC invocation implementation
91
 */
92
public class RpcInvocation implements Invocation {
93
    public RpcInvocation();
94
    public RpcInvocation(String methodName, Class<?>[] parameterTypes, Object[] arguments);
95
    public void setMethodName(String methodName);
96
    public void setParameterTypes(Class<?>[] parameterTypes);
97
    public void setArguments(Object[] arguments);
98
    public void setAttachment(String key, String value);
99
    public void setAttachments(Map<String, String> attachments);
100
}
101
```
102

103
### RPC Result
104

105
Container for RPC invocation results and exceptions.
106

107
```java { .api }
108
/**
109
 * RPC invocation result container
110
 */
111
public interface Result {
112
    /** Get the return value */
113
    Object getValue();
114
    
115
    /** Set the return value */
116
    void setValue(Object value);
117
    
118
    /** Get exception if invocation failed */
119
    Throwable getException();
120
    
121
    /** Set exception for failed invocation */
122
    void setException(Throwable t);
123
    
124
    /** Check if result contains exception */
125
    boolean hasException();
126
    
127
    /** Get result attachments */
128
    Map<String, String> getAttachments();
129
    
130
    /** Get attachment by key */
131
    String getAttachment(String key);
132
    
133
    /** Add attachment to result */
134
    void setAttachment(String key, String value);
135
}
136

137
/**
138
 * Asynchronous RPC result
139
 */
140
public class AsyncRpcResult implements Result {
141
    public AsyncRpcResult(CompletableFuture<Object> future);
142
    public CompletableFuture<Object> getFuture();
143
    public boolean isDone();
144
}
145
```
146

147
### RPC Context
148

149
Thread-local context for RPC invocations containing attachments and metadata.
150

151
```java { .api }
152
/**
153
 * Thread-local RPC context for storing invocation metadata
154
 */
155
public class RpcContext {
156
    /** Get current thread's RPC context */
157
    public static RpcContext getContext();
158
    
159
    /** Get server-side context */
160
    public static RpcContext getServerContext();
161
    
162
    /** Check if current side is provider */
163
    public boolean isProviderSide();
164
    
165
    /** Check if current side is consumer */
166
    public boolean isConsumerSide();
167
    
168
    /** Set attachment value */
169
    public RpcContext setAttachment(String key, String value);
170
    
171
    /** Get attachment value */
172
    public String getAttachment(String key);
173
    
174
    /** Remove attachment */
175
    public String removeAttachment(String key);
176
    
177
    /** Get all attachments */
178
    public Map<String, String> getAttachments();
179
    
180
    /** Set request attachments */
181
    public void setAttachments(Map<String, String> attachments);
182
    
183
    /** Get remote address */
184
    public InetSocketAddress getRemoteAddress();
185
    
186
    /** Get local address */
187
    public InetSocketAddress getLocalAddress();
188
    
189
    /** Get remote application name */
190
    public String getRemoteApplicationName();
191
    
192
    /** Get local application name */
193
    public String getLocalApplicationName();
194
}
195
```
196

197
**Usage Examples:**
198

199
```java
200
import org.apache.dubbo.rpc.RpcContext;
201

202
// Set attachment on consumer side
203
RpcContext.getContext().setAttachment("userId", "12345");
204
String result = greeterService.sayHello("World");
205

206
// Get attachment on provider side
207
@DubboService
208
public class GreeterServiceImpl implements GreeterService {
209
    public String sayHello(String name) {
210
        String userId = RpcContext.getContext().getAttachment("userId");
211
        return "Hello " + name + ", user: " + userId;
212
    }
213
}
214
```
215

216
### Generic Service
217

218
Interface for generic service invocation without compiled stubs.
219

220
```java { .api }
221
/**
222
 * Generic service interface for runtime service invocation
223
 */
224
public interface GenericService {
225
    /**
226
     * Generic synchronous invocation
227
     * @param method Method name to invoke
228
     * @param parameterTypes Parameter type names
229
     * @param args Method arguments
230
     * @return Method result
231
     * @throws GenericException if invocation fails
232
     */
233
    Object $invoke(String method, String[] parameterTypes, Object[] args) 
234
        throws GenericException;
235
    
236
    /**
237
     * Generic asynchronous invocation
238
     * @param method Method name to invoke
239
     * @param parameterTypes Parameter type names
240
     * @param args Method arguments
241
     * @return CompletableFuture containing the result
242
     */
243
    CompletableFuture<Object> $invokeAsync(String method, String[] parameterTypes, Object[] args);
244
}
245

246
/**
247
 * Exception for generic service invocations
248
 */
249
public class GenericException extends RuntimeException {
250
    public GenericException(String message);
251
    public GenericException(String message, Throwable cause);
252
    public GenericException(Throwable cause);
253
}
254
```
255

256
**Usage Examples:**
257

258
```java
259
import org.apache.dubbo.rpc.service.GenericService;
260

261
// Configure generic reference
262
ReferenceConfig<GenericService> reference = new ReferenceConfig<>();
263
reference.setInterface("com.example.GreeterService");
264
reference.setGeneric(true);
265

266
GenericService genericService = reference.get();
267

268
// Generic invocation
269
Object result = genericService.$invoke(
270
    "sayHello", 
271
    new String[]{"java.lang.String"}, 
272
    new Object[]{"World"}
273
);
274
```
275

276
### Service Proxy Factory
277

278
Interface for creating service proxies and invokers.
279

280
```java { .api }
281
/**
282
 * Factory for creating service proxies and invokers
283
 */
284
@SPI("javassist")
285
public interface ProxyFactory {
286
    /**
287
     * Create proxy for consumer side
288
     * @param invoker Service invoker
289
     * @return Service proxy
290
     * @throws RpcException if proxy creation fails
291
     */
292
    <T> T getProxy(Invoker<T> invoker) throws RpcException;
293
    
294
    /**
295
     * Create proxy with specific class loader
296
     * @param invoker Service invoker
297
     * @param classLoader Class loader to use
298
     * @return Service proxy
299
     */
300
    <T> T getProxy(Invoker<T> invoker, Class<?>... interfaces) throws RpcException;
301
    
302
    /**
303
     * Create invoker for provider side
304
     * @param proxy Service implementation
305
     * @param type Service interface
306
     * @param url Service URL
307
     * @return Service invoker
308
     */
309
    <T> Invoker<T> getInvoker(T proxy, Class<T> type, URL url) throws RpcException;
310
}
311
```
312

313
### Filter System
314

315
Interceptor pattern for request/response processing.
316

317
```java { .api }
318
/**
319
 * RPC invocation filter for intercepting requests and responses
320
 */
321
@SPI
322
public interface Filter {
323
    /**
324
     * Filter RPC invocation
325
     * @param invoker Next invoker in chain
326
     * @param invocation Current invocation
327
     * @return Invocation result
328
     * @throws RpcException if filtering fails
329
     */
330
    Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException;
331
    
332
    /**
333
     * Callback for successful response (optional)
334
     * @param appResponse Application response
335
     * @param invoker Service invoker
336
     * @param invocation Original invocation
337
     * @return Modified response
338
     */
339
    default Result onResponse(Result appResponse, Invoker<?> invoker, Invocation invocation) {
340
        return appResponse;
341
    }
342
    
343
    /**
344
     * Callback for exception handling (optional)
345
     * @param exception Thrown exception
346
     * @param invoker Service invoker  
347
     * @param invocation Original invocation
348
     */
349
    default void onError(Throwable exception, Invoker<?> invoker, Invocation invocation) {
350
        // Default implementation does nothing
351
    }
352
}
353

354
/**
355
 * Base filter implementation with common functionality
356
 */
357
public abstract class BaseFilter implements Filter {
358
    protected boolean needToPrintLog(Invoker<?> invoker, Invocation invocation) {
359
        return true;
360
    }
361
}
362
```
363

364
**Usage Examples:**
365

366
```java
367
// Custom logging filter
368
public class LoggingFilter implements Filter {
369
    @Override
370
    public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
371
        long start = System.currentTimeMillis();
372
        try {
373
            Result result = invoker.invoke(invocation);
374
            long elapsed = System.currentTimeMillis() - start;
375
            System.out.println("Method " + invocation.getMethodName() + 
376
                             " took " + elapsed + "ms");
377
            return result;
378
        } catch (Exception e) {
379
            System.err.println("Method " + invocation.getMethodName() + " failed: " + e.getMessage());
380
            throw e;
381
        }
382
    }
383
}
384
```
385

386
### Protocol Interface
387

388
SPI interface for different transport protocols.
389

390
```java { .api }
391
/**
392
 * Protocol interface for different transport implementations
393
 */
394
@SPI("dubbo")
395
public interface Protocol {
396
    /** Get default port for this protocol */
397
    int getDefaultPort();
398
    
399
    /**
400
     * Export service for provider side
401
     * @param invoker Service invoker to export
402
     * @return Service exporter for lifecycle management
403
     * @throws RpcException if export fails
404
     */
405
    <T> Exporter<T> export(Invoker<T> invoker) throws RpcException;
406
    
407
    /**
408
     * Create service reference for consumer side
409
     * @param type Service interface class
410
     * @param url Service URL
411
     * @return Service invoker
412
     * @throws RpcException if reference creation fails
413
     */
414
    <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException;
415
    
416
    /** Destroy protocol and release resources */
417
    void destroy();
418
}
419

420
/**
421
 * Service exporter for managing exported services
422
 */
423
public interface Exporter<T> {
424
    /** Get the exported service invoker */
425
    Invoker<T> getInvoker();
426
    
427
    /** Unexport the service */
428
    void unexport();
429
}
430
```
431

432
### RPC Exception Handling
433

434
Comprehensive exception handling with error codes.
435

436
```java { .api }
437
/**
438
 * RPC-specific exception with error codes
439
 */
440
public class RpcException extends RuntimeException {
441
    // Exception types
442
    public static final int UNKNOWN_EXCEPTION = 0;
443
    public static final int NETWORK_EXCEPTION = 1;
444
    public static final int TIMEOUT_EXCEPTION = 2;
445
    public static final int BIZ_EXCEPTION = 3;
446
    public static final int FORBIDDEN_EXCEPTION = 4;
447
    public static final int SERIALIZATION_EXCEPTION = 5;
448
    public static final int NO_INVOKER_AVAILABLE_AFTER_FILTER = 6;
449
    public static final int LIMIT_EXCEEDED_EXCEPTION = 7;
450
    
451
    public RpcException();
452
    public RpcException(String message);
453
    public RpcException(String message, Throwable cause);
454
    public RpcException(int code);
455
    public RpcException(int code, String message);
456
    public RpcException(int code, String message, Throwable cause);
457
    
458
    /** Get exception code */
459
    public int getCode();
460
    
461
    /** Set exception code */
462
    public void setCode(int code);
463
    
464
    /** Check if exception is of specific type */
465
    public boolean isBiz();
466
    public boolean isTimeout();
467
    public boolean isNetwork();
468
    public boolean isSerialization();
469
    public boolean isForbidden();
470
}
471
```
472

473
## Echo Service
474

475
Built-in service for connectivity testing and health checks.
476

477
```java { .api }
478
/**
479
 * Built-in echo service for testing connectivity
480
 */
481
public interface EchoService {
482
    /**
483
     * Echo the input message back
484
     * @param message Message to echo
485
     * @return Same message
486
     */
487
    Object $echo(Object message);
488
}
489
```
490

491
**Usage Examples:**
492

493
```java
494
// Test service connectivity
495
EchoService echoService = (EchoService) greeterService;
496
Object result = echoService.$echo("ping");
497
// result should be "ping" if service is available
498
```