tessl/maven-com-xuxueli--xxl-job-core

A distributed task scheduling framework core library for Java applications

—

Pending

Overview

Eval results

Files

Job Handlers and Annotations

Name: tessl/maven-com-xuxueli--xxl-job-core
Author: tessl

Core job definition system using annotations and handler interfaces. Provides the foundation for creating executable job units that can be scheduled and triggered by the XXL-Job admin system.

Capabilities

@XxlJob Annotation

Primary annotation for marking methods as job handlers with automatic discovery by the Spring executor.

/**
 * Marks a method as a job handler for XXL-Job scheduling
 * @param value - Job handler name (required, used for job registration)
 * @param init - Init method name (optional, called when JobThread initializes)
 * @param destroy - Destroy method name (optional, called when JobThread destroys)
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface XxlJob {
    String value();
    String init() default "";
    String destroy() default "";
}

Usage Examples:

import com.xxl.job.core.handler.annotation.XxlJob;
import com.xxl.job.core.context.XxlJobHelper;
import org.springframework.stereotype.Component;

@Component
public class SampleJobHandler {

    // Basic job handler
    @XxlJob("basicJob")
    public void basicJobHandler() throws Exception {
        String param = XxlJobHelper.getJobParam();
        XxlJobHelper.log("Executing basic job with param: {}", param);
        
        // Job logic here
        
        XxlJobHelper.handleSuccess();
    }

    // Job with lifecycle methods
    @XxlJob(value = "lifecycleJob", init = "initMethod", destroy = "cleanupMethod")
    public void lifecycleJobHandler() throws Exception {
        XxlJobHelper.log("Lifecycle job executing");
        XxlJobHelper.handleSuccess();
    }
    
    public void initMethod() {
        XxlJobHelper.log("Job initialization");
    }
    
    public void cleanupMethod() {
        XxlJobHelper.log("Job cleanup");
    }

    // Sharded job example
    @XxlJob("shardedJob")
    public void shardedJobHandler() throws Exception {
        int shardIndex = XxlJobHelper.getShardIndex();
        int shardTotal = XxlJobHelper.getShardTotal();
        
        XxlJobHelper.log("Processing shard {} of {}", shardIndex, shardTotal);
        
        // Process only data for this shard
        for (int i = shardIndex; i < dataList.size(); i += shardTotal) {
            // Process dataList.get(i)
        }
        
        XxlJobHelper.handleSuccess();
    }
}

IJobHandler Abstract Class

Base abstract class for creating custom job handlers when annotation-based approach is not suitable.

/**
 * Base abstract class for job handlers
 * Provides lifecycle methods for job execution
 */
public abstract class IJobHandler {
    /**
     * Execute the job handler
     * Must be implemented by subclasses
     * @throws Exception if job execution fails
     */
    public abstract void execute() throws Exception;
    
    /**
     * Initialize the job handler
     * Called when JobThread is created
     * @throws Exception if initialization fails
     */
    public void init() throws Exception {
        // Default empty implementation
    }
    
    /**
     * Cleanup the job handler
     * Called when JobThread is destroyed
     * @throws Exception if cleanup fails
     */
    public void destroy() throws Exception {
        // Default empty implementation
    }
}

Usage Examples:

import com.xxl.job.core.handler.IJobHandler;
import com.xxl.job.core.context.XxlJobHelper;

// Custom job handler implementation
public class CustomJobHandler extends IJobHandler {
    
    private SomeService service;
    
    @Override
    public void init() throws Exception {
        // Initialize resources
        service = new SomeService();
        XxlJobHelper.log("CustomJobHandler initialized");
    }
    
    @Override
    public void execute() throws Exception {
        try {
            String param = XxlJobHelper.getJobParam();
            XxlJobHelper.log("Processing with param: {}", param);
            
            // Execute job logic
            service.processData(param);
            
            XxlJobHelper.handleSuccess("Job completed successfully");
        } catch (Exception e) {
            XxlJobHelper.log(e);
            XxlJobHelper.handleFail("Job failed: " + e.getMessage());
        }
    }
    
    @Override
    public void destroy() throws Exception {
        // Cleanup resources
        if (service != null) {
            service.close();
        }
        XxlJobHelper.log("CustomJobHandler destroyed");
    }
}

