Comprehensive Guide to Using the XXL‑Job Distributed Task Scheduling Framework

XXL‑Job is a lightweight, open‑source distributed task scheduling framework that separates a management console (admin) from execution nodes (executors) and integrates seamlessly with Spring Boot projects.

Project introduction : The framework offers features such as dynamic task registration, real‑time logs, and support for various execution strategies.

Server deployment : Download the source from https://github.com/xuxueli/xxl-job , import the xxl-job-admin module into a new Spring Boot project, execute the provided table_xxl_job.sql script to create the required tables, and configure the database connection in application.properties . After building the project, start it and access the admin UI at http://localhost:8080/xxl-job-admin/ (default credentials admin/123456).

Executor configuration : Create a separate Spring Boot module for the executor, copy the xxl-job-executor-sample files, adjust logback.xml , and set the executor’s server.port and xxl.job.executor.port (e.g., 9998 and 9999) in application-9998.properties and application-9999.properties . Register the executor with the admin console using a matching appName .

Task development : Three common ways to create tasks are demonstrated:

Annotation‑based tasks – simply add @XxlJob("myJob") on a Spring bean method.

API‑based tasks – invoke the executor via the provided REST API.

Sharding (broadcast) tasks – configure multiple shards to run the same logic concurrently.

Task execution : In the admin UI, create a job, choose a routing strategy (e.g., round‑robin), set a CRON expression, and specify the handler name (e.g., myJobAnnotationHandler ). Execute the job manually to see real‑time logs and results.

Task logs : The platform records execution details, including parent‑child relationships, parameters, and console output, which can be viewed from the job’s log page.

Communication design : XXL‑Job uses Netty HTTP for communication (with optional Mina, Jetty, or TCP). The framework hides network details via dynamic proxies. The scheduler invokes the executor synchronously while the executor processes tasks asynchronously using a LinkedBlockingQueue . Key code snippets illustrate this flow:

public static ReturnT
runExecutor(TriggerParam triggerParam, String address) {
    ReturnT
runResult = null;
    try {
        ExecutorBiz executorBiz = XxlJobScheduler.getExecutorBiz(address);
        // Synchronous call that internally handles async processing
        runResult = executorBiz.run(triggerParam);
    } catch (Exception e) {
        logger.error("xxxxx xxl-job trigger error", address, e);
        runResult = new ReturnT<>(ReturnT.FAIL_CODE, ThrowableUtil.toString(e));
    }
    // Build result message
    StringBuffer runResultSB = new StringBuffer(I18nUtil.getString("jobconf_trigger_run") + "：");
    runResultSB.append("
address：").append(address);
    runResultSB.append("
code：").append(runResult.getCode());
    runResultSB.append("
msg：").append(runResult.getMsg());
    runResult.setMsg(runResultSB.toString());
    return runResult;
}

// Dynamic proxy invocation (synchronous call)
if (CallType.SYNC == callType) {
    XxlRpcFutureResponse futureResponse = new XxlRpcFutureResponse(invokerFactory, xxlRpcRequest, null);
    client.asyncSend(finalAddress, xxlRpcRequest);
    XxlRpcResponse xxlRpcResponse = futureResponse.get(timeout, TimeUnit.MILLISECONDS);
    if (xxlRpcResponse.getErrorMsg() != null) {
        throw new XxlRpcException(xxlRpcResponse.getErrorMsg());
    }
    return xxlRpcResponse.getResult();
}

The response is matched to the original request using a UUID request ID, ensuring the correct thread is notified when the executor returns the result.

Overall, the guide walks readers from initial project setup through advanced design concepts, providing practical code examples and visual screenshots to help developers quickly adopt XXL‑Job for reliable distributed task scheduling.