0
# Communication Interfaces and Models
1

2
Remote procedure call interfaces and data models for admin-executor communication. Handles job triggering, status callbacks, heartbeat monitoring, and distributed coordination.
3

4
## Capabilities
5

6
### AdminBiz Interface
7

8
Interface for executor-to-admin communication, handling job execution callbacks and executor registration.
9

10
```java { .api }
11
/**
12
 * Interface for communication from executor to admin server
13
 * Handles job callbacks and executor lifecycle management
14
 */
15
public interface AdminBiz {
16
    
17
    /**
18
     * Send job execution callback results to admin server
19
     * @param callbackParamList - List of job execution results
20
     * @return Response indicating callback processing status
21
     */
22
    ReturnT<String> callback(List<HandleCallbackParam> callbackParamList);
23
    
24
    /**
25
     * Register executor with admin server
26
     * @param registryParam - Executor registration information
27
     * @return Response indicating registration status
28
     */
29
    ReturnT<String> registry(RegistryParam registryParam);
30
    
31
    /**
32
     * Unregister executor from admin server
33
     * @param registryParam - Executor registration information to remove
34
     * @return Response indicating unregistration status
35
     */
36
    ReturnT<String> registryRemove(RegistryParam registryParam);
37
}
38
```
39

40
### ExecutorBiz Interface
41

42
Interface for admin-to-executor communication, handling job triggers, heartbeats, and log queries.
43

44
```java { .api }
45
/**
46
 * Interface for communication from admin server to executor
47
 * Handles job triggering and executor monitoring
48
 */
49
public interface ExecutorBiz {
50
    
51
    /**
52
     * Heartbeat check to verify executor is alive
53
     * @return Response indicating executor status
54
     */
55
    ReturnT<String> beat();
56
    
57
    /**
58
     * Idle heartbeat check for specific job
59
     * @param idleBeatParam - Parameters for idle beat check
60
     * @return Response indicating job thread status
61
     */
62
    ReturnT<String> idleBeat(IdleBeatParam idleBeatParam);
63
    
64
    /**
65
     * Trigger job execution
66
     * @param triggerParam - Job execution parameters
67
     * @return Response indicating trigger acceptance status
68
     */
69
    ReturnT<String> run(TriggerParam triggerParam);
70
    
71
    /**
72
     * Kill running job execution
73
     * @param killParam - Parameters for job termination
74
     * @return Response indicating kill operation status
75
     */
76
    ReturnT<String> kill(KillParam killParam);
77
    
78
    /**
79
     * Query job execution logs
80
     * @param logParam - Parameters for log query
81
     * @return Log content and metadata
82
     */
83
    ReturnT<LogResult> log(LogParam logParam);
84
}
85
```
86

87
## Response and Parameter Models
88

89
### ReturnT Generic Response
90

91
Standard response wrapper for all remote procedure calls with success/failure indication and optional data payload.
92

93
```java { .api }
94
/**
95
 * Generic response wrapper for RPC calls
96
 * @param <T> Response data type
97
 */
98
public class ReturnT<T> implements Serializable {
99
    
100
    // Response code constants
101
    /**
102
     * Success response code
103
     */
104
    public static final int SUCCESS_CODE = 200;
105
    
106
    /**
107
     * Failure response code
108
     */
109
    public static final int FAIL_CODE = 500;
110
    
111
    // Predefined response instances
112
    /**
113
     * Predefined success response
114
     */
115
    public static final ReturnT<String> SUCCESS = new ReturnT<String>(null);
116
    
117
    /**
118
     * Predefined failure response
119
     */
120
    public static final ReturnT<String> FAIL = new ReturnT<String>(FAIL_CODE, null);
121
    
122
    // Constructors
123
    /**
124
     * Create success response with data
125
     * @param content Response data
126
     */
127
    public ReturnT(T content);
128
    
129
    /**
130
     * Create response with code and message
131
     * @param code Response code (200=success, 500=failure)
132
     * @param msg Response message
133
     */
134
    public ReturnT(int code, String msg);
135
    
136
    /**
137
     * Create empty response (defaults to success)
138
     */
139
    public ReturnT();
140
    
141
    // Accessors
142
    /**
143
     * Get response code
144
     * @return Response code (200=success, 500=failure)
145
     */
146
    public int getCode();
147
    
148
    /**
149
     * Set response code
150
     * @param code Response code to set
151
     */
152
    public void setCode(int code);
153
    
154
    /**
155
     * Get response message
156
     * @return Response message or null
157
     */
158
    public String getMsg();
159
    
160
    /**
161
     * Set response message
162
     * @param msg Response message to set
163
     */
164
    public void setMsg(String msg);
165
    
166
    /**
167
     * Get response content/data
168
     * @return Response data or null
169
     */
170
    public T getContent();
171
    
172
    /**
173
     * Set response content/data
174
     * @param content Response data to set
175
     */
176
    public void setContent(T content);
177
}
178
```
179