// Register custom handler programmatically
XxlJobExecutor.registJobHandler("customJobHandler", new CustomJobHandler());

Method Job Handler Implementation

Internal implementation used by the framework for @XxlJob annotated methods.

/**
 * Internal job handler implementation for annotated methods
 * Used by the framework to wrap @XxlJob annotated methods
 */
public class MethodJobHandler extends IJobHandler {
    // Framework internal - not for direct use
}

Script Job Handler Implementation

Implementation for dynamic script-based job execution supporting multiple scripting languages.

/**
 * Job handler for script-based job execution
 * Supports Groovy, Shell, Python, PHP, Node.js, PowerShell
 */
public class ScriptJobHandler extends IJobHandler {
    // Framework internal - scripts managed through admin interface
}

Glue Job Handler Implementation

Implementation for dynamically loaded job code ("glue" jobs) that can be updated at runtime.

/**
 * Job handler for glue-type jobs
 * Allows runtime code updates without redeployment
 */
public class GlueJobHandler extends IJobHandler {
    // Framework internal - glue code managed through admin interface
}

Job Handler Registration

Automatic Registration (Spring)

When using XxlJobSpringExecutor, all @XxlJob annotated methods in Spring beans are automatically discovered and registered:

@Configuration
public class XxlJobConfig {
    
    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
        // Configuration...
        return executor;
        // All @XxlJob methods automatically registered on startup
    }
}

Manual Registration (Standalone)

For non-Spring environments, register job handlers manually:

// Register IJobHandler implementations
XxlJobExecutor.registJobHandler("myJobHandler", new MyJobHandler());

// For XxlJobSimpleExecutor, provide bean list
XxlJobSimpleExecutor executor = new XxlJobSimpleExecutor();
List<Object> jobBeans = Arrays.asList(new MyJobHandlerBean());
executor.setXxlJobBeanList(jobBeans);

Job Handler Best Practices

Error Handling

@XxlJob("robustJob")
public void robustJobHandler() throws Exception {
    try {
        String param = XxlJobHelper.getJobParam();
        
        // Validate parameters
        if (param == null || param.trim().isEmpty()) {
            XxlJobHelper.handleFail("Job parameter is required");
            return;
        }
        
        // Execute job logic with proper error handling
        processData(param);
        
        XxlJobHelper.handleSuccess("Job completed successfully");
        
    } catch (BusinessException e) {
        XxlJobHelper.log("Business error: {}", e.getMessage());
        XxlJobHelper.handleFail("Business error: " + e.getMessage());
    } catch (Exception e) {
        XxlJobHelper.log(e);
        XxlJobHelper.handleFail("Unexpected error: " + e.getMessage());
    }
}

Parameter Processing

@XxlJob("parameterizedJob")
public void parameterizedJobHandler() throws Exception {
    String param = XxlJobHelper.getJobParam();
    
    // Parse JSON parameters
    ObjectMapper mapper = new ObjectMapper();
    JobParams params = mapper.readValue(param, JobParams.class);
    
    XxlJobHelper.log("Processing with params: startDate={}, endDate={}", 
                     params.getStartDate(), params.getEndDate());
                     
    // Use parameters in job logic
    processDateRange(params.getStartDate(), params.getEndDate());
    
    XxlJobHelper.handleSuccess();
}

Logging and Monitoring

@XxlJob("monitoredJob")
public void monitoredJobHandler() throws Exception {
    long startTime = System.currentTimeMillis();
    XxlJobHelper.log("Job started at {}", new Date());
    
    try {
        // Job logic with progress logging
        int totalItems = getItemCount();
        XxlJobHelper.log("Processing {} items", totalItems);
        
        for (int i = 0; i < totalItems; i++) {
            processItem(i);
            
            // Log progress periodically
            if (i % 100 == 0) {
                XxlJobHelper.log("Processed {}/{} items", i, totalItems);
            }
        }
        
        long duration = System.currentTimeMillis() - startTime;
        XxlJobHelper.handleSuccess("Processed " + totalItems + " items in " + duration + "ms");
        
    } catch (Exception e) {
        long duration = System.currentTimeMillis() - startTime;
        XxlJobHelper.log("Job failed after {}ms: {}", duration, e.getMessage());
        XxlJobHelper.handleFail(e.getMessage());
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-com-xuxueli--xxl-job-core

docs