How Xxl-Job Powers Lightweight Distributed Task Scheduling in Java

Core Concepts

Xxl-Job consists of a Scheduler Center (a web service that triggers scheduled tasks) and one or more Executors (services that actually run the task logic). The Scheduler Center stores task definitions and schedules in a database and can run in cluster mode, sharing the same database among instances.

1. Scheduler Center

Provides a UI for managing task triggers and relies on a shared database for persistence. In a cluster, instances do not communicate directly; they coordinate through the database.

2. Executor

An Executor is a service instance that runs the actual job logic. Each Executor has a name (often the service name) and can host multiple tasks.

3. Job

A Job represents a specific piece of work. Multiple jobs can be defined within a single Executor.

The Scheduler Center controls when tasks are triggered, while the Executor executes the tasks, achieving a separation of trigger logic and execution.

Demo Setup

1. Build the Scheduler Center

Clone the source code:

https://github.com/xuxueli/xxl-job.git

Configure the database connection in

/doc/db

and run the project (as a JAR or directly from the IDE). Access the admin console at

http://localhost:8080/xxl-job-admin/toLogin

with default credentials

admin/123456

.

2. Add Executor and Task

Create an executor named

sanyou-xxljob-demo

and a task named

TestJob

with a cron expression that runs every second.

3. Code Example

<code>&lt;dependencies&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;
        &lt;version&gt;2.2.5.RELEASE&lt;/version&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;com.xuxueli&lt;/groupId&gt;
        &lt;artifactId&gt;xxl-job-core&lt;/artifactId&gt;
        &lt;version&gt;2.4.0&lt;/version&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;</code>

Configure the executor bean:

<code>@Configuration
public class XxlJobConfiguration {
    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
        executor.setAdminAddresses("http://localhost:8080/xxl-job-admin");
        executor.setAppname("sanyou-xxljob-demo");
        executor.setPort(9999);
        executor.setAccessToken("default_token");
        executor.setLogPath("./");
        return executor;
    }
}</code>

Define a job method using

@XxlJob

:

<code>@Component
public class TestJob {
    private static final Logger logger = LoggerFactory.getLogger(TestJob.class);

    @XxlJob("TestJob")
    public void testJob() {
        logger.info("TestJob任务执行了。。。");
    }
}</code>

When the demo runs, the task prints the log message every second.

Executor Startup Details

The executor entry point is

XxlJobSpringExecutor

, which implements

SmartInitializingSingleton

. During bean initialization it performs three key actions:

Initialize JobHandlers by scanning Spring beans annotated with

@XxlJob

and registering them in a local cache.

Create an HTTP server (based on Netty) on the configured port to receive requests from the Scheduler Center.

Start a registration thread that reports the executor’s name, IP, and port to the Scheduler Center.

JobHandler Types

MethodJobHandler – invokes a Java method via reflection.

GlueJobHandler – allows dynamic modification of Java code through the GLUE IDE.

ScriptJobHandler – executes scripts (e.g., shell, Python).

Task Triggering Mechanism

The Scheduler Center runs a scheduling thread that queries the

xxl_job_info

table for tasks whose next trigger time is within the next 5 seconds. It classifies tasks into three groups based on how far the trigger time is from the current time and applies the configured expiration strategy (ignore or fire immediately).

To ensure only one Scheduler instance triggers a task in a clustered environment, a database row lock is acquired with:

select * from xxl_job_lock where lock_name = 'schedule_lock' for update

If the lock is obtained, the instance proceeds with scheduling.

Fast/Slow Thread Pools

Triggering involves HTTP calls to executors, which can be slow. The Scheduler records the latency of each trigger; tasks that exceed 500 ms more than ten times in a minute are moved to a slow thread pool to avoid blocking faster tasks.

Executor Selection (Routing Strategies)

When multiple executor instances exist, the Scheduler chooses one based on the configured routing strategy (first, last, round‑robin, random, consistent hash, LFU, LRU, failover, busy‑overload, or shard‑broadcast). Shard‑broadcast splits the workload across all instances.

Executor Task Execution

Upon receiving a trigger request, the executor creates a

JobThread

for the task. The thread pulls the job from an in‑memory queue, ensuring isolation between tasks. If the selected executor is already busy, the Scheduler’s blocking strategy (serial, discard, or cover) determines how to handle the new trigger.

Result Callback

After execution, the

JobThread

places the result into a queue. A dedicated

TriggerCallbackThread

batches these results and sends them back to the Scheduler Center, which updates the task status and handles retries or downstream jobs.

Conclusion

Xxl-Job provides a simple yet powerful architecture for distributed task scheduling, with clear separation of scheduling and execution, flexible routing, and robust handling of latency and concurrency.