Integrating Spring Boot with XXL‑Job for Distributed Task Scheduling

Introduction

In modern applications, scheduled tasks are essential. Combining Spring Boot with XXL‑Job offers a powerful solution for simplifying task scheduling and management across distributed systems.

1. Overview of XXL‑Job

XXL‑Job is an open‑source distributed task scheduling platform built on Java, providing a web UI for configuring, monitoring, and managing tasks. Key features include distributed scheduling, elastic scaling, a central scheduling console, multiple task types, dependency handling, retry mechanisms, alerts, and active community support.

Comparison with Other Schedulers

Quartz : Requires extra configuration for distributed environments; XXL‑Job offers easier setup and richer UI.

Spring @Scheduled : Suitable for single‑node apps; XXL‑Job supports multi‑node execution and advanced features.

Elastic Job : Similar distributed capabilities but lacks XXL‑Job's visual management.

Akka Scheduler : More complex; XXL‑Job provides a simpler web‑based approach.

Cron4J : Lightweight for simple tasks; XXL‑Job adds dependency, retry, and monitoring.

2. Integrating XXL‑Job with Spring Boot

Configure XXL‑Job Admin

Clone the XXL‑Job source from Gitee or GitHub, import the project, and execute the provided SQL script /xxl-job/doc/db/tables_xxl_job.sql to create the database schema.

Modify /xxl-job/xxl-job-admin/src/main/resources/application.properties to set the server port, database connection, and access token:

### web, port (default 8080)
server.port=9998
# Database configuration
spring.datasource.url=jdbc:mysql://127.0.0.1:3361/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=123456

### XXL‑Job access token (must match executor)
xxl.job.accessToken=eyJhbGciOiJIUzI1NiJ9

Update the log path in /xxl-job/xxl-job-executor-samples/xxl-job-executor-sample-springboot/src/main/resources/logback.xml if necessary.

Start the admin console at http://127.0.0.1:9998/xxl-job-admin using the default credentials admin/123456 .

Configure the Executor

The cloned project already contains executor samples, including a Spring Boot version. Add the following Maven dependency to your own project:

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

Configure executor properties in application.properties :

# Admin address (optional for auto‑registration)
xxl.job.admin.addresses=http://127.0.0.1:9998/xxl-job-admin
# Access token (must match admin)
xxl.job.accessToken=eyJhbGciOiJIUzI1NiJ9
# Executor name
xxl.job.executor.appname=xxl-job-executor-xiaobo
# Executor port (default 9999)
xxl.job.executor.port=9999
# Log path and retention
xxl.job.executor.logpath=./logs/xxl-job/jobhandler
xxl.job.executor.logretentiondays=30

Create a configuration class to instantiate XxlJobSpringExecutor :

package com.todoitbo.baseSpringbootDasmart.config;

import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import lombok.extern.slf4j.Slf4j;

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

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

Define a job handler using the @XxlJob annotation:

package com.todoitbo.baseSpringbootDasmart.handler;

import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.springframework.stereotype.Component;

@Component
public class JobHandler {
    @XxlJob("demoJobHandler")
    public void demoJobHandler() throws Exception {
        XxlJobHelper.log("XXL‑JOB, Hello World.");
    }
}

Parameter Details of @XxlJob

value (String): Unique job name used in the admin console.

init (String): Method executed once before the first job run for initialization.

destroy (String): Method executed after the final job run for cleanup.

3. Best Practices

Log task execution details for troubleshooting.

Validate input parameters to avoid runtime errors.

Ensure job idempotency to handle retries safely.

Configure failure handling strategies (retry count, interval).

Set up task dependencies correctly in the admin UI.

Leverage dynamic scheduling for real‑time adjustments.

Integrate monitoring and alerting systems.

Use version control for job handler code.

Consider clustering executors for high availability.

Keep XXL‑Job updated to benefit from new features and bug fixes.

Secure the admin console and avoid storing sensitive data in job logic.

Following these guidelines helps build a reliable, maintainable, and scalable task scheduling system using Spring Boot and XXL‑Job.