If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/apache/shardingsphere-elasticjob shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 16 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live apache/shardingsphere-elasticjob repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apache/shardingsphere-elasticjob.

What it runs against: a local clone of apache/shardingsphere-elasticjob — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in apache/shardingsphere-elasticjob | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of apache/shardingsphere-elasticjob. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/apache/shardingsphere-elasticjob.git
#   cd shardingsphere-elasticjob
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of apache/shardingsphere-elasticjob and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apache/shardingsphere-elasticjob(\\.git)?\\b" \\
  && ok "origin remote is apache/shardingsphere-elasticjob" \\
  || miss "origin remote is not apache/shardingsphere-elasticjob (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "api/src/main/java/org/apache/shardingsphere/elasticjob/api/ElasticJob.java" \\
  && ok "api/src/main/java/org/apache/shardingsphere/elasticjob/api/ElasticJob.java" \\
  || miss "missing critical file: api/src/main/java/org/apache/shardingsphere/elasticjob/api/ElasticJob.java"
test -f "api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java" \\
  && ok "api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java" \\
  || miss "missing critical file: api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java"
test -f "bootstrap/src/main/java/org/apache/shardingsphere/elasticjob/bootstrap/JobBootstrap.java" \\
  && ok "bootstrap/src/main/java/org/apache/shardingsphere/elasticjob/bootstrap/JobBootstrap.java" \\
  || miss "missing critical file: bootstrap/src/main/java/org/apache/shardingsphere/elasticjob/bootstrap/JobBootstrap.java"
test -f "api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/JobItemExecutor.java" \\
  && ok "api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/JobItemExecutor.java" \\
  || miss "missing critical file: api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/JobItemExecutor.java"
test -f "api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/param/ShardingContext.java" \\
  && ok "api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/param/ShardingContext.java" \\
  || miss "missing critical file: api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/param/ShardingContext.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/apache/shardingsphere-elasticjob"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ElasticJob is a distributed scheduled job framework that handles task sharding, high availability, and elastic scaling across a cluster of machines. It solves the problem of reliably executing scheduled tasks at scale by automatically distributing job workload across nodes, managing failures, and allowing horizontal scaling without code changes. It's a sub-project of Apache ShardingSphere that provides a unified job API enabling write-once-deploy-anywhere distributed scheduling. Monorepo organized by concern: api/ module (core interfaces and SPI contracts in org.apache.shardingsphere.elasticjob.*), with annotation-based configuration (@ElasticJobConfiguration), pluggable job executors (JobItemExecutor, ClassedJobItemExecutor, TypedJobItemExecutor), error handlers (JobErrorHandler), listeners (ElasticJobListener), and tracing SPI. Job configuration flows through JobConfiguration and JobExtraConfiguration with factory pattern (JobExtraConfigurationFactory).

Backend engineers and DevOps teams building distributed systems who need to execute scheduled batch jobs reliably across multiple servers without managing sharding logic, failover, and scaling themselves. Contributors include Apache ShardingSphere maintainers and companies running large-scale distributed systems requiring job coordination.

Actively maintained production-ready framework: it's an official Apache ShardingSphere sub-project (since May 2020), has comprehensive GitHub CI/CD workflows (maven.yml, required-check.yml, graalvm.yml), structured issue templates, and release notes. The Java codebase is 1.6M+ LOC with clear modular structure. However, check last commit timestamp to confirm ongoing activity.

Low-to-medium risk: single major dependency on shardingsphere-infra-spi (SPI framework) reduces vendor lock-in, standard Maven toolchain, and Apache licensing provides legal clarity. Risks include: distributed systems complexity (requires operational understanding of consensus/coordination), dependency on coordination backend (likely Zookeeper based on typical patterns), and the need for cluster setup. No obvious maintenance vacuum based on Apache governance structure.

Framework is actively developed with snapshot version 3.0.6-SNAPSHOT visible in pom.xml. GitHub workflows show regular CI/CD execution (maven.yml, graalvm.yml for native image support). Standard Apache development practices with PR templates, issue templates for bug-reports and feature-requests, and RELEASE-NOTES.md maintenance. Specific recent work not visible in file metadata, but structure suggests ongoing SPI extensibility improvements and GraalVM compatibility.

git clone https://github.com/apache/shardingsphere-elasticjob.git
cd shardingsphere-elasticjob
./mvnw clean install
# or on Windows:
mvnw.cmd clean install