180
**Usage Examples:**
181

182
```java
183
// Success response with data
184
ReturnT<String> successResult = new ReturnT<>("Operation completed successfully");
185

186
// Failure response with error message
187
ReturnT<String> failureResult = new ReturnT<>(ReturnT.FAIL_CODE, "Validation failed");
188

189
// Check response status
190
if (result.getCode() == ReturnT.SUCCESS_CODE) {
191
    String data = result.getContent();
192
    // Handle success
193
} else {
194
    String error = result.getMsg();
195
    // Handle failure
196
}
197
```
198

199
### TriggerParam (Job Trigger Parameters)
200

201
Parameters passed from admin server when triggering job execution.
202

203
```java { .api }
204
/**
205
 * Parameters for job trigger requests from admin to executor
206
 */
207
public class TriggerParam implements Serializable {
208
    
209
    /**
210
     * Job identifier
211
     */
212
    private int jobId;
213
    
214
    /**
215
     * Job handler name
216
     */
217
    private String executorHandler;
218
    
219
    /**
220
     * Job execution parameters
221
     */
222
    private String executorParams;
223
    
224
    /**
225
     * Blocking strategy when job is already running
226
     */
227
    private String executorBlockStrategy;
228
    
229
    /**
230
     * Job execution timeout in seconds
231
     */
232
    private int executorTimeout;
233
    
234
    /**
235
     * Log identifier for this execution
236
     */
237
    private long logId;
238
    
239
    /**
240
     * Job trigger timestamp
241
     */
242
    private long logDateTime;
243
    
244
    /**
245
     * Glue script type (BEAN, GLUE_GROOVY, etc.)
246
     */
247
    private String glueType;
248
    
249
    /**
250
     * Glue script source code
251
     */
252
    private String glueSource;
253
    
254
    /**
255
     * Glue script last update time
256
     */
257
    private long glueUpdatetime;
258
    
259
    /**
260
     * Broadcast index for broadcast jobs
261
     */
262
    private int broadcastIndex;
263
    
264
    /**
265
     * Total broadcast count for broadcast jobs
266
     */
267
    private int broadcastTotal;
268
    
269
    // Standard getters and setters for all fields
270
}
271
```
272

273
### HandleCallbackParam (Execution Callback)
274

275
Parameters sent from executor to admin server reporting job execution results.
276

277
```java { .api }
278
/**
279
 * Parameters for job execution callbacks from executor to admin
280
 */
281
public class HandleCallbackParam implements Serializable {
282
    
283
    /**
284
     * Log identifier matching the trigger request
285
     */
286
    private long logId;
287
    
288
    /**
289
     * Job execution timestamp
290
     */
291
    private long logDateTim;
292
    
293
    /**
294
     * Job execution result code (200=success, 500=fail, 502=timeout)
295
     */
296
    private int handleCode;
297
    
298
    /**
299
     * Job execution result message
300
     */
301
    private String handleMsg;
302
    
303
    // Constructors
304
    /**
305
     * Create callback parameter
306
     * @param logId Log identifier
307
     * @param logDateTim Execution timestamp
308
     * @param handleCode Result code
309
     * @param handleMsg Result message
310
     */
311
    public HandleCallbackParam(long logId, long logDateTim, int handleCode, String handleMsg);
312
    
313
    // Standard getters and setters
314
}
315
```
316

