Master XXL-Job: From Source Code to Scheduled Tasks in Spring Boot

To achieve more flexible control over scheduled jobs, the author adopted XXL-Job, a widely used open‑source scheduler built on Spring Boot, and shares a step‑by‑step experience.

XXL-Job Overview

Key features include lightweight design, easy extensibility, dynamic configuration, HA for both admin and executor, elastic scaling, multiple routing strategies, fault‑tolerance, blocking policies, timeout control, retry and alarm mechanisms, sharding, broadcast, and event triggers.

Downloading the Source

The project can be cloned from GitHub or Gitee: git clone [email protected]:xuxueli0323/xxl-job.git After cloning, open the project in an IDE; the default branch is 2.3.1‑SNAPSHOT. Switch to a stable tag such as 2.3.0 if desired:

git checkout -b 2.3.0 origin/2.3.0

Project Structure

xxl-job-admin – the scheduling console

xxl-job-core – shared dependencies

xxl-job-executor-samples – sample executors

xxl-job-executor-sample-springboot – Spring Boot‑based executor (recommended)

xxl-job-executor-sample-frameless – framework‑less version

During deployment, the admin console is run separately, while the sample code can be integrated into your own services.

Initializing the Database

Execute doc/db/tables_xxl_job.sql to create the xxl_job database and its eight tables.

Configuring the Application

In xxl-job-admin, edit application.properties to set the database URL, mail server, etc. The author split the file into profile‑specific files:

application.properties

application-dev.properties

application-prod.properties

application-test.properties

Activate a profile with:

spring.profiles.active=dev

Packaging and Launching

Run the Spring Boot main class directly from the IDE or build a JAR. The default logback.xml points to /data/applogs/xxl-job/xxl-job-admin.log, which may not exist; replace it with a local path or externalize the property:

<!--<property name="log.path" value="/data/applogs/xxl-job/xxl-job-admin.log"/>-->
<springProperty scope="context" name="log.path" source="log.path"/>

Then define the actual path in the profile file, e.g.: log.path=/Users/zzs/temp/xxl-job-admin.log After fixing the path, start the admin console (default URL http://localhost:8888/xxl-job-admin) with username admin and password 123456.

Writing an Executor

Add the core dependency to a Spring Boot project:

<dependency>
   <groupId>com.xuxueli</groupId>
   <artifactId>xxl-job-core</artifactId>
   <version>${project.parent.version}</version>
</dependency>

Create a bean with a method annotated by @XxlJob("helloXxlJobHandler"):

@Component
public class MyXxlJob {
    @XxlJob("helloXxlJobHandler")
    public void helloXxlJobHandler() {
        String jobParam = XxlJobHelper.getJobParam();
        System.out.println("jobParam=" + jobParam);
        System.out.println("Hello XXL-Job");
    }
}

Configure the executor to point to the admin address:

xxl.job.admin.addresses=http://localhost:8888/xxl-job-admin

Run the executor’s main method.

Managing Tasks via the Admin UI

Navigate to the “Task Management” section, click “Add Task”, fill in the parameters as described, and save. After execution, the scheduling log shows the run record, and the console prints:

jobParam=hello,xxl-job
Hello XXL-Job

The task’s frequency, routing rules, and parameters can be adjusted later through the same UI.

Conclusion

XXL-Job provides a powerful, web‑based interface for managing distributed scheduled jobs, offering features such as HA, dynamic configuration, and execution history that are far more flexible than hard‑coded cron jobs.