apache/seatunnel

[Docs][Core] Add Javadoc to CoordinatorService (scheduling and HA methods)

Open

#10544 opened on Feb 28, 2026

View on GitHub
 (3 comments) (0 reactions) (1 assignee)Java (6,897 stars) (1,432 forks)batch import
help wanted

Description

Sub-issue of #10533

Scope

CoordinatorService is the Zeta master-node coordinator: it schedules pending jobs, handles master failover, and manages JobMaster lifecycle. The job scheduling and HA restoration methods have no Javadoc despite being the most critical for understanding Zeta's reliability model.

File

seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/CoordinatorService.java

Methods to document

Method Line What to explain
startPendingJobScheduleThread() 227 Background thread purpose; loop structure; exception handling and restart policy
pendingJobSchedule() 250 Peek-then-consume pattern on PendingJobQueue; resource pre-check before dequeue; PendingSourceState.RESTORE vs SUBMIT semantics
completeFailJob(JobMaster, ...) 334 Why insufficient-resource failures are handled separately from runtime failures
restoreAllRunningJobFromMasterNodeSwitch() 449 Master HA failover: iterates runningJobInfoIMap to reconstruct JobMaster for each in-flight job
restoreJobFromMasterActiveSwitch(Long, JobInfo) 506 Per-job restore path during master switch; difference from normal job submission
checkNewActiveMaster() 539 Hazelcast master-node detection; triggers initCoordinatorService on promotion
clearCoordinatorService() 566 Graceful shutdown ordering: cancels running jobs, shuts down executors, clears IMaps

How to contribute

  1. Fork the repo and create a branch
  2. Add Javadoc to the methods above
  3. Run ./mvnw spotless:apply and ./mvnw -q -DskipTests verify
  4. Open a PR with title: [Docs][Core] Add Javadoc to CoordinatorService scheduling and HA methods

Contributor guide

Tech stack
java
Domain
documentationbackend
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
blocked
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
JavaMavenSeaTunnel basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Refer to the CoordinatorService.java file at seatunnel engine/seatunnel engine server/src/main/java/org/apache/seatunnel/engine/server/CoordinatorService.java. Follow the provided table to add Javadoc for methods including startPendingJobScheduleThread(), pendingJobSchedule(), completeFailJob(), restoreAllRunningJobFromMasterNodeSwitch(), restoreJobFromMasterActiveSwitch(), checkNewActiveMaster(), and clearCoordinatorService(). Check sub issue #10533 for broader context. Run `./mvnw spotless:apply` and `./mvnw q DskipTests verify` before opening a PR.