0
# Executor Configuration and Management
1

2
Executor lifecycle management for both Spring and standalone environments. Handles registration with admin servers, job thread management, and server communication.
3

4
## Capabilities
5

6
### XxlJobExecutor Core Class
7

8
Main executor class that manages job execution lifecycle, communication with admin servers, and embedded HTTP server.
9

10
```java { .api }
11
/**
12
 * Core executor class for managing job execution and lifecycle
13
 * Handles registration with admin servers and job thread management
14
 */
15
public class XxlJobExecutor {
16
    
17
    // Configuration methods
18
    /**
19
     * Set admin server addresses (comma-separated for multiple servers)
20
     * @param adminAddresses - Admin server URLs, e.g., "http://127.0.0.1:8080/xxl-job-admin"
21
     */
22
    public void setAdminAddresses(String adminAddresses);
23
    
24
    /**
25
     * Set access token for authentication with admin servers
26
     * @param accessToken - Token for secure communication
27
     */
28
    public void setAccessToken(String accessToken);
29
    
30
    /**
31
     * Set timeout for network operations in seconds
32
     * @param timeout - Timeout value (default: 30 seconds)
33
     */
34
    public void setTimeout(int timeout);
35
    
36
    /**
37
     * Set application name for executor identification
38
     * @param appname - Unique application name for this executor
39
     */
40
    public void setAppname(String appname);
41
    
42
    /**
43
     * Set executor address for admin callback (optional, auto-detected if not set)
44
     * @param address - Full executor address including port
45
     */
46
    public void setAddress(String address);
47
    
48
    /**
49
     * Set executor IP address (optional, auto-detected if not set)
50
     * @param ip - IP address for admin callback
51
     */
52
    public void setIp(String ip);
53
    
54
    /**
55
     * Set executor port for embedded HTTP server
56
     * @param port - Port number for receiving job triggers
57
     */
58
    public void setPort(int port);
59
    
60
    /**
61
     * Set log file storage path
62
     * @param logPath - Directory path for job execution logs
63
     */
64
    public void setLogPath(String logPath);
65
    
66
    /**
67
     * Set log retention period in days
68
     * @param logRetentionDays - Number of days to keep log files
69
     */
70
    public void setLogRetentionDays(int logRetentionDays);
71
    
72
    // Lifecycle methods
73
    /**
74
     * Start the executor and register with admin servers
75
     * Initializes embedded HTTP server and begins heartbeat
76
     * @throws Exception if startup fails
77
     */
78
    public void start() throws Exception;
79
    
80
    /**
81
     * Stop the executor and cleanup resources
82
     * Unregisters from admin servers and stops embedded server
83
     */
84
    public void destroy();
85
    
86
    // Static management methods
87
    /**
88
     * Get list of admin server communication clients
89
     * @return List of AdminBiz clients for admin server communication
90
     */
91
    public static List<AdminBiz> getAdminBizList();
92
    
93
    /**
94
     * Load job handler by name
95
     * @param name - Job handler name
96
     * @return IJobHandler instance or null if not found
97
     */
98
    public static IJobHandler loadJobHandler(String name);
99
    
100
    /**
101
     * Register job handler with given name
102
     * @param name - Job handler name for registration
103
     * @param jobHandler - IJobHandler implementation
104
     * @return Previously registered handler or null
105
     */
106
    public static IJobHandler registJobHandler(String name, IJobHandler jobHandler);
107
    
108
    /**
109
     * Register job thread for specific job ID
110
     * @param jobId - Unique job identifier
111
     * @param handler - Job handler to execute
112
     * @param removeOldReason - Reason for removing old thread (if exists)
113
     * @return JobThread instance
114
     */
115
    public static JobThread registJobThread(int jobId, IJobHandler handler, String removeOldReason);
116
    
117
    /**
118
     * Remove job thread for specific job ID
119
     * @param jobId - Job identifier
120
     * @param removeOldReason - Reason for removal
121
     * @return Removed JobThread or null
122
     */
123
    public static JobThread removeJobThread(int jobId, String removeOldReason);
124
    
125
    /**
126
     * Load existing job thread for specific job ID
127
     * @param jobId - Job identifier
128
     * @return JobThread instance or null if not found
129
     */
130
    public static JobThread loadJobThread(int jobId);
131
}
132
```
133

134
### XxlJobSpringExecutor (Spring Integration)
135

