0
# XXL-Job Core
1

2
XXL-Job Core is a distributed task scheduling framework library for Java applications. It provides comprehensive job execution capabilities with cluster deployment, task failover, and real-time monitoring. The library enables developers to build scalable job scheduling systems with embedded Netty server functionality, JSON serialization, Groovy scripting support, and Spring framework integration.
3

4
## Package Information
5

6
- **Package Name**: xxl-job-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>com.xuxueli</groupId><artifactId>xxl-job-core</artifactId><version>3.1.0</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import com.xxl.job.core.handler.annotation.XxlJob;
15
import com.xxl.job.core.context.XxlJobHelper;
16
import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
17
```
18

19
## Basic Usage
20

21
```java
22
import com.xxl.job.core.handler.annotation.XxlJob;
23
import com.xxl.job.core.context.XxlJobHelper;
24
import org.springframework.stereotype.Component;
25

26
@Component
27
public class SampleJobHandler {
28

29
    @XxlJob("demoJobHandler")
30
    public void demoJobHandler() throws Exception {
31
        String param = XxlJobHelper.getJobParam();
32
        XxlJobHelper.log("XXL-JOB, Hello World: {}", param);
33
        
34
        // Job logic here
35
        
36
        XxlJobHelper.handleSuccess();
37
    }
38
}
39

40
// Configuration
41
@Configuration
42
public class XxlJobConfig {
43
    
44
    @Bean
45
    public XxlJobSpringExecutor xxlJobExecutor() {
46
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
47
        xxlJobSpringExecutor.setAdminAddresses("http://127.0.0.1:8080/xxl-job-admin");
48
        xxlJobSpringExecutor.setAppname("xxl-job-executor-sample");
49
        xxlJobSpringExecutor.setAddress("");
50
        xxlJobSpringExecutor.setIp("");
51
        xxlJobSpringExecutor.setPort(9999);
52
        xxlJobSpringExecutor.setAccessToken("");
53
        xxlJobSpringExecutor.setLogPath("/data/applogs/xxl-job/jobhandler");
54
        xxlJobSpringExecutor.setLogRetentionDays(30);
55
        return xxlJobSpringExecutor;
56
    }
57
}
58
```
59

60
## Architecture
61

62
XXL-Job Core is built around several key components:
63

64
- **Job Annotation System**: `@XxlJob` annotation for marking methods as job handlers with automatic discovery
65
- **Executor Framework**: Core execution management through `XxlJobExecutor` with Spring and standalone implementations
66
- **Context Management**: Thread-local job context through `XxlJobHelper` and `XxlJobContext` for accessing job parameters and logging
67
- **Communication Layer**: Remote procedure call interfaces (`AdminBiz`, `ExecutorBiz`) for distributed coordination
68
- **Embedded Server**: Netty-based HTTP server for receiving job trigger requests
69
- **Script Engine**: Dynamic job execution through Groovy and other scripting languages
70
- **Logging System**: File-based job execution logging with configurable retention
71

72
## Capabilities
73

74
### Job Definition and Execution
75

76
Core job definition using annotations and handlers. Essential for creating executable job units that can be scheduled and triggered by the XXL-Job admin system.
77

78
```java { .api }
79
// Primary job annotation
80
@XxlJob(value = "jobName", init = "initMethod", destroy = "destroyMethod")
81
public @interface XxlJob {
82
    String value();
83
    String init() default "";
84
    String destroy() default "";
85
}
86

87
// Base job handler interface
88
public abstract class IJobHandler {
89
    public abstract void execute() throws Exception;
90
    public void init() throws Exception {}
91
    public void destroy() throws Exception {}
92
}
93
```
94

95
[Job Handlers and Annotations](./job-handlers.md)
96

97
### Executor Management
98

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

101
```java { .api }
102
// Core executor class
103
public class XxlJobExecutor {
104
    public void setAdminAddresses(String adminAddresses);
105
    public void setAccessToken(String accessToken);
106
    public void setAppname(String appname);
107
    public void setAddress(String address);
108
    public void setPort(int port);
109
    public void setLogPath(String logPath);
110
    public void start() throws Exception;
111
    public void destroy();
112
}
113

114
// Spring integration
115
public class XxlJobSpringExecutor extends XxlJobExecutor 
116
    implements ApplicationContextAware, SmartInitializingSingleton, DisposableBean {
117
    // Automatic @XxlJob method discovery
118
}
119

