Run a Spring Boot application as a Micronaut application

Write an application using Spring Boot annotations and compute it into a Micronaut application at compilation time.

Authors: Sergio del Amo

Micronaut Version: 3.9.2

1. Getting Started

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

You will write an application that includes no dependencies on Micronaut itself in the source code (only Spring dependencies) but is computed into a Micronaut application at compilation time.

2. What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE
JDK 1.8 or greater installed with JAVA_HOME configured appropriately

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

4. Writing the Application

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

mn create-app example.micronaut.micronautguide \
    --features=spring-web,spring-boot,views-thymeleaf,micronaut-validation \
    --build=maven
    --lang=java

If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.

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

If you use Micronaut Launch, select Micronaut Application as application type and add spring-web, spring-boot, views-thymeleaf, and micronaut-validation features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features and apply those changes to your application.

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Dependencies

Micronaut for Spring allows you to use traditional Spring annotations, which are mapped to Micronaut annotations at compilation time. This allows you to write an application that can be imported to another Spring or Micronaut application without change.

To use Spring Framework Annotations, write Spring MVC controllers, and support Spring Boot features, add both features spring-web and spring-boot when you create the application with Micronaut CLI and/or Micronaut Launch. These features include the following dependencies:

pom.xml

<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-annotation</artifactId>
</path>
<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-web-annotation</artifactId>
</path>
<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-boot-annotation</artifactId>
</path>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-web</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.micronaut.spring</groupId>
    <artifactId>micronaut-spring-boot</artifactId>
    <scope>runtime</scope>
</dependency>

4.2. Application

Create an Application class:

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

package example.micronaut;

import io.micronaut.runtime.Micronaut;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication (1)
public class Application {

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

1	In a Spring Boot application, the @SpringBootApplication enables Spring Boot’s auto-configuration mechanism, enables `@Component` scan on the package where the application is located, and allows the application to register extra beans in the context or import additional configuration classes.

4.3. @ConfigurationProperties

src/main/java/example/micronaut/GreetingConfiguration.java

package example.micronaut;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component (1)
@ConfigurationProperties("greeting") (2)
public class GreetingConfiguration {

    private String template = "Hello, %s!";

    public String getTemplate() {
        return template;
    }

    public void setTemplate(String template) {
        this.template = template;
    }
}

1	org.springframework.stereotype.Component maps to io.micronaut.context.annotation.Bean at compilation time. Spring will scan the application for classes annotated with `@Component`. It instantiates those classes and fulfills the injection points.
2	org.springframework.boot.context.properties.ConfigurationProperties maps to io.micronaut.context.annotation.ConfigurationProperties at compilation time.

The @Prototype annotation is a synonym for @Bean because the default scope in a Micronaut application is prototype.

4.4. Configuration

Add some configuration which will populate this GreetingConfiguration:

src/main/resources/application.yml

greeting:
  template: "Hola, %s!"

4.5. POJO

Create a POJO that uses Jackson Annotations.

src/main/java/example/micronaut/Greeting.java

package example.micronaut;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;

public class Greeting {

    private final long id;
    private final String content;

    @JsonCreator
    public Greeting(@JsonProperty("id") long id, @JsonProperty("content") String content) {
        this.id = id;
        this.content = content;
    }

    public long getId() {
        return id;
    }

    public String getContent() {
        return content;
    }
}

4.6. Service

Add a service that showcases configuration injection and validation.

src/main/java/example/micronaut/GreetingService.java

package example.micronaut;

import org.springframework.stereotype.Service;
import org.springframework.validation.annotation.Validated;

import javax.validation.constraints.Pattern;
import java.util.Optional;
import java.util.concurrent.atomic.AtomicLong;
import java.util.concurrent.atomic.AtomicReference;

@Service (1)
@Validated (2)
public class GreetingService {

    private final AtomicLong counter = new AtomicLong();

    private final GreetingConfiguration greetingConfiguration;

    private final AtomicReference<Greeting> lastGreeting = new AtomicReference<>();

    public GreetingService(GreetingConfiguration greetingConfiguration) { (3)
        this.greetingConfiguration = greetingConfiguration;
    }

    public Greeting greeting(@Pattern(regexp = "\\D+") String name) { (4)
        final Greeting greeting = new Greeting(counter.incrementAndGet(),
                String.format(greetingConfiguration.getTemplate(), name));
        lastGreeting.set(greeting);
        return greeting;
    }

    public Optional<Greeting> getLastGreeting() {
        return Optional.ofNullable(lastGreeting.get());
    }
}

1	org.springframework.stereotype.Service maps to io.micronaut.context.annotation.Bean at compilation time. A Spring `@Service` indicates that they hold business logic.
2	The `@Validated` annotation tells Spring to validate parameters passed into a method of the annotated class.
3	Use constructor injection to inject a bean of type `GreetingConfiguration`.
4	Use `javax.validation.constraints` Constraints to ensure the data matches your expectations.

4.6.1. Service Test

Create a test to verify validation works as expected.

src/test/java/example/micronaut/GreetingServiceTest.java

package example.micronaut;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.function.Executable;

import javax.validation.ConstraintViolationException;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertThrows;

@MicronautTest(startApplication = false) (1)
class GreetingServiceTest {