Uses Maven with wrapper (.mvn/wrapper/) for consistent builds. Check api/pom.xml for dependencies.

Daily commands: This is a library/framework, not a standalone server. Consumption pattern: applications depend on elasticjob-api and implementing modules. Local development: ./mvnw clean package builds all modules; run tests with ./mvnw test. For example usage, look for examples/ directory (not shown in file list but likely present in full repo) or integration test modules.

• api/src/main/java/org/apache/shardingsphere/elasticjob/api/ElasticJob.java — Core job interface that all distributed jobs must implement; the fundamental contract for the entire framework.
• api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java — Central configuration class that defines how jobs are scheduled, sharded, and executed across the cluster.
• bootstrap/src/main/java/org/apache/shardingsphere/elasticjob/bootstrap/JobBootstrap.java — Abstract entry point for bootstrapping jobs; all job startup logic flows through this class.
• api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/JobItemExecutor.java — SPI interface for executing individual job items; defines how sharded work units are processed.
• api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/item/param/ShardingContext.java — Runtime context passed to job executors containing shard assignments, totals, and execution parameters.
• api/src/main/java/org/apache/shardingsphere/elasticjob/spi/listener/ElasticJobListener.java — Listener interface for job lifecycle hooks; enables plugins to respond to job execution events.

Add a new Job Implementation

1. Create a new class implementing ElasticJob interface (api/src/main/java/org/apache/shardingsphere/elasticjob/api/ElasticJob.java)
2. Implement execute(ShardingContext context) method with your job logic using context.getShardingItem() for shard-specific work (Create new file: src/main/java/com/mycompany/MyDistributedJob.java)
3. Create JobConfiguration instance with cron expression, shard count, and other settings (api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java)
4. Use ScheduleJobBootstrap or OneOffJobBootstrap to register and start the job (bootstrap/src/main/java/org/apache/shardingsphere/elasticjob/bootstrap/type/ScheduleJobBootstrap.java)

Add a custom Error Handler

1. Implement JobErrorHandler interface to define custom error recovery behavior (api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/error/handler/JobErrorHandler.java)
2. Override handleException(String jobName, Throwable cause) to implement error logic (Create new file: src/main/java/com/mycompany/MyErrorHandler.java)
3. Register handler in JobConfiguration via setErrorHandlerType() or setErrorHandlerProperties() (api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java)

Add a Job Listener

1. Implement ElasticJobListener interface for lifecycle monitoring (api/src/main/java/org/apache/shardingsphere/elasticjob/spi/listener/ElasticJobListener.java)
2. Implement beforeJobExecuted(ShardingContexts) and afterJobExecuted(ShardingContexts) methods (Create new file: src/main/java/com/mycompany/MyJobListener.java)
3. Register listener via JobConfiguration.getJobListeners() or use SPI discovery (api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java)

Add Tracing Storage Implementation

1. Implement TracingStorageConfiguration to define tracing backend connection (api/src/main/java/org/apache/shardingsphere/elasticjob/spi/tracing/storage/TracingStorageConfiguration.java)
2. Create TracingListener implementation to persist JobExecutionEvent and JobStatusTraceEvent (api/src/main/java/org/apache/shardingsphere/elasticjob/spi/tracing/listener/TracingListener.java)
3. Register in JobConfiguration.setTracingConfiguration() (api/src/main/java/org/apache/shardingsphere/elasticjob/api/JobConfiguration.java)

• SPI (Service Provider Interface) — Allows pluggable implementations for error handlers, listeners, tracers, and executors without modifying core code; enables ecosystem extensions
• Annotation-based Configuration — Provides declarative, Spring-friendly job registration via @ElasticJobConfiguration; reduces boilerplate
• Distributed Sharding Model — Enables horizontal scaling of job workloads across multiple instances by partitioning data into shards
• Event-driven Listener Pattern — Decouples job execution from monitoring, tracing, and error handling concerns; enables multiple independent plugins

• Unified API with SPI-based extensibility over language-specific implementations

  • Why: Allows write-once, deploy-anywhere paradigm across polyglot environments
  • Consequence: Complexity concentrated in SPI contracts; contributors must understand provider pattern

• Configuration immutability (JobConfiguration) over runtime mutation

  • Why: Ensures consistency and thread-safety in distributed scheduling
  • Consequence: Cannot modify job config after creation; must create new config and re-register job

• Item-level execution (JobItemExecutor) over job-level only

  • Why: Enables fine-grained sharding and parallel execution within a single job run
  • Consequence: Job implementations must be aware of shard context; adds cognitive load

