Quarkus JBeret

The Quarkus JBeret Extension adds support for JSR-352 Batch Applications for the Java Platform. JBeret is an implementation of the JSR-352.

Installation

If you want to use this extension, you need to add the io.quarkiverse.jberet:quarkus-jberet extension first to your build file:

pom.xml
<dependencyManagement>
    <dependency>
        <groupId>io.quarkiverse.jberet</groupId>
        <artifactId>quarkus-jberet-bom</artifactId>
        <version>2.11.0</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkiverse.jberet</groupId>
        <artifactId>quarkus-jberet</artifactId>
    </dependency>
</dependencies>
build.gradle
implementation platform("io.quarkiverse.jberet:quarkus-jberet-bom:2.11.0")
implementation("io.quarkiverse.jberet:quarkus-jberet:2.11.0")

Recommended Quarkus version: 3.28.1 or higher

There is no direct correspondence between Quarkus JBeret versions and Quarkus versions.

The Batch API and Runtime will be available out of the box. Please refer to the Java Batch documentation, or the JBeret documentation to learn more about Batch Applications.

Simplified Configuration

The Batch API requires the @BatchProperty annotation to inject the specific configuration from the batch definition file. Instead, you can use the @ConfigProperty annotation, which is used to inject configuration properties in Quarkus using the MicroProfile Config API and keep consistency:

@Inject
@BatchProperty(name = "job.config.name")
String batchConfig;

// Use Optional or set a defaultValue (see note below)
@ConfigProperty(name = "job.config.name")
Optional<String> mpConfig;

Batch properties are only available during job execution, not at application startup. Because Quarkus validates @ConfigProperty injection points at startup, using @ConfigProperty without Optional or defaultValue will cause a ConfigurationException. Always use Optional<T> or set a defaultValue:

// OK - Optional
@ConfigProperty(name = "job.config.name")
Optional<String> mpConfig;

// OK - defaultValue
@ConfigProperty(name = "job.config.name", defaultValue = "")
String mpConfig;

// FAILS at startup - batch property value is not yet available
@ConfigProperty(name = "job.config.name")
String mpConfig;

This restriction does not apply to @BatchProperty, which is only resolved during job execution.

Also, @BatchProperty injection fallbacks to Quarkus Config org.eclipse.microprofile.config.spi.Converter to convert the type, if the type is not supported by Java Batch.

CDI Beans

The Batch APIs JobOperator and JobRepository are available as CDI beans, so they can be injected directly into any code:

@Inject
JobOperator jobOperator;
@Inject
JobRepository jobRepository;

void start() {
    long executionId = jobOperator.start("batchlet", new Properties());
    JobExecution jobExecution = jobRepository.getJobExecution(executionId);
}

A specific Quarkus implementation is available in QuarkusJobOperator, which can be also injected directly:

@Inject
QuarkusJobOperator jobOperator;

void start() {
    Job job = new JobBuilder("programmatic")
            .step(new StepBuilder("programmaticStep")
                    .batchlet("programmaticBatchlet")
                    .build())
            .build();

    long executionId = jobOperator.start(job, new Properties());
    JobExecution jobExecution = jobOperator.getJobExecution(executionId);
}

With QuarkusJobOperator it is possible to define and start programmatic Jobs, with the JBeret Programmatic Job Definition.

It is possible to provide a Job definition via a CDI producer (instead of using XML):

@ApplicationScoped
public static class JobProducer {
    @Produces
    @Named
    public Job job() {
        return new JobBuilder("job")
                .step(new StepBuilder("step").batchlet("batchlet", new String[] {}).build())
                .build();
    }
}

A Job registered with CDI will be named by the @Named#value attribute or by the method name. The @Named annotation is required regardless. This is the named used by JobOperator to locate and execute a Job.

Job Launcher

The QuarkusJobLauncher provides a simplified way to start and run batch jobs synchronously. Unlike the standard JobOperator, which always starts jobs asynchronously, the QuarkusJobLauncher blocks until the job completes and returns the final JobExecution:

@Inject
QuarkusJobLauncher jobLauncher;

void execute() throws Exception {
    JobExecution execution = jobLauncher.run("myJob", new Properties());
    // Execution is already complete here
    BatchStatus status = execution.getBatchStatus();
}

The run method also handles restart automatically. If the most recent execution of the job is FAILED or STOPPED, calling run will restart it from the last checkpoint instead of creating a new job instance. If the job has never been run or the last execution completed successfully, a new job instance is created.

Command Mode with @QuarkusMain

The QuarkusJobLauncher is designed to work with Quarkus Command Mode. This allows you to run a batch job as a CLI application that starts, executes the job, and exits:

@QuarkusMain
public class BatchApplication implements QuarkusApplication {
    @Inject
    QuarkusJobLauncher jobLauncher;

    @Override
    public int run(String... args) throws Exception {
        Properties jobParameters = new Properties();
        // args can be used to set job parameters
        JobExecution execution = jobLauncher.run("myJob", jobParameters);
        return execution.getBatchStatus() == BatchStatus.COMPLETED ? 0 : 1;
    }
}

The application will start Quarkus, execute the batch job, and return an exit code based on the job result. This is useful for scheduled batch processing via cron, CI/CD pipelines, or any scenario where the job should run once and exit.

Scheduler

The JBeret Scheduler is integrated out of the box in this extension.

To schedule a Job execution, please refer to the quarkus.jberet.job."job-name".cron configuration. A Job can also be scheduled programmatically, using the JobScheduler API and the Quarkus startup event:

