Integrating Spring Boot with XXL‑Job for Distributed Task Scheduling

Introduction

In modern applications, scheduled tasks are indispensable. This article demonstrates how to integrate Spring Boot with XXL‑Job to achieve efficient distributed task scheduling.

What is XXL‑Job

XXL‑Job is an open‑source Java‑based distributed task scheduling platform that provides a visual web UI, elastic scaling, task dependency management, retry mechanisms, and alerting.

Key Features

Distributed task scheduling : Handles tasks across multiple nodes.

Elastic expansion : Dynamically add or remove executor nodes.

Task scheduling center : Centralized management and monitoring of tasks.

Multiple task types : Supports simple cron jobs, Bean calls, Shell scripts, HTTP tasks, and GLUE (dynamic language) tasks.

Task dependency and failure retry : Configure execution order and automatic retries.

Alert and logging : Email/SMS alerts and detailed execution logs.

Open source and community support : Active community and extensibility.

Comparison with Other Schedulers

Compared with Quartz, Spring @Scheduled, Elastic‑Job, Akka Scheduler, and Cron4J, XXL‑Job offers easier distributed configuration, a richer web UI, built‑in alerting, and better support for large‑scale task management.

Integrating XXL‑Job with Spring Boot

Configure XXL‑Job Admin

Clone the source from Gitee or GitHub, execute the SQL script /xxl-job/doc/db/tables_xxl_job.sql , and modify the admin configuration file /xxl-job/xxl-job-admin/src/main/resources/application.properties . Example configuration:

### web, port (default 8080, changed to 9998)
server.port=9998
# Database connection
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

After configuration, access the admin console at http://127.0.0.1:9998/xxl-job-admin with the default credentials admin/123456 .

Configure the Executor

The cloned project already contains executor samples for both plain Java and Spring Boot. Add the Maven dependency to your project:

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

Configure the executor properties in application.properties :

# Admin address (optional)
xxl.job.admin.addresses=http://127.0.0.1:9998/xxl-job-admin
# Access token (must match admin)
xxl.job.accessToken=eyJhbGciOiJIUzI1NiJ9
# Executor app 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 lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@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:

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.");
    }
}

@XxlJob Annotation Parameters

The annotation supports three main attributes:

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

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

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

Best Practices

Log task execution details for troubleshooting.

Validate input parameters to avoid runtime errors.

Ensure idempotent task logic 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.

Perform thorough unit testing of task logic.

Deploy multiple executor nodes for high availability.

Keep the admin console secure and avoid storing sensitive data in task code.

Maintain up‑to‑date documentation and provide team training.

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