317
### RegistryParam (Executor Registration)
318

319
Parameters for executor registration and unregistration with admin servers.
320

321
```java { .api }
322
/**
323
 * Parameters for executor registration with admin server
324
 */
325
public class RegistryParam implements Serializable {
326
    
327
    /**
328
     * Registry type (EXECUTOR or ADMIN)
329
     */
330
    private String registryGroup;
331
    
332
    /**
333
     * Registry key (typically application name)
334
     */
335
    private String registryKey;
336
    
337
    /**
338
     * Registry value (executor address)
339
     */
340
    private String registryValue;
341
    
342
    // Constructors
343
    /**
344
     * Create registration parameter
345
     * @param registryGroup Registry type
346
     * @param registryKey Application name
347
     * @param registryValue Executor address
348
     */
349
    public RegistryParam(String registryGroup, String registryKey, String registryValue);
350
    
351
    // Standard getters and setters
352
}
353
```
354

355
### IdleBeatParam (Idle Heartbeat)
356

357
Parameters for checking if a specific job thread is idle and available for execution.
358

359
```java { .api }
360
/**
361
 * Parameters for idle heartbeat checks
362
 */
363
public class IdleBeatParam implements Serializable {
364
    
365
    /**
366
     * Job identifier to check
367
     */
368
    private int jobId;
369
    
370
    // Constructors and standard getters/setters
371
}
372
```
373

374
### KillParam (Job Termination)
375

376
Parameters for requesting termination of a running job.
377

378
```java { .api }
379
/**
380
 * Parameters for job kill requests
381
 */
382
public class KillParam implements Serializable {
383
    
384
    /**
385
     * Job identifier to terminate
386
     */
387
    private int jobId;
388
    
389
    // Constructors and standard getters/setters
390
}
391
```
392

393
### LogParam (Log Query)
394

395
Parameters for querying job execution logs from executor.
396

397
```java { .api }
398
/**
399
 * Parameters for log query requests
400
 */
401
public class LogParam implements Serializable {
402
    
403
    /**
404
     * Job trigger timestamp
405
     */
406
    private long logDateTim;
407
    
408
    /**
409
     * Log identifier
410
     */
411
    private long logId;
412
    
413
    /**
414
     * Starting line number for log retrieval
415
     */
416
    private int fromLineNum;
417
    
418
    // Constructors and standard getters/setters
419
}
420
```
421

422
### LogResult (Log Query Response)
423

424
Response containing job execution log content and metadata.
425

426
```java { .api }
427
/**
428
 * Response containing job execution log data
429
 */
430
public class LogResult implements Serializable {
431
    
432
    /**
433
     * Starting line number of returned content
434
     */
435
    private int fromLineNum;
436
    
437
    /**
438
     * Ending line number of returned content
439
     */
440
    private int toLineNum;
441
    
442
    /**
443
     * Log content as string
444
     */
445
    private String logContent;
446
    
447
    /**
448
     * Whether there are more log lines available
449
     */
450
    private boolean isEnd;
451
    
452
    // Constructors and standard getters/setters
453
}
454
```
455

456
## Communication Patterns
457

458
### Job Execution Flow
459

460
```java
461
// 1. Admin triggers job execution
462
TriggerParam triggerParam = new TriggerParam();
463
triggerParam.setJobId(123);
464
triggerParam.setExecutorHandler("myJobHandler");
465
triggerParam.setExecutorParams("{\"mode\":\"batch\"}");
466
triggerParam.setLogId(456);
467

468
ReturnT<String> triggerResponse = executorBiz.run(triggerParam);
469

470
// 2. Executor processes job and sends callback
471
HandleCallbackParam callbackParam = new HandleCallbackParam(
472
    456, // logId
473
    System.currentTimeMillis(),
474
    200, // success code
475
    "Job completed successfully"
476
);
477

478
List<HandleCallbackParam> callbackList = Arrays.asList(callbackParam);
479
ReturnT<String> callbackResponse = adminBiz.callback(callbackList);
480
```
481

482
### Executor Registration Flow
483