    @Inject
    GreetingService greetingService;

    @Test
    void regexValidationNonDigitsWork() {
        assertDoesNotThrow(() -> greetingService.greeting("foo"));
        Executable e = () -> greetingService.greeting("12foo");
        assertThrows(ConstraintViolationException.class, e);
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context. This test does not need the embedded server. Set `startApplication` to `false` to avoid starting it.

4.7. @RestController

Micronaut Spring only supports @RestController semantics. A @RestController request handling method serializes return objects into an HTTP response. Create a controller that uses the following Spring annotations.

src/main/java/example/micronaut/GreetingController.java

package example.micronaut;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.ui.Model;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;

import javax.validation.constraints.Pattern;

@RestController (1)
public class GreetingController {

    private final GreetingService greetingService;

    public GreetingController(GreetingService greetingService) { (2)
        this.greetingService = greetingService;
    }

    @GetMapping("/greeting") (3)
    public Greeting greeting(
            @RequestParam(value="name", defaultValue="World") @Pattern(regexp = "\\D+") String name) {  (4)
        return greetingService.greeting(name);
    }

    @PostMapping("/greeting") (5)
    public Greeting greetingByPost(@RequestBody Greeting greeting) { (6)
        return greetingService.greeting(greeting.getContent());
    }

    @DeleteMapping("/greeting") (7)
    public ResponseEntity<?> deleteGreeting() { (8)
        MultiValueMap<String, String> headers = new LinkedMultiValueMap<>();
        headers.add("Foo", "Bar");
        return new ResponseEntity<>(headers, HttpStatus.NO_CONTENT); (8)
    }

    @GetMapping("/greeting-status") (3)
    @ResponseStatus(code = HttpStatus.CREATED) (9)
    public Greeting greetingWithStatus(
            @RequestParam(value="name", defaultValue="World") @Pattern(regexp = "\\D+") String name) {
        return greetingService.greeting(name);
    }
}

1	org.springframework.web.bind.annotation.RestController.html maps to io.micronaut.http.annotation.Controller at compilation time.
2	Use constructor injection to inject a bean of type `GreetingService`.
3	org.springframework.web.bind.annotation.GetMapping maps to io.micronaut.http.annotation.Get at compilation time.
4	org.springframework.web.bind.annotation.RequestParam maps to io.micronaut.http.annotation.QueryValue at compilation time.
5	org.springframework.web.bind.annotation.PostMapping maps to io.micronaut.http.annotation.Post at compilation time.
6	org.springframework.web.bind.annotation.RequestBody maps to io.micronaut.http.annotation.Body at compilation time.
7	org.springframework.web.bind.annotation.DeleteMapping maps to io.micronaut.http.annotation.Delete at compilation time.
8	Special support is provided by the `micronaut-spring-web` dependency to allow the application to return a ResponseEntity.
9	org.springframework.web.bind.annotation.ResponseStatus maps to io.micronaut.http.annotation.Status at compilation time.

4.8. Tests

4.8.1. Declarative HTTP Client

You can use Spring annotations with a declarative Micronaut HTTP Client.

src/test/java/example/micronaut/GreetingClient.java

package example.micronaut;

import io.micronaut.http.client.annotation.Client;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;

import io.micronaut.core.annotation.Nullable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;

@Client("/") (1)
public interface GreetingClient {

    @GetMapping("/greeting{?name}") (2)
    Greeting greet(@Nullable String name);

    @PostMapping("/greeting") (3)
    Greeting greetByPost(@RequestBody Greeting greeting); (4)

    @DeleteMapping("/greeting") (5)
    HttpStatus deletePost();

    @GetMapping("/nested/greeting{?name}") (2)
    Greeting nestedGreet(@RequestParam @Nullable String name); (6)

    @GetMapping("/greeting-status{?name}") (2)
    ResponseEntity<Greeting> greetWithStatus(@RequestParam @Nullable String name); (6)
}

1	Use `@Client("/")` to declare a declarative HTTP Client pointing to the application.
2	org.springframework.web.bind.annotation.GetMapping maps to io.micronaut.http.annotation.Get at compilation time.
3	org.springframework.web.bind.annotation.PostMapping maps to io.micronaut.http.annotation.Post at compilation time.
4	org.springframework.web.bind.annotation.RequestBody maps to io.micronaut.http.annotation.Body at compilation time.
5	org.springframework.web.bind.annotation.DeleteMapping maps to io.micronaut.http.annotation.Delete at compilation time.
6	org.springframework.web.bind.annotation.RequestParam maps to io.micronaut.http.annotation.QueryValue at compilation time.

and use it in a test:

src/test/java/example/micronaut/GreetingControllerTest.java

package example.micronaut;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import jakarta.inject.Inject;
import static org.junit.jupiter.api.Assertions.*;

@MicronautTest
class GreetingControllerTest {

    @Inject
    GreetingClient greetingClient;

    @Test
    void testGreetingService() {
        assertEquals(
                "Hola, John!",
                greetingClient.greet("John").getContent()
        );
    }
}

4.9. @Scheduled

You can use the @Scheduled annotation to schedule a recurring task. Create a Job:

src/main/java/example/micronaut/GreetingJob.java

package example.micronaut;

import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.Optional;

@Component (1)
public class GreetingJob {
    private static final Logger LOG = LoggerFactory.getLogger(GreetingJob.class);

    private final GreetingService greetingService;

    public GreetingJob(GreetingService greetingService) { (2)
        this.greetingService = greetingService;
    }

    @Scheduled(fixedDelayString = "30s") (3)
    void printLastGreeting() {
        final Optional<Greeting> lastGreeting = greetingService.getLastGreeting();
        lastGreeting.ifPresent(greeting -> {
            LOG.info("Last Greeting was = {}", greeting.getContent());
        });
    }
}

1	org.springframework.stereotype.Component maps to io.micronaut.context.annotation.Bean at compilation time. Spring will scan the application for classes annotated with `@Component`. It instantiates those classes and fulfills the injection points.
2	Use constructor injection to inject a bean of type `GreetingService`.
3	org.springframework.scheduling.annotation.Scheduled maps to io.micronaut.scheduling.annotation.Scheduled at compilation time. You can use `@Scheduled` annotation to schedule a recurring task.

4.10. Server side HTML Rendering

4.10.1. Thymeleaf view

4.11. Views

Although the Micronaut framework is primarily designed around message encoding / decoding, there are occasions where it is convenient to render a view on the server side.

To use the Thymeleaf Java template engine to render views in a Micronaut application, add the following dependency on your classpath.

pom.xml

<dependency>
    <groupId>io.micronaut.views</groupId>
    <artifactId>micronaut-views-thymeleaf</artifactId>
    <scope>compile</scope>
</dependency>

Create a Thymeleaf view to render the UI for the controller:

src/main/resources/views/home.html

<!DOCTYPE html>
<html>
<head>
    <title>Home</title>
</head>
<body>
    <h1 th:text="${message}"></h1>
</body>
</html>

4.11.1. Controller

src/main/java/example/micronaut/HomeController.java

package example.micronaut;

import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController (1)
public class HomeController {
    @GetMapping(path = "/", produces = "text/html") (2)
    public String home(Model model) { (3)
        model.addAttribute(
                "message",
                "Welcome to Micronaut for Spring");

        return "home"; (4)
    }
}

1	org.springframework.web.bind.annotation.RestController.html maps to io.micronaut.http.annotation.Controller at compilation time.
2	org.springframework.web.bind.annotation.GetMapping maps to io.micronaut.http.annotation.Get at compilation time.
3	You can use org.springframework.ui.Model in combination with Micronaut Views.
4	the View’s name

4.11.2. Controller Test

Add a test that proves you can use org.springframework.ui.Model and render server-side HTML.

src/test/java/example/micronaut/HomeControllerTest.java

package example.micronaut;

import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

@MicronautTest (1)
class HomeControllerTest {

    @Inject
    @Client("/")
    HttpClient httpClient; (2)

    @Test
    void renderServerSideHTMLwithThymeleafAndMicronautViews() {
        String expected = "<!DOCTYPE html>\n" +
                "<html>\n"+
                "<head>\n"+
                "    <title>Home</title>\n"+
                "</head>\n"+
                "<body>\n"+
                "    <h1>Welcome to Micronaut for Spring</h1>\n"+
                "</body>\n"+
                "</html>";
        String html = httpClient.toBlocking().retrieve("/");
        assertEquals(expected, html);
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
2	Inject the `HttpClient` bean and point it to the embedded server.

5. Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

Execute the API:

 curl "http://localhost:8080/greeting?name=Sergio"

{"id":1,"content":"Hola, Sergio!"}

If you wait 30 seconds, you will see a log statement from GreetingJob.

6. Next steps

7. Help with the Micronaut Framework

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

Table of Contents

Run a Spring Boot application as a Micronaut application

1. Getting Started

2. What you will need

3. Solution

4. Writing the Application

4.1. Dependencies

4.2. Application

4.3. @ConfigurationProperties

4.4. Configuration

4.5. POJO

4.6. Service

4.6.1. Service Test

4.7. @RestController

4.8. Tests

4.8.1. Declarative HTTP Client

4.9. @Scheduled

4.10. Server side HTML Rendering

4.10.1. Thymeleaf view

4.11. Views

4.11.1. Controller

4.11.2. Controller Test

5. Running the Application

6. Next steps

7. Help with the Micronaut Framework