136
Spring-integrated executor with automatic discovery of @XxlJob annotated methods and Spring lifecycle management.
137

138
```java { .api }
139
/**
140
 * Spring-integrated executor with automatic @XxlJob method discovery
141
 * Implements Spring lifecycle interfaces for proper integration
142
 */
143
public class XxlJobSpringExecutor extends XxlJobExecutor 
144
    implements ApplicationContextAware, SmartInitializingSingleton, DisposableBean {
145
    
146
    /**
147
     * Get Spring application context
148
     * @return ApplicationContext instance
149
     */
150
    public static ApplicationContext getApplicationContext();
151
    
152
    // Inherited from XxlJobExecutor: all configuration and lifecycle methods
153
    // Additional Spring lifecycle management handled automatically
154
}
155
```
156

157
**Usage Examples:**
158

159
```java
160
import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
161
import org.springframework.context.annotation.Bean;
162
import org.springframework.context.annotation.Configuration;
163

164
@Configuration
165
public class XxlJobConfig {
166
    
167
    @Bean
168
    public XxlJobSpringExecutor xxlJobExecutor() {
169
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
170
        
171
        // Required configuration
172
        xxlJobSpringExecutor.setAdminAddresses("http://127.0.0.1:8080/xxl-job-admin");
173
        xxlJobSpringExecutor.setAppname("xxl-job-executor-sample");
174
        
175
        // Optional configuration
176
        xxlJobSpringExecutor.setAddress(""); // Auto-detect if empty
177
        xxlJobSpringExecutor.setIp(""); // Auto-detect if empty
178
        xxlJobSpringExecutor.setPort(9999);
179
        xxlJobSpringExecutor.setAccessToken("default_token");
180
        xxlJobSpringExecutor.setLogPath("/data/applogs/xxl-job/jobhandler");
181
        xxlJobSpringExecutor.setLogRetentionDays(30);
182
        
183
        return xxlJobSpringExecutor;
184
    }
185
}
186

187
// Multiple admin servers for high availability
188
@Bean
189
public XxlJobSpringExecutor xxlJobExecutor() {
190
    XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
191
    executor.setAdminAddresses("http://admin1:8080/xxl-job-admin,http://admin2:8080/xxl-job-admin");
192
    // Other configuration...
193
    return executor;
194
}
195
```
196

197
### XxlJobSimpleExecutor (Standalone Usage)
198

199
Simple executor for non-Spring environments with manual job handler registration.
200

201
```java { .api }
202
/**
203
 * Simple executor for non-Spring environments
204
 * Requires manual job handler registration
205
 */
206
public class XxlJobSimpleExecutor extends XxlJobExecutor {
207
    
208
    /**
209
     * Get list of job bean objects containing @XxlJob methods
210
     * @return List of objects with job handler methods
211
     */
212
    public List<Object> getXxlJobBeanList();
213
    
214
    /**
215
     * Set list of job bean objects containing @XxlJob methods
216
     * @param xxlJobBeanList - List of objects with @XxlJob annotated methods
217
     */
218
    public void setXxlJobBeanList(List<Object> xxlJobBeanList);
219
    
220
    // Inherited from XxlJobExecutor: all configuration and lifecycle methods
221
}
222
```
223

224
**Usage Examples:**
225

226
```java
227
import com.xxl.job.core.executor.impl.XxlJobSimpleExecutor;
228
import java.util.Arrays;
229

230
public class StandaloneJobExecutor {
231
    
232
    public static void main(String[] args) throws Exception {
233
        // Create and configure executor
234
        XxlJobSimpleExecutor xxlJobExecutor = new XxlJobSimpleExecutor();
235
        
236
        // Configuration
237
        xxlJobExecutor.setAdminAddresses("http://127.0.0.1:8080/xxl-job-admin");
238
        xxlJobExecutor.setAppname("standalone-executor");
239
        xxlJobExecutor.setPort(9999);
240
        xxlJobExecutor.setLogPath("./logs");
241
        
242
        // Register job handlers manually
243
        xxlJobExecutor.setXxlJobBeanList(Arrays.asList(
244
            new MyJobHandlerBean(),
245
            new AnotherJobHandlerBean()
246
        ));
247
        
248
        // Start executor
249
        xxlJobExecutor.start();
250
        
251
        // Keep application running
252
        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
253
            xxlJobExecutor.destroy();
254
        }));
255
        
256
        Thread.sleep(Long.MAX_VALUE);
257
    }
258
}
259

260
// Job handler bean class
261
public class MyJobHandlerBean {
262
    
263
    @XxlJob("standaloneJob")
264
    public void standaloneJobHandler() throws Exception {
265
        XxlJobHelper.log("Standalone job executing");
266
        XxlJobHelper.handleSuccess();
267
    }
268
}
269
```
270

