Practical Guide to Using XXL‑JOB for Distributed Task Scheduling with Spring Boot

What is XXL‑JOB?

XXL‑JOB is an open‑source distributed task scheduling platform designed for rapid development, simplicity, lightweight operation, and easy extensibility. It separates scheduling logic (the scheduler) from execution logic (the executor), allowing tasks to be defined as independent JobHandler components.

Why Use a Distributed Scheduler?

In a clustered environment, a single‑machine scheduler cannot guarantee task uniqueness, high availability, fault tolerance, or load balancing. XXL‑JOB solves these problems and competes with other solutions such as Quartz and Elastic‑Job.

Installing XXL‑JOB with Docker

docker pull xuxueli/xxl-job-admin:2.3.1

mkdir -p -m 777 /mydata/xxl-job/data/applogs

After creating /mydata/xxl-job/application.properties (omitted for brevity) and the required SQL script, run:

docker run -p 8088:8088 \
  -d --name=xxl-job-admin --restart=always \
  -v /mydata/xxl-job/application.properties:/application.properties \
  -v /mydata/xxl-job/data/applogs:/data/applogs \
  -e PARAMS='--spring.config.location=/application.properties' \
  xuxueli/xxl-job-admin:2.3.1

Verify with docker ps and access the UI at http:// host :8088/xxl-job-admin/ (default credentials: admin / 123456).

Integrating XXL‑JOB into a Spring Boot Project

Add the Maven dependency:

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

Configure the scheduler in application.yml with the admin address, executor name, IP, port, log path, and access token.

Create a configuration class that builds an XxlJobSpringExecutor bean using the injected properties.

Defining Custom Jobs

Use the @XxlJob annotation on a method to register a job handler, e.g.:

@Component
public class TestJob {
    @XxlJob("testHandler")
    public void testHandler() {
        XxlJobHelper.handleSuccess("Task executed successfully");
    }
}

Jobs can log via XxlJobHelper.log and set success or failure with handleSuccess / handleFail .

Real‑World Use Case: Video Transcoding

The article walks through a scenario where video files stored in MinIO need to be transcoded. Tasks are sharded across executors using the "sharding broadcast" strategy, and each executor obtains its slice via XxlJobHelper.getShardIndex() and getShardTotal() .

Optimistic‑lock SQL ensures only one executor processes a given record, providing idempotency. The job flow includes downloading the source file, transcoding with a utility, uploading the result back to MinIO, and updating the task status in the database.

int shardIndex = XxlJobHelper.getShardIndex();
int shardTotal = XxlJobHelper.getShardTotal();
List
list = mediaProcessService.getMediaProcessList(shardIndex, shardTotal, count);
// ... use CountDownLatch and thread pool to process each item ...

Additional scheduled jobs clean up completed records, move them to a history table, and implement a compensation mechanism for tasks that remain in "processing" state for too long.

Conclusion

The guide demonstrates end‑to‑end setup of XXL‑JOB, from Docker deployment to Spring Boot integration, sharding, idempotent processing, and a concrete video‑transcoding example, showing how distributed scheduling can improve reliability and throughput in real applications.