120
// Standalone usage
121
public class XxlJobSimpleExecutor extends XxlJobExecutor {
122
    public void setXxlJobBeanList(List<Object> xxlJobBeanList);
123
}
124
```
125

126
[Executor Configuration and Management](./executor.md)
127

128
### Job Context and Utilities
129

130
Runtime context access and logging utilities for job execution. Provides thread-safe access to job parameters, logging, and result handling.
131

132
```java { .api }
133
// Context helper utilities
134
public class XxlJobHelper {
135
    public static long getJobId();
136
    public static String getJobParam();
137
    public static int getShardIndex();
138
    public static int getShardTotal();
139
    public static boolean log(String pattern, Object... arguments);
140
    public static boolean handleSuccess();
141
    public static boolean handleSuccess(String message);
142
    public static boolean handleFail();
143
    public static boolean handleFail(String message);
144
    public static boolean handleTimeout();
145
}
146

147
// Job execution context
148
public class XxlJobContext {
149
    public static final int HANDLE_CODE_SUCCESS = 200;
150
    public static final int HANDLE_CODE_FAIL = 500;
151
    public static final int HANDLE_CODE_TIMEOUT = 502;
152
}
153
```
154

155
[Context Management and Logging](./context-helpers.md)
156

157
### Distributed Communication
158

159
Remote procedure call interfaces and data models for admin-executor communication. Handles job triggering, status callbacks, and heartbeat monitoring.
160

161
```java { .api }
162
// Admin server communication
163
public interface AdminBiz {
164
    ReturnT<String> callback(List<HandleCallbackParam> callbackParamList);
165
    ReturnT<String> registry(RegistryParam registryParam);
166
    ReturnT<String> registryRemove(RegistryParam registryParam);
167
}
168

169
// Executor communication  
170
public interface ExecutorBiz {
171
    ReturnT<String> beat();
172
    ReturnT<String> idleBeat(IdleBeatParam idleBeatParam);
173
    ReturnT<String> run(TriggerParam triggerParam);
174
    ReturnT<String> kill(KillParam killParam);
175
    ReturnT<LogResult> log(LogParam logParam);
176
}
177

178
// Standard response wrapper
179
public class ReturnT<T> implements Serializable {
180
    public static final int SUCCESS_CODE = 200;
181
    public static final int FAIL_CODE = 500;
182
    public static final ReturnT<String> SUCCESS;
183
    public static final ReturnT<String> FAIL;
184
}
185
```
186

187
[Communication Interfaces and Models](./communication.md)
188

189
### Configuration and Utilities
190

191
Enums, constants, and utility classes for job execution strategies, script types, and system configuration.
192

193
```java { .api }
194
// Execution blocking strategies
195
public enum ExecutorBlockStrategyEnum {
196
    SERIAL_EXECUTION("Serial execution"),
197
    DISCARD_LATER("Discard Later"),
198
    COVER_EARLY("Cover Early");
199
    
200
    public String getTitle();
201
    public static ExecutorBlockStrategyEnum match(String name, ExecutorBlockStrategyEnum defaultItem);
202
}
203

204
// Supported script types
205
public enum GlueTypeEnum {
206
    BEAN, GLUE_GROOVY, GLUE_SHELL, GLUE_PYTHON, GLUE_PHP, GLUE_NODEJS, GLUE_POWERSHELL;
207
    
208
    public String getDesc();
209
    public boolean isScript();
210
    public static GlueTypeEnum match(String name);
211
}
212
```
213

214
[Configuration and Utilities](./configuration.md)
215

216
### Thread Management and Infrastructure
217

218
Core thread classes and infrastructure components for job execution, registration, callback handling, and embedded server management.
219

220
```java { .api }
221
// Core job execution thread
222
public class JobThread extends Thread {
223
    public ReturnT<String> pushTriggerQueue(TriggerParam triggerParam);
224
    public void toStop(String stopReason);
225
    public boolean isRunningOrHasQueue();
226
}
227

228
// Registry management thread
229
public class ExecutorRegistryThread {
230
    public static ExecutorRegistryThread getInstance();
231
    public void start(String adminAddresses, String accessToken, String appname, String address);
232
    public void toStop();
233
}
234

235
// Embedded HTTP server
236
public class EmbedServer {
237
    public void start(String address, int port, String appname, String accessToken) throws Exception;
238
    public void stop() throws Exception;
239
}
240
```
241

242
[Thread Management and Infrastructure](./thread-management.md)