271
## Configuration Best Practices
272

273
### Production Configuration
274

275
```java
276
@Configuration
277
@Profile("production")
278
public class ProductionXxlJobConfig {
279
    
280
    @Bean
281
    public XxlJobSpringExecutor xxlJobExecutor() {
282
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
283
        
284
        // High availability admin servers
285
        executor.setAdminAddresses(
286
            "http://xxl-job-admin-1:8080/xxl-job-admin," +
287
            "http://xxl-job-admin-2:8080/xxl-job-admin"
288
        );
289
        
290
        // Unique application identification
291
        executor.setAppname("production-order-service");
292
        
293
        // Security token
294
        executor.setAccessToken("${xxl.job.access.token}");
295
        
296
        // Network configuration
297
        executor.setPort(9999);
298
        executor.setTimeout(60); // 60 seconds for long-running jobs
299
        
300
        // Logging configuration
301
        executor.setLogPath("/var/log/xxl-job");
302
        executor.setLogRetentionDays(7); // Keep logs for 7 days
303
        
304
        return executor;
305
    }
306
}
307
```
308

309
### Development Configuration
310

311
```java
312
@Configuration
313
@Profile("development")
314
public class DevelopmentXxlJobConfig {
315
    
316
    @Bean
317
    public XxlJobSpringExecutor xxlJobExecutor() {
318
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
319
        
320
        // Local admin server
321
        executor.setAdminAddresses("http://localhost:8080/xxl-job-admin");
322
        executor.setAppname("dev-" + System.getProperty("user.name"));
323
        
324
        // Development settings
325
        executor.setPort(0); // Random available port
326
        executor.setLogPath("./logs/xxl-job");
327
        executor.setLogRetentionDays(3);
328
        
329
        return executor;
330
    }
331
}
332
```
333

334
### Dynamic Configuration
335

336
```java
337
@Configuration
338
public class DynamicXxlJobConfig {
339
    
340
    @Value("${xxl.job.admin.addresses}")
341
    private String adminAddresses;
342
    
343
    @Value("${xxl.job.executor.appname}")
344
    private String appname;
345
    
346
    @Value("${xxl.job.executor.port:9999}")
347
    private int port;
348
    
349
    @Value("${xxl.job.access.token:}")
350
    private String accessToken;
351
    
352
    @Value("${xxl.job.executor.logpath:./logs}")
353
    private String logPath;
354
    
355
    @Value("${xxl.job.executor.logretentiondays:30}")
356
    private int logRetentionDays;
357
    
358
    @Bean
359
    public XxlJobSpringExecutor xxlJobExecutor() {
360
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
361
        
362
        executor.setAdminAddresses(adminAddresses);
363
        executor.setAppname(appname);
364
        executor.setPort(port);
365
        executor.setAccessToken(accessToken);
366
        executor.setLogPath(logPath);
367
        executor.setLogRetentionDays(logRetentionDays);
368
        
369
        return executor;
370
    }
371
}
372
```
373

374
## Executor Lifecycle Management
375

376
### Startup Process
377

378
1. **Configuration Validation**: Validate required settings (admin addresses, app name)
379
2. **Server Initialization**: Start embedded Netty HTTP server on configured port
380
3. **Handler Registration**: Discover and register @XxlJob annotated methods (Spring) or manual handlers
381
4. **Admin Registration**: Register executor with admin servers and begin heartbeat
382
5. **Thread Pool Setup**: Initialize job execution thread pools
383

384
### Shutdown Process
385

386
1. **Graceful Shutdown**: Complete currently executing jobs
387
2. **Admin Unregistration**: Unregister from admin servers
388
3. **Server Shutdown**: Stop embedded HTTP server
389
4. **Resource Cleanup**: Clean up threads, connections, and temporary resources
390

391
### Health Monitoring
392

393
The executor automatically handles:
394
- **Heartbeat**: Regular ping to admin servers to indicate availability
395
- **Registry**: Automatic re-registration if admin servers restart
396
- **Job Thread Management**: Creation and cleanup of job execution threads
397
- **Log Management**: Automatic log file rotation and cleanup based on retention settings