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
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
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
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

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 fails after final attempt
JobRetryingEvent	Job is being retried
JobCancellingEvent	Job cancellation initiated
JobCancelledEvent	Job cancellation confirmed
JobPausedEvent	Job paused
JobResumedEvent	Job resumed
JobDlqEvent	Job moved to dead letter queue
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
PerformanceMetricsEvent	System metrics snapshot available

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 only interface you inject and use directly. Every scheduling operation begins here:

@Inject
JobSchedulerService scheduler;

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