Mastering Distributed Scheduling with XXL‑JOB: A Hands‑On Tutorial

Scheduled task overview

Scheduled tasks execute at a fixed time point or at regular intervals (e.g., nightly data aggregation, SMS sending). Common Java implementations include While+Sleep , Timer/TimerTask , ScheduledExecutorService , Quartz , Spring Task and SpringBoot @Scheduled , each with distinct capabilities and limitations.

Problems of centralized scheduling

High traffic can exceed the capacity of a single node.

In a multi‑machine deployment the same task may be triggered multiple times.

Task timing often needs to be adjusted dynamically (pause, resume).

Failure of a machine must not make the task unavailable (failover required).

Execution logs need to be observable for monitoring.

XXL‑JOB

XXL‑JOB is an open‑source distributed task scheduler launched in 2015. Design goals are rapid development, simplicity, lightweight footprint and easy scalability. Core capabilities are:

Simple – Web UI for CRUD operations; onboarding within one minute.

Dynamic – Real‑time start/stop, status changes and termination of running tasks.

Scheduler HA – Central scheduler built on a Quartz cluster; executor HA via clustered deployment.

Elastic scaling – New executors are auto‑detected and tasks are re‑balanced on the next schedule.

Routing strategies – First, last, round‑robin, random, consistent‑hash, least‑used, most‑idle, failover, busy‑transfer, etc.

Failover – If an executor fails, the request is automatically rerouted.

Failure alerts – Email alerts by default; extensible to SMS, DingTalk, etc.

Source code: https://github.com/xuxueli/xxl-job/tree/v2.0.0

Architecture

XXL‑JOB consists of two modules:

Scheduler (Admin) – Manages scheduling metadata, issues dispatch requests, provides visual management, real‑time updates, monitoring and failover support. It does not contain business logic.

Executor – Receives dispatch requests, runs the JobHandler implementation and reports results.

Scheduler high availability

Implemented with a MySQL‑backed cluster. All nodes write task locks to the xxl_job_lock table; only the node whose lock name and trigger time match acquires the lock and executes the task.

Parallel dispatch

Dispatches are performed by a thread pool to avoid single‑thread bottlenecks. Different tasks can run in parallel; the same task runs concurrently on multiple executors but serially on a single executor.

Executor high availability

When executors are clustered, the scheduler discovers all online instances (e.g., 127.0.0.1:9997,127.0.0.1:9998,127.0.0.1:9999) and applies the selected routing strategy.

Installation

Admin module

Clone the source: git clone https://github.com/xuxueli/xxl-job (or use the Gitee mirror).

Import the project into IDEA.

Execute the SQL script /xxl-job/doc/db/tables_xxl_job.sql to create the scheduling database (default name xxl_job).

Edit

/xxl-job/xxl-job-admin/src/main/resources/application.properties

. Important properties:

server.port=8080
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=your_password
spring.mail.host=smtp.qq.com
spring.mail.port=25
[email protected]
spring.mail.password=mail_auth_code
xxl.job.accessToken=
xxl.job.i18n=zh_CN
xxl.job.triggerpool.fast.max=200
xxl.job.triggerpool.slow.max=100
xxl.job.logretentiondays=30

Start the admin application with XxlJobAdminApplication#main.

Open a browser at http://localhost:8080/xxl-job-admin/toLogin (default credentials admin/123456).

Executor module (SpringBoot sample)

Use the sample project xxl-job-executor-sample-springboot (found under xxl-job-executor-samples).

Configure

/xxl-job-executor-samples/xxl-job-executor-sample-springboot/src/main/resources/application.properties

with the admin address, executor name and RPC port, e.g.:

xxl.job.admin.addresses=http://127.0.0.1:8080/xxl-job-admin
xxl.job.executor.appname=xxl-job-executor-sample
xxl.job.executor.port=9999
xxl.job.accessToken=
xxl.job.executor.logpath=/data/applogs/xxl-job/jobhandler
xxl.job.executor.logretentiondays=30

Create the executor bean (usually in a @Configuration class):

@Bean
public XxlJobSpringExecutor xxlJobExecutor() {
    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;
}

Define a job handler (Bean mode) in any Spring component:

@Component
public class SampleXxlJob {
    private static final Logger logger = LoggerFactory.getLogger(SampleXxlJob.class);

    @XxlJob("demoJobHandler")
    public ReturnT<String> demoJobHandler(String param) throws Exception {
        logger.info("XXL‑JOB, Hello World. param={}", param);
        return ReturnT.SUCCESS;
    }
}

Task creation and management

In the admin UI:

Add an executor: provide appName , address (IP:port of the executor RPC service) and choose the registration mode (automatic or manual).

Create a job: set the routing strategy (e.g., round‑robin), cron expression, JobHandler name (must match the @XxlJob value), execution mode (Bean or GLUE), alarm email and optional parameters.

Save and start the job; logs can be viewed from the UI or the executor’s log directory.

GLUE mode (Java)

GLUE allows editing the job code directly in the web IDE. The edited class implements IJobHandler and runs inside the executor process, eliminating the need to rebuild or redeploy the application.

Scheduler clustering

Run multiple admin instances on different ports (e.g., 18080 and 18081). Use Nginx to load‑balance them under a virtual host, for example www.jobs.com. Executors register to the virtual host, so the configuration only needs the virtual host address.

# Nginx upstream
upstream jobs {
    server localhost:18080;
    server localhost:18081;
}
server {
    listen 80;
    server_name www.jobs.com;
    location / { proxy_pass http://jobs/; }
}

Executor clustering

Deploy multiple executor instances with distinct xxl.job.executor.port values. Keep xxl.job.admin.addresses and xxl.job.executor.appname identical across the cluster. The admin UI lists all online executors, and tasks can be routed using strategies such as round‑robin, random or failover.

Sharding feature

When processing large data sets, XXL‑JOB can split the workload across executors. The framework provides XxlJobHelper.getShardIndex() and XxlJobHelper.getShardTotal() to obtain the current shard parameters. Example sharding job handler:

@XxlJob("sendMsgShardingHandler")
public void sendMsgShardingHandler() throws Exception {
    int total = XxlJobHelper.getShardTotal();
    int index = XxlJobHelper.getShardIndex();
    List<UserMobilePlan> list = (total == 1) ?
        userMobilePlanMapper.selectAll() :
        userMobilePlanMapper.selectByMod(index, total);
    // process list ...
}

In a benchmark with 2000+ rows, a single executor took ~20 s; with two executors the time dropped to ~10 s, demonstrating the speed‑up from sharding.

Conclusion

XXL‑JOB offers a comprehensive solution for distributed scheduling, including HA, dynamic routing, GLUE development and sharding. For small monolithic projects a lighter solution such as Quartz or SpringBoot @Scheduled may be more appropriate.