Getting Started with XXL‑Job: Installation, Configuration, and Developing Scheduled Tasks

Two days ago I wrote an article about ElasticJob, and many readers asked for a deeper dive into XXL‑Job, which is more widely used. XXL‑Job is a lightweight, distributed task‑scheduling framework from Meituan Dianping that relies on a central admin console and MySQL for coordination.

1. XXL‑Job Overview

XXL‑Job’s GitHub repository shows higher star counts than ElasticJob, indicating greater popularity. Unlike ElasticJob, which uses ZooKeeper for leader election, XXL‑Job uses a central admin server and DB locks, making it simpler to set up.

2. Running XXL‑Job

Clone the source code:

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

Open the project in IDEA; the main modules are doc , xxl-job-admin , xxl-job-core , and xxl-job-executor-samples .

Import the database script doc/db/tables_xxl_job.sql into MySQL to create the required tables.

Update the DB connection in xxl-job-admin/src/main/resources/application.properties :

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=123
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

Adjust the log path in xxl-job-admin/src/main/resources/logback.xml to a relative location:

<property name="log.path" value="./applogs/xxl-job/xxl-job-admin.log"/>

Start the admin console (a SpringBoot application) and access it at http://localhost:8080/xxl-job-admin/toLogin (default credentials: admin/123456 ).

3. Developing a Scheduled Task

Create a new SpringBoot project with Web dependency, then add the XXL‑Job core dependency:

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

Add a logback.xml configuration (see source) and the following application.properties settings:

# web port
server.port=8089

# logging config
logging.config=classpath:logback.xml

# admin address
xxl.job.admin.addresses=http://127.0.0.1:8080/xxl-job-admin

# executor name
xxl.job.executor.appname=xxl-job-demo
xxl.job.executor.port=9999
xxl.job.executor.logpath=./applogs/xxl-job/jobhandler
xxl.job.executor.logretentiondays=30

Define a configuration class that creates the XxlJobSpringExecutor bean (see source code).

@Configuration
public class XxlJobConfig {
    // ... fields injected with @Value ...
    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
        executor.setAdminAddresses(adminAddresses);
        executor.setAppname(appname);
        // ... other setters ...
        return executor;
    }
}

Two common ways to write a job handler:

Bean (class) mode : implement com.xxl.job.core.handler.IJobHandler and register with XxlJobExecutor.registJobHandler("demo", new DemoJobHandler()); .

Bean (method) mode (recommended): create a Spring component with a method annotated @XxlJob("demoJobHandler") . @Component public class MyJob { @XxlJob("demoJobHandler") public ReturnT demoJobHandler() throws Exception { String param = XxlJobHelper.getJobParam(); XxlJobHelper.log("XXL‑JOB, Hello World：{}", param); return ReturnT.SUCCESS; } }

GLUE (Java) mode : write the job code directly in the XXL‑Job web UI; the framework compiles and runs it without a separate class.

After the SpringBoot application starts, register the executor in the admin UI (Executor Management → Add). Then create a new job (Job Management → Add), select BEAN mode, set the JobHandler name to demoJobHandler , and configure a CRON expression (e.g., every 5 seconds).

Start the job and view execution logs in the UI; the custom log output appears in red boxes.

4. Summary

XXL‑Job provides a simple, MySQL‑based, centrally managed scheduling solution for Java applications. By following the steps above you can quickly set up the admin console, configure a SpringBoot executor, write Bean‑based or GLUE tasks, and monitor their execution through the web UI.