Java / Maven

Schedule periodic tasks inside your Micronaut applications

Learn how to schedule periodic tasks inside your Micronaut microservices.

Sergio del Amo

On this guide

In this section

Getting Started

In this guide, we will create a Micronaut application written in Java.

Nowadays it is pretty usual to have some kind of cron or scheduled task that needs to run every midnight, every hour, a few times a week,…

In this guide you will learn how to use Micronaut capabilities to schedule periodic tasks inside a Micronaut microservice.

What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Download and unzip the source

Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide --build=maven --lang=java

Note	If you don’t specify the `--build` argument, Gradle with the Kotlin DSL is used as the build tool. If you don’t specify the `--lang` argument, Java is used as the language. If you don’t specify the `--test` argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

Setup IntelliJ IDEA to develop Micronaut Applications.

Set log level INFO for package demo

In this guide, we will use several log statements to show Job execution.

Add this statement to the end of logback.xml:

java/src/main/resources/logback.xml

<logger name="example.micronaut" level="INFO"/>

The above line configures a logger for package example.micronaut with log level INFO.

Creating a Job

Create the HelloWorldJob class:

java/src/main/java/example/micronaut/HelloWorldJob.java

package example.micronaut;

import io.micronaut.scheduling.annotation.Scheduled;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import jakarta.inject.Singleton;
import java.text.SimpleDateFormat;
import java.util.Date;

@Singleton // 
public class HelloWorldJob {
    private static final Logger LOG = LoggerFactory.getLogger(HelloWorldJob.class); // 

    @Scheduled(fixedDelay = "10s") // 
    void executeEveryTen() {
        LOG.info("Simple Job every 10 seconds: {}", new SimpleDateFormat("dd/M/yyyy hh:mm:ss").format(new Date()));
    }

    @Scheduled(fixedDelay = "45s", initialDelay = "5s") // 
    void executeEveryFourtyFive() {
        LOG.info("Simple Job every 45 seconds: {}", new SimpleDateFormat("dd/M/yyyy hh:mm:ss").format(new Date()));
    }
}

1	Use `jakarta.inject.Singleton` to designate a class as a singleton.
2	Inject a Logger.
3	Create trigger every 10 seconds
4	Create another trigger every 45 seconds with an initial delay of 5 seconds (5000 millis)

Now start the application. Execute the ./mvnw mn:run command, which will start the application on port 8080.

After a few seconds, you will see the following output:

... Simple Job every 10 seconds :15/5/2018 12:48:02 
... Simple Job every 45 seconds :15/5/2018 12:48:07 
... Simple Job every 10 seconds :15/5/2018 12:48:12 
... Simple Job every 10 seconds :15/5/2018 12:48:22
... Simple Job every 10 seconds :15/5/2018 12:48:32
... Simple Job every 10 seconds :15/5/2018 12:48:42
... Simple Job every 45 seconds :15/5/2018 12:48:52 
... Simple Job every 10 seconds :15/5/2018 12:48:52

1	First execution of 10 seconds Job after the application starts
2	The 45 seconds Job starts 5 seconds after the application starts
3	Second execution of 10 seconds Job 10 seconds after the first execution
4	Second execution of 45 seconds Job 45 seconds after the first execution

Business logic in dedicated Use Cases

Although the previous example is valid, usually you don’t want to put your business logic in a Job. A better approach is to create an additional bean that the Job invokes. This approach decouples your business logic from the scheduling logic. Moreover, it facilitates testing and maintenance. Let’s see an example:

Create the following use case:

java/src/main/java/example/micronaut/EmailUseCase.java

package example.micronaut;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import jakarta.inject.Singleton;
import java.text.SimpleDateFormat;
import java.util.Date;

@Singleton
public class EmailUseCase {
    private static final Logger LOG = LoggerFactory.getLogger(EmailUseCase.class);

    void send(String user, String message) {
        LOG.info("Sending email to {}: {} at {}", user, message, new SimpleDateFormat("dd/M/yyyy hh:mm:ss").format(new Date()));
    }
}

And then the Job:

java/src/main/java/example/micronaut/DailyEmailJob.java

package example.micronaut;

import io.micronaut.scheduling.annotation.Scheduled;

import jakarta.inject.Singleton;

@Singleton // 
public class DailyEmailJob {

    protected final EmailUseCase emailUseCase;

    public DailyEmailJob(EmailUseCase emailUseCase) {  // 
        this.emailUseCase = emailUseCase;
    }

    @Scheduled(cron = "0 30 4 1/1 * ?") // 
    void execute() {
        emailUseCase.send("john.doe@micronaut.example", "Test Message"); // 
    }
}

1	Use `jakarta.inject.Singleton` to designate a class as a singleton.
2	Constructor injection.
3	Trigger the Job once a day at 04:30 AM
4	Call the injected use case

Scheduling a Job Manually

Consider the following scenario. You want to send every user an email two hours after they register on your application and ask them about their experiences during this first interaction.

For this guide, we will schedule a Job to trigger after one minute.

To test it, we will call a new use case named RegisterUseCase twice when the application starts.

Modify Application.java:

java/src/main/java/example/micronaut/Application.java

package example.micronaut;

import io.micronaut.context.event.ApplicationEventListener;
import io.micronaut.runtime.Micronaut;
import io.micronaut.runtime.server.event.ServerStartupEvent;

import jakarta.inject.Singleton;

@Singleton // 
public class Application implements ApplicationEventListener<ServerStartupEvent> {  // 

    private final RegisterUseCase registerUseCase;