484
```java
485
// Register executor with admin server
486
RegistryParam registryParam = new RegistryParam(
487
    "EXECUTOR",                    // registry group
488
    "my-application",              // app name
489
    "http://192.168.1.100:9999"    // executor address
490
);
491

492
ReturnT<String> registryResponse = adminBiz.registry(registryParam);
493

494
// Unregister on shutdown
495
ReturnT<String> unregisterResponse = adminBiz.registryRemove(registryParam);
496
```
497

498
### Heartbeat Monitoring
499

500
```java
501
// General executor heartbeat
502
ReturnT<String> beatResponse = executorBiz.beat();
503

504
// Job-specific idle check
505
IdleBeatParam idleBeatParam = new IdleBeatParam();
506
idleBeatParam.setJobId(123);
507

508
ReturnT<String> idleBeatResponse = executorBiz.idleBeat(idleBeatParam);
509
```
510

511
### Log Retrieval
512

513
```java
514
// Query job execution logs
515
LogParam logParam = new LogParam();
516
logParam.setLogId(456);
517
logParam.setLogDateTim(System.currentTimeMillis());
518
logParam.setFromLineNum(1);
519

520
ReturnT<LogResult> logResponse = executorBiz.log(logParam);
521

522
if (logResponse.getCode() == ReturnT.SUCCESS_CODE) {
523
    LogResult logResult = logResponse.getContent();
524
    String logContent = logResult.getLogContent();
525
    boolean hasMoreLines = !logResult.isEnd();
526
    
527
    // Display or process log content
528
    System.out.println(logContent);
529
    
530
    // Fetch more lines if available
531
    if (hasMoreLines) {
532
        logParam.setFromLineNum(logResult.getToLineNum() + 1);
533
        // Query next batch...
534
    }
535
}
536
```
537

538
### Job Termination
539

540
```java
541
// Kill running job
542
KillParam killParam = new KillParam();
543
killParam.setJobId(123);
544

545
ReturnT<String> killResponse = executorBiz.kill(killParam);
546

547
if (killResponse.getCode() == ReturnT.SUCCESS_CODE) {
548
    System.out.println("Job killed successfully");
549
} else {
550
    System.out.println("Kill failed: " + killResponse.getMsg());
551
}
552
```
553

554
## Error Handling
555

556
### Response Code Handling
557

558
```java
559
public void handleResponse(ReturnT<?> response) {
560
    switch (response.getCode()) {
561
        case ReturnT.SUCCESS_CODE:
562
            // Handle success
563
            System.out.println("Operation successful: " + response.getMsg());
564
            break;
565
            
566
        case ReturnT.FAIL_CODE:
567
            // Handle failure
568
            System.err.println("Operation failed: " + response.getMsg());
569
            break;
570
            
571
        default:
572
            // Handle custom codes
573
            System.out.println("Custom response code " + response.getCode() + ": " + response.getMsg());
574
            break;
575
    }
576
}
577
```
578

579
### Communication Retry Logic
580

581
```java
582
public ReturnT<String> callWithRetry(AdminBiz adminBiz, HandleCallbackParam callbackParam) {
583
    int maxRetries = 3;
584
    int retryDelay = 1000; // 1 second
585
    
586
    for (int attempt = 1; attempt <= maxRetries; attempt++) {
587
        try {
588
            List<HandleCallbackParam> callbacks = Arrays.asList(callbackParam);
589
            ReturnT<String> response = adminBiz.callback(callbacks);
590
            
591
            if (response.getCode() == ReturnT.SUCCESS_CODE) {
592
                return response;
593
            }
594
            
595
            System.out.println("Attempt " + attempt + " failed: " + response.getMsg());
596
            
597
        } catch (Exception e) {
598
            System.out.println("Attempt " + attempt + " error: " + e.getMessage());
599
        }
600
        
601
        if (attempt < maxRetries) {
602
            try {
603
                Thread.sleep(retryDelay * attempt); // Exponential backoff
604
            } catch (InterruptedException e) {
605
                Thread.currentThread().interrupt();
606
                break;
607
            }
608
        }
609
    }
610
    
611
    return new ReturnT<>(ReturnT.FAIL_CODE, "All retry attempts failed");
612
}
613
```