Upgrade to v9

This guide documents how to migrate to JobRunr v9 and JobRunr Pro v9.

This version is currently in beta

Important

This release has a few breaking changes Please carefully review the breaking changes section.

Installation

For the OSS version, the v9 release is available in the Maven Central repository.

For Pro users, the v9 release is available on our private Maven repository.

Simply replace the version you’re on with 9.0.0.

Micronaut 5 support

As of v9, JobRunr OSS and JobRunr Pro require Micronaut 5. Before upgrading to JobRunr v9, you must upgrade your application from Micronaut 4 to Micronaut 5.

Support for Micronaut 4 has been removed and is no longer available in JobRunr v9.

EventBus

JobRunr Pro

JobRunr Pro now includes a built-in EventBus that supports multiple inter-server communication channels, such as UDP multicast and PostgreSQL LISTEN/NOTIFY.

With the EventBus, job enqueue events are propagated to all relevant servers immediately, allowing enqueued jobs to start executing almost instantly instead of waiting for the next polling cycle.

Usage

If you don’t do anything, it will be automatically configured for you using org.jobrunr.utils.events.EventTransportFactory#createEventTransport, but if you want to customize this, you can do it as follows.

To use the event bus, you must now configure an EventTransport. If you were previously using the jobrunr.multicast-group-address property, you will need to provide an EventTransport bean. Alternatively, if you were using org.jobrunr.configuration.JobRunrConfiguration#useMulticastAddress, update your setup to use org.jobrunr.configuration.JobRunrConfiguration#useEventTransport.

You can choose between a PostgresEventTransport (if you are using PostgreSQL) or a MulticastEventTransport. If you do not explicitly configure one, JobRunr will use the MulticastEventTransport by default.

JobRunrPro
    .configure()
    .useEventTransport(new MulticastEventTransport("udp://239.76.159.181:8379"));
Important

When you use the MulticastEventTransport like with the previous implementation of multicast please ensure that your network supports multicast.

Pausing of Batch Jobs

JobRunr Pro

The Pause Batch Job feature allows you to temporarily stop the execution of all child jobs within a batch that have not yet started processing.

When a batch job is paused, all child jobs in the Enqueued, Scheduled, or Pending state are paused and will not execute until the batch job is resumed. Child jobs that are already Processing continue running to completion.

Important

A batch job can only be paused after all of its child jobs have been created.

Usage

You can pause and resume a batch job in one of three ways:

  • Use the Pause and Resume buttons in the JobRunr dashboard.
  • Call the REST API endpoints:
    • POST /jobs/{batchJobId}/pause
    • POST /jobs/{batchJobId}/resume
  • Use the BatchJobManager to programmatically pause or resume a batch job
    var manager = new BatchJobManager(storageProvider);
manager.pauseBatchJob("batchJobId");
manager.resumeBatchJob("batchJobId");

If you pause a batch job after all of its child jobs have entered the Processing state, the batch job will continue to completion because there are no remaining child jobs that can be paused.

Kotlin Exposed upgrade

JobRunr Pro

The Kotlin Exposed dependency has been upgraded to v1. To continue using the Exposed Transaction Plugin, you must upgrade your application to Exposed v1.

Breaking Changes

API Changes

We removed a number of API’s that were deprecated in v8:

  • The deprecated JobRunrConfiguration#useMicroMeter has been removed, use JobRunrConfiguration#useMetrics instead
  • The deprecated JobBuilder#withDetails has been removed, use JobBuilder#withJobLambda instead
  • The deprecated RecurringJobBuilder#withDetails has been removed, use RecurringJobBuilder#withJobLambda instead
  • JobRunr Pro The deprecated JobSearchRequestBuilder#withQueue has been removd, use JobSearchRequestBuilder#withPriorityQueue instead
  • JobRunr Pro The deprecated RecurringJobSearchRequestBuilder#withQueue has been removd, use RecurringJobSearchRequestBuilder#withPriorityQueue instead
  • JobRunr Pro The deprecated JobServerFilter#getProgress has been removed, use JobServerFilter#getProgressAsRatio instead

Other changes:

  • JobRunr Pro JobRunrDashboardWebServer has constructor changes to accept an EventTransport
  • JobRunr Pro DashboardApiHandler and DashboardDbDataProvider have constructor changes to accept an EventBus
  • JobRunr Pro JobScheduler and JobRequestScheduler have constructor changes to accept an EventTransport.
  • JobRunr Pro StorageProvider.BatchJobWithChildStats and StorageProvider.BatchJobChildStats now also require an awaitingBatchJobChildCount
  • JobRunr Pro DashboardDbDataProvider public constructor now also expects a BatchJobManager
  • JobRunr Pro ConcurrentJobModificationPolicy has been dropped with no alternative
  • JobRunr Pro JobSearchRequest now requires a list of UUID for awaitingOn
  • JobRunr Pro Remove CronExpression#create, use constructor instead
  • JobRunr Pro Several unused constructor on RoundRobinDynamicQueuePolicy had been removed
  • JobRunr Pro Removed duplicate JsonMapperFactory, use the factory in package org.jobrunr.utils.mapper

Micronaut

  • Dropped support for Micronaut 4, use Micronaut 5 instead

Kotlin Exposed

  • JobRunr Pro Kotlin Exposed now requires v1

Multicast

  • JobRunr Pro JobEnqueuedMessagePublisher has removed, you may implement an EventTransport instead.
  • JobRunr Pro MulticastMessagePublisher and MulticastMessageReceiver have been removed, see MulticastEventTransport instead.

Job States

  • JobRunr Pro AllowedJobStateStateChanges.isIllegalStateChange(...) now also expected a JobType
  • JobRunr Pro DeletedState: the constructor DeletedState(String reason, JobRunrUserInfo user) has been removed
  • JobRunr Pro EnqueuedState: the constructor EnqueuedState(String reason, JobRunrUserInfo user) has been removed

BackgroundJobServer

  • JobRunr Pro org.jobrunr.server.BackgroundJobServer#publishJobEnqueuedMessage has been dropped you may use org.jobrunr.server.BackgroundJobServer#publishEvent instead.
  • JobRunr Pro BackgroundJobServer has constructor changes to accept an EventTransport

Configuration

  • JobRunr Pro StorageProviderClusterConfiguration has constructor changes to accept an EventBus instead of multi-cast-group-address.
  • JobRunr Pro Method org.jobrunr.configuration.JobRunrConfiguration#useMulticastAddress has been dropped, you’ll need to configure a MulticastEventTransport via org.jobrunr.configuration.JobRunrConfiguration#useEventTransport.
  • JobRunr Pro Property jobrunr.multicast-group-address has been dropped, you’ll need to provide configure MulticastEventTransport bean.

Multi-Cluster

  • JobRunr Pro The Multi-Cluster Dashboard should be upgraded at the same time as the single cluster dashboard (this is not required if they were on 8.7 or higher)

Test Fixtures

  • JobRunr test fixtures now require JDK 17 or higher