    public Application(RegisterUseCase registerUseCase) {  // 
        this.registerUseCase = registerUseCase;
    }

    public static void main(String[] args) {
        Micronaut.run(Application.class);
    }

    @Override
    public void onApplicationEvent(ServerStartupEvent event) {  // 
        try {
            registerUseCase.register("harry@micronaut.example");
            Thread.sleep(20000);
            registerUseCase.register("ron@micronaut.example");
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }
}

1	Use `jakarta.inject.Singleton` to designate a class as a singleton.
2	Listen to the event `ServerStartupEvent`
3	Constructor injection of `RegisterUseCase`
4	`onApplicationEvent` is invoked when the application starts. Subscribing to an event is as easy as implementing `ApplicationEventListener`.

Create a runnable task EmailTask.java

java/src/main/java/example/micronaut/EmailTask.java

package example.micronaut;

public class EmailTask implements Runnable {

    private String email;
    private String message;
    private EmailUseCase emailUseCase;

    public EmailTask(EmailUseCase emailUseCase, String email, String message) {
        this.email = email;
        this.message = message;
        this.emailUseCase = emailUseCase;
    }

    @Override
    public void run() {
        emailUseCase.send(email, message);
    }

}

Create RegisterUseCase.java, which schedules the previous task.

java/src/main/java/example/micronaut/RegisterUseCase.java

package example.micronaut;

import io.micronaut.scheduling.TaskExecutors;
import io.micronaut.scheduling.TaskScheduler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import jakarta.inject.Named;
import jakarta.inject.Singleton;
import java.text.SimpleDateFormat;
import java.time.Duration;
import java.util.Date;

@Singleton
public class RegisterUseCase {

    private static final Logger LOG = LoggerFactory.getLogger(RegisterUseCase.class);

    protected final TaskScheduler taskScheduler;
    protected final EmailUseCase emailUseCase;

    public RegisterUseCase(EmailUseCase emailUseCase, // 
                           @Named(TaskExecutors.SCHEDULED) TaskScheduler taskScheduler) {  // 
        this.emailUseCase = emailUseCase;
        this.taskScheduler = taskScheduler;
    }

    public void register(String email) {
        LOG.info("saving {} at {}", email, new SimpleDateFormat("dd/M/yyyy hh:mm:ss").format(new Date()));
        scheduleFollowupEmail(email, "Welcome to the Micronaut framework");
    }

    private void scheduleFollowupEmail(String email, String message) {
        EmailTask task = new EmailTask(emailUseCase, email, message); // 
        taskScheduler.schedule(Duration.ofMinutes(1), task);  // 
    }
}

1	Constructor injection of `EmailUseCase`
2	Inject the `TaskScheduler` bean
3	Create a `Runnable` task
4	Schedule the task to run a minute from now

If you execute the above code, you will see the Job being executed one minute after we schedule it and with the supplied email address.

INFO  example.micronaut.RegisterUseCase - saving harry@micronaut.example at 15/5/2018 06:25:14
INFO  example.micronaut.RegisterUseCase - saving ron@micronaut.example at 15/5/2018 06:25:34
INFO  example.micronaut.EmailUseCase - Sending email to harry@micronaut.example : Welcome to Micronaut at 15/5/2018 06:26:14
INFO  example.micronaut.EmailUseCase - Sending email to ron@micronaut.example : Welcome to the Micronaut framework at 15/5/2018 06:26:34

Summary

During this guide, we learned how to configure Jobs using the @Scheduled annotation using fixedDelay, initialDelay, and cron, as well as manually configuring Jobs with a TaskScheduler and tasks.

Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, an advanced JDK with ahead-of-time Native Image compilation, to generate a native executable of this Micronaut application.

Compiling Micronaut applications ahead of time with GraalVM significantly improves startup time and reduces the memory footprint of JVM-based applications.

Note	Only Java and Kotlin projects support using GraalVM’s `native-image` tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

GraalVM Installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 25

sdk install java 25.0.2-graal

For installation on Windows, or for a manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 25

sdk install java 25.0.2-graalce

Native Executable Generation

To generate a native executable using Maven, run:

./mvnw package -Dpackaging=native-image

The native executable is created in the target directory and can be run with target/micronautguide.

It is possible to customize the name of the native executable or pass additional build arguments using the Maven plugin for GraalVM Native Image building. Declare the plugin as follows:

pom.xml

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.11.5</version>
    <configuration>
         
         <imageName>mn-graalvm-application</imageName>
        <buildArgs>
          
          <buildArg>-Ob</buildArg>
        </buildArgs>
    </configuration>
</plugin>

1	The native executable name will now be `mn-graalvm-application`.
2	It is possible to pass extra build arguments to `native-image`. For example, `-Ob` enables the quick build mode.

Execute the native executable, and you will see the log message of the Jobs appear:

10:16:20.803 [pool-2-thread-1] INFO  example.micronaut.HelloWorldJob - Simple Job every 10 seconds: 09/12/2019 10:16:20
10:16:20.806 [main] INFO  example.micronaut.RegisterUseCase - saving harry@micronaut.example at 09/12/2019 10:16:20
10:16:25.804 [pool-2-thread-2] INFO  example.micronaut.HelloWorldJob - Simple Job every 45 seconds: 09/12/2019 10:16:25
10:16:30.807 [pool-2-thread-4] INFO  example.micronaut.HelloWorldJob - Simple Job every 10 seconds: 09/12/2019 10:16:30

Next Steps

Explore more features with Micronaut Guides.

Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

License

Note	All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).