XXL-JOB Mastery: A Step-by-Step Spring Boot Guide to Distributed Scheduling

1. xxl-job

xxl-job is a lightweight distributed task scheduling framework originated from Meituan‑Dianping. It uses a central scheduling platform, MySQL for persistence, DB locks for consistency, and provides a convenient monitoring page with email alerts. Compared with ElasticJob (which relies on ZooKeeper and a decentralized design), xxl-job is currently more popular on GitHub.

ElasticJob, created by Dangdang, targets high‑concurrency scenarios and uses ZooKeeper for leader election, offering strong scalability and availability.

2. Running xxl-job

Clone the repository https://github.com/xuxueli/xxl-job and open it in IDEA. The project contains four main directories: doc (documentation), xxl-job-admin (admin console), xxl-job-core (core code), and xxl-job-executor-samples (sample executors).

Import the SQL script doc/db/tables_xxl_job.sql into MySQL to create the required tables.

Update xxl-job-admin/src/main/resources/application.properties with your database connection:

spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=123
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

Modify the log path in xxl-job-admin/src/main/resources/logback.xml to a relative location (e.g., ./applogs/xxl-job/xxl-job-admin.log) so it works on Windows or macOS.

Start the xxl-job-admin Spring Boot application and open the login page at http://localhost:8080/xxl-job-admin/toLogin. The default credentials are admin/123456.

3. Developing scheduled tasks

3.1 Project creation and configuration

Create a new Spring Boot project with the spring-boot-starter-web dependency. Add the xxl‑job core dependency:

<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.3.0</version>
</dependency>

Add a custom logback.xml (shown below) to the resources folder.

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false" scan="true" scanPeriod="1 seconds">
    <property name="log.path" value="./applogs/xxl-job/xxl-job-executor-sample-springboot.log"/>
    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} %contextName [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    <appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${log.path}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${log.path}.%d{yyyy-MM-dd}.zip</fileNamePattern>
        </rollingPolicy>
        <encoder>
            <pattern>%date %level [%thread] %logger{36} [%file : %line] %msg%n</pattern>
        </encoder>
    </appender>
    <root level="info">
        <appender-ref ref="console"/>
        <appender-ref ref="file"/>
    </root>
</configuration>

Configure application.properties for the executor:

# web port
server.port=8089

# logging
logging.config=classpath:logback.xml

# admin address
xxl.job.admin.addresses=http://127.0.0.1:8080/xxl-job-admin

# access token (optional)
xxl.job.accessToken=

# executor settings
xxl.job.executor.appname=xxl-job-demo
xxl.job.executor.address=
xxl.job.executor.ip=
xxl.job.executor.port=9999
xxl.job.executor.logpath=./applogs/xxl-job/jobhandler
xxl.job.executor.logretentiondays=30

Create a configuration class to expose XxlJobSpringExecutor as a bean:

@Configuration
public class XxlJobConfig {
    private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);

    @Value("${xxl.job.admin.addresses}")
    private String adminAddresses;
    @Value("${xxl.job.accessToken}")
    private String accessToken;
    @Value("${xxl.job.executor.appname}")
    private String appname;
    @Value("${xxl.job.executor.address}")
    private String address;
    @Value("${xxl.job.executor.ip}")
    private String ip;
    @Value("${xxl.job.executor.port}")
    private int port;
    @Value("${xxl.job.executor.logpath}")
    private String logPath;
    @Value("${xxl.job.executor.logretentiondays}")
    private int logRetentionDays;

    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        logger.info(">>>>>>>>>>>> xxl-job config init.");
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
        executor.setAdminAddresses(adminAddresses);
        executor.setAppname(appname);
        executor.setAddress(address);
        executor.setIp(ip);
        executor.setPort(port);
        executor.setAccessToken(accessToken);
        executor.setLogPath(logPath);
        executor.setLogRetentionDays(logRetentionDays);
        return executor;
    }
}

3.2 Task development methods

3.2.1 Bean mode (class)

Implement com.xxl.job.core.handler.IJobHandler in a class, then register it manually:

XxlJobExecutor.registJobHandler("demoJobHandler", new DemoJobHandler());

Create the task in the admin console and bind it to the registered handler.

3.2.2 Bean mode (method)

Define a Spring bean method annotated with @XxlJob("demoJobHandler"):

@Component
public class MyJob {
    @XxlJob("demoJobHandler")
    public ReturnT<String> demoJobHandler() throws Exception {
        String param = XxlJobHelper.getJobParam();
        XxlJobHelper.log("XXL-JOB, Hello World：{}", param);
        return ReturnT.SUCCESS;
    }
}

Use XxlJobHelper.getJobParam() to read parameters and XxlJobHelper.log() to write logs. After deploying, configure a task in the admin console, select BEAN mode, set the JobHandler name to demoJobHandler, and start the task.

3.2.3 GLUE mode (Java)

In the admin console, create a new task and choose “GLUE mode (Java)”. The task code can be edited directly in the Web IDE, saved, and executed without a separate JobHandler class. The interface also supports version rollback for up to 30 previous versions.

4. Summary

xxl-job offers a simple, MySQL‑based distributed scheduling solution that is easy to set up and integrate with Spring Boot. Give it a try if you need a lightweight scheduler for Java applications.