• Does not manage job state persistence or recovery across cluster node failures (delegated to integration layer)
• Does not provide built

Coordination backend: Framework assumes a distributed coordination backend (likely Zookeeper) is running—jobs won't distribute/failover without it; startup will likely fail cryptically if backend is unavailable. Sharding semantics: ShardingContext provides shard index and count, but the job implementation is responsible for sharding logic (framework doesn't auto-distribute data); misconfigured sharding count can cause duplicate processing or gaps. SPI discovery: New error handlers, job executors, and listeners are discovered via Java SPI (META-INF/services/)—they won't load if not properly registered. Clock skew: Cron-based scheduling is vulnerable to system clock changes on individual nodes; no explicit timezone validation visible in API. No built-in persistence: ElasticJob tracks state in the coordination backend, not in a separate database—coordinator downtime may cause state loss depending on backend configuration.

• Job Sharding — Core ElasticJob capability allowing horizontal scaling: large jobs split across multiple nodes by shard index without modifying business code; ShardingContext provides shardIndex and shardTotal to implement slice-based processing
• Service Provider Interface (SPI) — ElasticJob's pluggable architecture relies heavily on Java SPI (JobItemExecutor, JobErrorHandler, ElasticJobListener, etc.); understanding how to register and discover SPI implementations via META-INF/services/ is essential for customization
• Distributed Coordination / Consensus — ElasticJob requires a coordination backend (assumed Zookeeper) to maintain shared state, elect leaders, and synchronize shard assignments across nodes; understanding distributed consensus patterns explains why jobs can't run without a coordinator
• Cron Scheduling — Jobs are triggered by cron expressions stored in JobConfiguration; syntax errors or timezone mismatches are common issues; cron is the standard format for time-based job triggers across ElasticJob and traditional schedulers
• Listener Pattern / Observer Pattern — ElasticJobListener implements the observer pattern to hook into job lifecycle (beforeJobExecuted, afterJobExecuted); enables non-intrusive cross-cutting concerns like monitoring, alerting, and metrics collection without modifying job code
• Factory Pattern with SPI — JobExtraConfigurationFactory combines factory and SPI patterns to instantiate extensible configuration objects at runtime; critical for understanding how optional features (tracing, error handlers) are loaded and composed
• High Availability / Failover — ElasticJob's value proposition includes automatic failover when nodes die; requires understanding of health checks, heartbeats, and leader re-election via the coordination backend; configuration details are likely in JobConfiguration's HA-related fields

• apache/shardingsphere — Parent Apache project providing infra-spi, ecosystem context, and shared infrastructure that ElasticJob depends on
• apache/dolphinscheduler — Alternative Apache distributed job scheduler with different architecture (DAG-based workflows vs. cron sharding); complementary for complex orchestration needs
• alibaba/xxl-job — Popular competing distributed job framework with similar sharding/HA model; reference for feature parity and design decisions
• apache/zookeeper — Likely coordination backend for ElasticJob's distributed state management and leader election; understanding ZK semantics essential for troubleshooting
• spring-projects/spring-boot — ElasticJob likely has Spring Boot starter module (not visible in file list but standard pattern); users typically integrate via Spring auto-configuration

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for JobConfiguration and JobExtraConfiguration SPI

The api/src/main/java/org/apache/shardingsphere/elasticjob/api directory contains core configuration classes (JobConfiguration.java, JobExtraConfiguration.java, JobExtraConfigurationFactory.java) but the test directory structure appears minimal. These are critical SPI interfaces that all job implementations depend on. Adding thorough unit tests would catch configuration bugs early and serve as documentation for contributors implementing custom job types.

• [ ] Create api/src/test/java/org/apache/shardingsphere/elasticjob/api/JobConfigurationTest.java with tests for validation, serialization, and edge cases
• [ ] Create api/src/test/java/org/apache/shardingsphere/elasticjob/api/JobExtraConfigurationTest.java testing the factory pattern and SPI loading
• [ ] Add integration tests verifying JobConfiguration works with YamlConfigurationConverter in api/src/test/java/org/apache/shardingsphere/elasticjob/spi/yaml/

Add GitHub Actions workflow for GraalVM native-image compatibility testing