@ApplicationScoped
public class Scheduler {
    @Inject
    JobScheduler jobScheduler;

    void onStart(@Observes StartupEvent startupEvent) {
        JobScheduleConfig scheduleConfig = JobScheduleConfigBuilder.newInstance()
                .jobName("scheduler")
                .initialDelay(0)
                .build();

        jobScheduler.schedule(scheduleConfig);
    }
}

The JobScheduler does not support persistent schedules.

REST API

The JBeret REST is integrated as separate extension that can be easily added to your build file:

pom.xml
<dependency>
    <groupId>io.quarkiverse.jberet</groupId>
    <artifactId>quarkus-jberet-rest</artifactId>
    <version>2.11.0</version>
</dependency>
build.gradle
implementation("io.quarkiverse.jberet:quarkus-jberet-rest:2.11.0")

JBeret REST requires either Quarkus REST (recommended) or Quarkus RESTEasy Classic. If any of these are not yet available in the project, one must be added:

pom.xml
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-rest-jackson</artifactId>
</dependency>

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-rest-client-jackson</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-rest-jackson")
implementation("io.quarkus:quarkus-rest-client-jackson")

The JBeret REST API, provides REST resources to several operations around the Batch API: starting and stopping jobs, querying the status of a job, schedule a job, and more. The extension includes a REST client to simplify the REST API calls:

@Inject
BatchClient batchClient;

void start() throws Exception {
    JobExecutionEntity jobExecutionEntity = batchClient.startJob("batchlet", new Properties());
}

Example Applications

Example applications can be found inside the integration-tests folder:

  • chunk - A simple Job that reads, processes, and stores data from a file.

  • jdbc-repository - A Job that uses a jdbc datasource to store JBeret and Job metadata.

  • scheduler - Schedule a Job to run every 10 seconds

  • job-launcher - A @QuarkusMain application using QuarkusJobLauncher with start and restart

Or take a look into the World of Warcraft Auctions - Batch Application. It downloads the World of Warcraft Auction House data and provides statistics about items prices.

Native Image Limitations

The Quakus JBeret Extension fully supports the Graal VM Native Image with the following exceptions:

  • Scripting Languages. While Javascript should work, it is unlikely that other scripting languages will be supported in Graal via JSR-223.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.jberet.jobs.includes

A regex pattern of Job names to exclude.

Environment variable: QUARKUS_JBERET_JOBS_INCLUDES

list of Pattern

quarkus.jberet.jobs.excludes

A regex pattern of Job names to include.

Environment variable: QUARKUS_JBERET_JOBS_EXCLUDES

list of Pattern

quarkus.jberet.max-async

The maximum number of threads allowed to be executed.

Environment variable: QUARKUS_JBERET_MAX_ASYNC

int

quarkus.jberet.job.job-listeners

quarkus.jberet.job."job-name".job-listeners

A list of jakarta.batch.api.listener.JobListener bean names or FQNs to execute with the Job.

The unnamed configuration quarkus.jberet.job.job-listeners, applies to all configured jobs.

Environment variable: QUARKUS_JBERET_JOB_JOB_LISTENERS

list of RefArtifact

quarkus.jberet.job.step-listeners

quarkus.jberet.job."job-name".step-listeners

A list of jakarta.batch.api.listener.StepListener bean names or FQNs to execute with the Job.

The unnamed configuration quarkus.jberet.job.step-listeners, applies to all configured jobs.

Environment variable: QUARKUS_JBERET_JOB_STEP_LISTENERS

list of RefArtifact

quarkus.jberet.job."job-name".cron

The Job schedule in Cron format.

The syntax used for Cron expressions is based on Quartz. See Cron Trigger.

Environment variable: QUARKUS_JBERET_JOB__JOB_NAME__CRON

string

quarkus.jberet.job."job-name".params."params"

The Job parameters.

Environment variable: QUARKUS_JBERET_JOB__JOB_NAME__PARAMS__PARAMS_

Map<String,String>

The JBeret Repository configuration

Type

Default

quarkus.jberet.repository.type

The repository type to store JBeret and Job data. A jdbc jdbc type requires a JDBC datasource.

Environment variable: QUARKUS_JBERET_REPOSITORY_TYPE

string

in-memory

quarkus.jberet.repository.jdbc.datasource

The datasource name for the JBeret Repository. By default, it uses the default (unnamed) datasource.

Environment variable: QUARKUS_JBERET_REPOSITORY_JDBC_DATASOURCE

string

quarkus.jberet.repository.jdbc.ddl-file

Custom DDL file resource for JBeret tables creation; if using custom table names please also set sql-file property to propagate table names.

Environment variable: QUARKUS_JBERET_REPOSITORY_JDBC_DDL_FILE

string

quarkus.jberet.repository.jdbc.sql-file

Custom queries to be used to query JBeret tables; this is mandatory if custom table names are used in custom DDL filename.

The file must be of type properties, and must follow the exact template as defined in jberet.properties

Environment variable: QUARKUS_JBERET_REPOSITORY_JDBC_SQL_FILE

string

quarkus.jberet.repository.jdbc.db-table-prefix

JBeret tables name prefix.

Environment variable: QUARKUS_JBERET_REPOSITORY_JDBC_DB_TABLE_PREFIX

string

quarkus.jberet.repository.jdbc.db-table-suffix

JBeret tables name suffix.

Environment variable: QUARKUS_JBERET_REPOSITORY_JDBC_DB_TABLE_SUFFIX

string