Background methods

JobRunr supports 3 ways to easily generate background jobs:

• Using only a Java 8 lambda
• Using JobRequests
• Using a JobBuilder that uses either a Java 8 lambda or a JobRequest

Java 8 lambda’s

Background jobs using Java 8 lambda’s in JobRunr look like regular method calls. Background jobs can use both instance and static method calls as in the following example.

BackgroundJob.enqueue<EmailSender>(x -> x.send("jobrunr@example.com"));

BackgroundJob.enqueue(() -> System.out.println("Hello, world!"));

Unlike usual method invocations which are run instantly, these methods are in fact Java 8 Functional Interfaces and are executed asynchronously and - depending on the configuration - even outside the current JVM. So the purpose of the method calls above is to collect and serialize the following information:

• Type name, including package.
• Method name and its parameter types.
• Argument values.

Important: all your servers must run the same version of your code! If your webapp server has a newer version with a method signature that is not compatible with the server that processes your background jobs, a NoSuchMethod Exception will be thrown and job processing will fail!
As of JobRunr v1.1.0, the dashboard shows an error if there are jobs which cannot be found.

Serialization is performed by the either Jackson, Gson or Json-B and the resulting JSON, that looks like in the following snippet, is persisted in a StorageProvider making it available for other processing in a different thread or even a different JVM. As we can see everything is passed by value, so heavy data structures will also be serialized and consume a lot of bytes in the RDBMS or NoSQL database.

{
  "lambdaType": "org.jobrunr.jobs.lambdas.JobLambda",
  "className": "java.lang.System",
  "staticFieldName": "out",
  "methodName": "println",
  "jobParameters": [
    {
      "className": "java.lang.String",
      "object": "a test"
    }
  ]
}

Parameters

You can pass parameters along to your background job methods but these should be kept as small as possible. A parameter must either be:

• a type of java.lang like String, Integer, …
• a custom class with a default no argument constructor - this to deserialize it from the StorageProvider

Method visibility

JobRunr only runs methods with public visibility.

Constraints for Java 8 lambda’s

JobRunr uses some ASM magic to analyse the Job Lambda and covers most use cases. It is important to note the following:

Only one method to enqueue is supported

You can not enqueue the following job as it results in two jobs to run which is not supported and this will fail:

BackgroundJob.enqueue(() -> {
  myService.createPDF();
  myService.sendPDF();
);

You cannot pass IoC injected services as parameters to the lambda

You can not enqueue the following job as the reference to the MyService instance is used as parameter to the lambda and thus not an instance during the analysis of the job lambda.

BackgroundJob.<MyService>enqueue(x -> doWork(x));

public class MyJobRequest implements JobRequest {

  private UUID id;

  public MyJobRequest(UUID id) {
    this.id = id;
  }

  @Override
  public Class<MyJobRequestHandler> getJobRequestHandler() {
      return MyJobRequestHandler.class;
  }

  public UUID getId() {
    return id;
  }

}

JobId jobId = BackgroundJobRequest.enqueue(new MyJobRequest(id));

@Component
public class MyJobRequestHandler implements JobRequestHandler<MyJobRequest> {

  @Inject
  private SomeService someService; // you can inject other services (or constructor-injection)

  @Override
  @Job(name = "Some neat Job Display Name", retries = 2)
  public void run(MyJobRequest jobRequest) {
      // do your background work here
  }
}

jobScheduler.create(aJob()
  .withName("A job requested for " + name)
  .withAmountOfRetries(3)
  .withLabels("tenant-A", "from-rest-api")
  .withDetails(() -> sampleService.executeExampleJob(name)));