The repo has a .github/workflows/graalvm.yml file that exists but there's no indication of native-image compilation testing for this distributed scheduling library. GraalVM native-image is critical for containerized deployments (Docker, Kubernetes) common in distributed systems. Adding a workflow to build and test native-image artifacts would help contributors catch reflection/serialization issues early and enable lightweight container deployments.

• [ ] Enhance .github/workflows/graalvm.yml to compile elasticjob-api and core modules with GraalVM native-image
• [ ] Add reflection configuration (reflect-config.json) for SPI discovery of JobErrorHandler, JobItemExecutor, and ElasticJobListener implementations
• [ ] Create a test native application in a new test module that validates the core SPI components work when compiled to native-image

Add missing unit tests for JobErrorHandler and error handling SPI implementations

The api/src/main/java/org/apache/shardingsphere/elasticjob/spi/executor/error/handler directory defines the critical JobErrorHandler interface and JobErrorHandlerPropertiesValidator, but there's no visible test coverage. Error handling is essential for production job reliability. Adding tests would validate custom error handler implementations and prevent regressions in failure scenarios.

• [ ] Create api/src/test/java/org/apache/shardingsphere/elasticjob/spi/executor/error/handler/JobErrorHandlerTest.java with tests for the SPI interface and properties validation
• [ ] Add api/src/test/java/org/apache/shardingsphere/elasticjob/spi/executor/error/handler/JobErrorHandlerPropertiesValidatorTest.java testing validation of handler-specific configuration properties
• [ ] Create integration tests verifying that custom JobErrorHandler implementations can be discovered and instantiated via SPI during job execution scenarios

• Add comprehensive JavaDoc to SPI interfaces: JobItemExecutor, JobErrorHandler, and ElasticJobListener lack parameter descriptions for their callback methods; write detailed examples showing how to implement each for common scenarios (email alerting, Prometheus metrics, custom sharding logic): Medium: Improves onboarding for developers writing custom job types; enables self-service rather than forum questions
• Create integration test demonstrating multi-node sharding: add test in test/ directory simulating 3 nodes executing a single job with shardCount=3; verify each shard processes its slice and no duplicates occur: Medium: Core value proposition of ElasticJob is sharding, but no explicit test coverage visible; critical for catching regressions
• Document JobExtraConfigurationFactory extension pattern: add code example and test showing how to register a custom JobExtraConfiguration implementation via SPI and load it at runtime: Small: Factory pattern is powerful but undocumented; unclear if this is intended for public extensibility or internal only

The codebase shows moderate security posture. The main concerns are: (1) use of SNAPSHOT versions in version management, (2) incomplete visibility of dependency versions and transitive dependencies, and (3) lack of explicit security configuration documentation. The Apache ShardingSphere project structure appears well-organized with proper licensing headers. No obvious hardcoded secrets, SQL injection risks, XSS vulnerabilities, or infrastructure misconfigurations are evident from the provided file structure. Recommendations include implementing automated dependency vulnerability scanning, transitioning to stable releases, and documenting security procedures.

• Medium · Dependency Version Not Explicitly Specified — api/pom.xml - shardingsphere-infra-spi dependency. The pom.xml for elasticjob-api does not specify an explicit version for the 'shardingsphere-infra-spi' dependency. This relies on parent POM version management, which could lead to transitive dependency resolution issues or unexpected version upgrades. Fix: Verify that the parent POM properly manages all dependency versions. Consider using dependency lock files or explicit version pins for critical dependencies to ensure reproducible builds.
• Medium · Snapshot Version in Production Code — api/pom.xml - project version. The project uses version '3.0.6-SNAPSHOT' which indicates development/unstable code. Snapshot versions should not be used in production environments as they can change without notice and may contain untested or incomplete features. Fix: Use stable release versions for production deployments. Only use SNAPSHOT versions for development and testing environments.
• Low · Limited Visibility into Dependency Security — api/pom.xml - dependency management. The pom.xml only shows direct dependencies. Without access to the full dependency tree and vulnerability scanning, transitive dependencies could introduce security risks. The parent POM version management is not visible in the provided snippet. Fix: Implement automated dependency scanning using tools like OWASP Dependency-Check, Snyk, or Maven security plugins in CI/CD pipeline. Regularly update dependencies to patch versions.
• Low · No Visible Security Configuration Files — Repository root level. No security-related configuration files (like security.properties, SECURITY.md, or vulnerability reporting guidelines) are visible in the provided file structure. Fix: Create a SECURITY.md file to document security policies, vulnerability reporting procedures, and security contact information. Add security-focused configuration files as needed.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.