API Reference Overview

Ratchet's public API is organized into two packages: run.ratchet.api for the user-facing API, and run.ratchet.spi for extension points. This page provides a complete index and explains how the pieces fit together.

Package Structure

run.ratchet.api: User-Facing API

Classes and interfaces you use directly when scheduling jobs, building workflows, and observing events.

Class / Interface	Kind	Purpose
JobSchedulerService	Interface	Primary entry point for scheduling, canceling, pausing, and retrying jobs
JobQueryService	Interface	Read-only dashboards/admin API for job lists, detail views, history, and queue health
ClusterQueryService	Interface	Read-only sibling of JobQueryService for observing the scheduler node roster
JobBuilder	Interface	Fluent builder for configuring individual jobs before submission
RecurringJobBuilder	Interface	Builder for configuring recurring (cron-based) jobs
BatchBuilder	Interface	Builder for in-memory batch processing of collections
StreamingBatchBuilder	Interface	Builder for memory-efficient streaming batch processing
JobContext	Final class	Thread-local access to job ID, job-scoped logger binding, and parameters during execution
SignalDecision	Record	Structured approval/rejection payload for signal-waiting jobs
JobResult<T>	Class	Captures execution outcome: success/failure, return value, timing, metadata
JobHandle	Interface	Lightweight receipt returned after job submission, provides the job ID
JobOptions	Record	Immutable configuration for priority, retries, backoff, and timeout
JobFilter	Record	Immutable query criteria for list/search operations
JobPage<T>	Record	Page metadata and cursor returned by query operations
JobSummary / JobDetail	Records	Lightweight and full read-only job projections
NodeStatus	Record	Point-in-time view of a scheduler node's heartbeat state, liveness, and identity
WorkflowCondition	Record	Defines conditions for workflow branching (success, failure, custom, batch)
WorkflowBranch	Record	Pairs a condition with a task and optional description
BatchContext	Record	Progress snapshot for batch jobs (total, completed, failed items)
StreamingBatchContext	Record	Progress snapshot during the streaming phase of batch construction
JobPriority	Enum	Priority levels: LOWEST, LOW, NORMAL, HIGH, CRITICAL
BackoffPolicy	Enum	Retry delay strategies: NONE, FIXED, EXPONENTIAL
JobType	Enum	Job categories: SINGLE, RECURRING, BATCH, CHAIN, WORKFLOW, SYSTEM
CircuitBreakerProfile	Enum	Pre-configured circuit breaker profiles: DEFAULT, FAST, CRITICAL, EXTERNAL_API, CLAIM_PATH

run.ratchet.api: Annotations

Annotation	Target	Purpose
@Recurring	Method	Declares a method as a cron-scheduled recurring job
@CircuitBreakerProtected	Type, Method	Wraps invocations through the ResilienceStrategy circuit breaker
@DoNotRetry	Type	Marks exception classes that should never be retried
@Incubating	Any	Marks experimental APIs that may change without deprecation

run.ratchet.api: Functional Interfaces

Interface	Signature	Purpose
SerializableCheckedRunnable	void run() throws Exception	Primary job task definition
SerializableConsumer<T>	void accept(T t)	Success callbacks, progress hooks
SerializableBiConsumer<T,U>	void accept(T t, U u)	Failure callbacks (context + error)
SerializableFunction<T,R>	R apply(T t)	Value-based workflow conditions
SerializablePredicate<T>	boolean test(T t)	Custom workflow conditions
SerializableCheckedConsumer<T>	void accept(T t) throws Exception	Streaming batch item processing

run.ratchet.api.event: Event Types

Event	Fires When
JobStartedEvent	Job begins execution
JobCompletedEvent	Job completes successfully
JobFailedEvent	Job reaches terminal FAILED state
JobRetryingEvent	Job is being retried
JobExecutionTimedOutEvent	Running job exceeds its execution timeout
JobCancelledEvent	Job cancellation confirmed
JobPausedEvent	Job paused
JobResumedEvent	Job resumed
JobDlqEvent	Job moved to dead letter queue
JobSignalWaitingEvent	Job created in WAITING state for a named signal
JobSignaledEvent	Signal delivered to a waiting job
JobSignalTimedOutEvent	Waiting job exceeded its signal timeout
BatchCompletingEvent	Batch is finishing
BatchCompletedEvent	Batch fully complete
ChainStartedEvent	Workflow chain begins
ChainCompletedEvent	Workflow chain succeeds
ChainFailedEvent	Workflow chain fails
WorkflowBranchTriggeredEvent	A workflow condition matches

run.ratchet.spi: Extension Points

Interface	Purpose
RetryPolicy	Custom retry/backoff logic
ResilienceStrategy	Circuit breaker / bulkhead wrapping
ClassPolicy	Deserialization class allowlist
ErrorSanitizer	Scrub sensitive data from error messages
JobInvocationResolver	Custom callback-to-job invocation resolution
ResultPersistenceStrategy	Custom job return-value persistence
ExecutorProvider	Supply custom thread pools or virtual threads
BeanResolver	Custom bean instantiation (default: CDI)
MetricsCollector	Emit custom metrics (Micrometer, StatsD, etc.)
JobLogger	Custom job logging backend
ClusterCoordinator	Distributed wakeup notifications
StartupCoordinator	Store-backed startup leases for destructive initialization tasks
NodeIdentityProvider	Identify nodes in a cluster
RatchetOptions	Required @ApplicationScoped CDI-produced runtime options; applications must produce one or the scheduler refuses to start

How to Read This Reference

Entry Point

Start with JobSchedulerService. It is the write-side interface you inject for scheduling and lifecycle operations. Every scheduling operation begins here:

@Inject
JobSchedulerService scheduler;

For dashboards, admin tools, and support workflows, inject JobQueryService separately. Keeping the query API separate lets applications grant read-only access without exposing mutation methods.

Building Jobs

JobSchedulerService.enqueue() returns a JobBuilder, which provides the fluent API for configuring retries, priorities, timeouts, workflows, and callbacks before calling submit().

Inside a Running Job

When Ratchet executes your job, JobContext is available on the current thread. Use it to access parameters, the job ID, and the current job-scoped logger binding.

Handling Results

JobResult<T> captures everything about a completed execution and is used in workflow conditions to drive branching logic.

API vs SPI

• API (run.ratchet.api): Classes you use directly. Stable across minor versions.
• SPI (run.ratchet.spi): Extension points you implement to customize behavior. Interfaces marked @Incubating may change between minor versions.

To provide a custom SPI implementation, create a CDI bean annotated with @Alternative @Priority(APPLICATION).

Maven Coordinates

<dependency>
  <groupId>run.ratchet</groupId>
  <artifactId>ratchet-api</artifactId>
</dependency>

The ratchet-api module has no runtime dependencies beyond Jakarta EE API types (jakarta.enterprise.cdi-api and jakarta.interceptor-api, both provided by the runtime). It defines the complete public API and SPI surface.

See Also

• Getting Started
• Concepts
• SPI Interfaces