Micronaut 2.0: a full stack Java framework for modular, testable applications

Micronaut

Natively Cloud Native

Version: 2.0.0 2.0.0 2.0.0.RC2 2.0.0.RC1 2.0.0.M3 2.0.0.M2 2.0.0.M1 1.3.6 1.3.5 1.3.4 1.3.3 1.3.2 1.3.1 1.3.0 1.3.0.RC1 1.3.0.M2 1.3.0.M1 1.3.0.TEST 1.2.11 1.2.10 1.2.9 1.2.8 1.2.7 1.2.6 1.2.5 1.2.4 1.2.3 1.2.2 1.2.1 1.2.0 1.2.0.RC2

Core Features

import io.micronaut.core.annotation.Creator;

@io.micronaut.core.annotation.Introspected
interface Example {
    String getName();

    @Creator
    static Example create(String name) {
        return () -> name;
    }
}

@Inject @Client("http://foo.com") RxHttpClient client;

@Bean
protected DefaultHttpClient httpClient(InjectionPoint<?> injectionPoint) {
    String url = metadata.stringValue(Client.class).orElse(null);
    if (url != null) {
        return new DefaultHttpClient(url);
    } else {
        return new DefaultHttpClient();
    }
}

public class Application {

    public static void main(String[] args) {
        Micronaut.build(args)
            .eagerInitSingletons(true) <i data-value="1"></i><b>(1)</b>
            .mainClass(Application.class)
            .start();
    }
}

CLI Features

$ curl https://launch.micronaut.io/demo.zip -o demo.zip
$ unzip demo.zip -d demo

$ mn feature-diff --features=azure-function
--- micronaut-cli.yml
+++ micronaut-cli.yml
@@ -3,4 +3,4 @@
 testFramework: junit
 sourceLanguage: java
 buildTool: gradle
-features: [app-name, application, gradle, http-client, java, junit, logback, netty-server, shade, yaml]
+features: [app-name, application, azure-function, azure-function-http, gradle, java, junit, logback, yaml]


--- host.json
+++ host.json
@@ -1,0 +1,7 @@
+{
+  "version": "2.0",
+  "extensionBundle": {
+    "id": "Microsoft.Azure.Functions.ExtensionBundle",
+    "version": "[1.*, 2.0.0)"
+  }
+}

GraalVM Improvements

Micronaut’s support for GraalVM Native Image has been moved out of experimental status, which solidifies our commitment to continue improving support for native images.

Build Improvements

<parent>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-parent</artifactId>
    <version>${micronaut.version}</version>
</parent>

$ ./mvnw mn:run

HTTP Features

$ mn create-app myapp --features jetty-server    # for Jetty
$ mn create-app myapp --features tomcat-server   # for Tomcat
$ mn create-app myapp --features undertow-server # for Undertow

@Inject RxHttpClient client;

Kotlin Improvements

Serverless Improvements

Module Improvements

Micronaut is more modular than ever, with several components now available in separate modules and upgrades to those modules.

implementation("io.micronaut.rxjava3:micronaut-rxjava3")

<dependency>
    <groupId>io.micronaut.rxjava3</groupId>
    <artifactId>micronaut-rxjava3</artifactId>
</dependency>

implementation("io.micronaut.reactor:micronaut-reactor")

<dependency>
    <groupId>io.micronaut.reactor</groupId>
    <artifactId>micronaut-reactor</artifactId>
</dependency>

implementation("io.micronaut.rxjava1:micronaut-rxjava1")

<dependency>
    <groupId>io.micronaut.rxjava1</groupId>
    <artifactId>micronaut-rxjava1</artifactId>
</dependency>

implementation("io.micronaut.rxjava3:micronaut-rxjava3-http-client")

<dependency>
    <groupId>io.micronaut.rxjava3</groupId>
    <artifactId>micronaut-rxjava3-http-client</artifactId>
</dependency>

implementation("io.micronaut.rxjava3:micronaut-reactor-http-client")

<dependency>
    <groupId>io.micronaut.rxjava3</groupId>
    <artifactId>micronaut-reactor-http-client</artifactId>
</dependency>

Thread Pool Selection Now Manual

If your application does blocking I/O such as communication via JDBC or JPA you should annotate all controllers that interact with these blocking resources with the@ExecuteOn annotation specifying either the default I/O thread pool or a thread pool that you configure an manage to deal with these blocking interactions. For example:

import io.micronaut.http.annotation.*;
import io.micronaut.scheduling.TaskExecutors;
import io.micronaut.scheduling.annotation.ExecuteOn;

@Controller("/executeOn/people")
public class PersonController {

    private final PersonService personService;

    PersonController(
            PersonService personService) {
        this.personService = personService;
    }

    @Get("/{name}")
    @ExecuteOn(TaskExecutors.IO) <b>(1)</b>
    Person byName(String name) {
        return personService.findByName(name);
    }
}

import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@Controller("/executeOn/people")
class PersonController {

    private final PersonService personService

    PersonController(
            PersonService personService) {
        this.personService = personService
    }

    @Get("/{name}")
    @ExecuteOn(TaskExecutors.IO) <b>(1)</b>
    Person byName(String name) {
        return personService.findByName(name)
    }
}

import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@Controller("/executeOn/people")
class PersonController (private val personService: PersonService) {
    @Get("/{name}")
    @ExecuteOn(TaskExecutors.IO) <b>(1)</b>
    fun byName(name: String): Person {
        return personService.findByName(name)
    }
}

Compilation Error with classes in io.micronaut.cache package

If your application fails to compile due to missing classes in the io.micronaut.cache you need to add a dependency on a cache implementation, for example the default cache implementation was Caffeine and this can be restored with the following dependency:

implementation("io.micronaut.cache:micronaut-cache-caffeine")

<dependency>
    <groupId>io.micronaut.cache</groupId>
    <artifactId>micronaut-cache-caffeine</artifactId>
</dependency>

Compilation Error with classes in javax.annotation package

If you application fails to compile referencing classes in the javax.annotation package such as @Nullable and @Nonnull you should update your project to instead import edu.umd.cs.findbugs.annotations from Spot Bugs.

New Group IDs

Some dependencies have new Maven Group IDs so you may need to update your dependency. The following table summarizes changes to group IDs:

AWS Module Changes

The AWS functionality (including support for AWS ParameterStore, AWS Route53 and AWS Lambda Function Client) has been moved out of the Micronaut core therefore if you need AWS related functionality you should use the necessary module.

Kubernetes Discovery Service deprecation

The class io.micronaut.discovery.kubernetes.KubernetesDiscoveryClient , that was deprecated in Micronaut 1.2, has now been removed from Micronaut 2.0. The replacement is the new Micronaut Kubernetes module, with an improved support for running Micronaut applications in a Kubernetes cluster, including support for Kubernetes' ConfigMap s, Secret s and more.

To use the new module, you need to add the following dependency:

implementation("io.micronaut.kubernetes:micronaut-kubernetes-discovery-client")

<dependency>
    <groupId>io.micronaut.kubernetes</groupId>
    <artifactId>micronaut-kubernetes-discovery-client</artifactId>
</dependency>

Transaction Management

For Micronaut 2.0, we recommend you to use the native Micronaut-based transaction management instead of other alternatives such as Spring Transaction Management.

You will use Java EE 7 javax.transaction.Transactional annotation and io.micronaut.transaction.annotation.ReadOnly to mark your transaction demarcations.

To use those annotations, you have to include the micronaut-data-processor dependency in your annotation processor configuration:

annotationProcessor("io.micronaut.data:micronaut-data-processor")

<dependency>
    <groupId>io.micronaut.data</groupId>
    <artifactId>micronaut-data-processor</artifactId>
</dependency>

If you use Hibernate/JPA, you will need to add as well:

implementation("io.micronaut.data:micronaut-data-hibernate-jpa")

<dependency>
    <groupId>io.micronaut.data</groupId>
    <artifactId>micronaut-data-hibernate-jpa</artifactId>
</dependency>

Then, code such as:

import io.micronaut.spring.tx.annotation.Transactional;
...
..
.
@Singleton
public class GenreRepositoryImpl implements GenreRepository {
...
..
.
    @Transactional(readOnly = true)
    public Optional<Genre> findById(@NotNull Long id) {
...
..
    }

    @Transactional
    public Genre save(@NotBlank String name) {
    ...
    ..
    }
}

becomes:

import javax.transaction.Transactional;
import io.micronaut.transaction.annotation.ReadOnly;
...
..
.
@Singleton
public class GenreRepositoryImpl implements GenreRepository {
...
..
.
    @ReadOnly
    public Optional<Genre> findById(@NotNull Long id) {
...
..
    }

    @Transactional
    public Genre save(@NotBlank String name) {
    ...
    ..
    }
}

Micronaut 2 for Groovy Users

Micronaut 2 defaults to Groovy 3 and Spock 2 both of which include significant changes at the language and testing framework level.

In the case of Spock 2 the most important change is that Spock 2 deprecates support for JUnit 4 and the associated JUnit 4 test runner and replaces it with JUnit 5 Platform.

In the case of a Gradle build this change means that when upgrading to Micronaut 2 with Spock 2 you may find your tests don’t execute at all which can give you the false sense of security that the upgrade was successful.

To ensure your Spock 2 tests run in a Micronaut 2 Gradle build you must add the following configuration to your build.gradle to enable JUnit 5 platform:

test {
  useJUnitPlatform()
}

With this configuration is place your Spock 2 tests will execute correctly.

Other Breaking Changes

If the above cases don’t cover your use case see the section onfor a list of other changes that are regarded as breaking in this release.

bash_profile/.bashrc

export MICRONAUT_HOME=~/path/to/micronaut-core
export PATH="$PATH:$MICRONAUT_HOME/cli/build/bin"

Configuring IntelliJ IDEA

To import a Micronaut project into IntelliJ IDEA simply open the build.gradle or pom.xml file and follow the instructions to import the project.

For IntelliJ IDEA if you plan to use the IntelliJ compiler then you should enable annotation processing under the "Build, Execution, Deployment → Compiler → Annotation Processors" by ticking the "Enable annotation processing" checkbox:

Once you have enabled annotation processing in IntelliJ you can run the application and tests directly within the IDE without the need of an external build tool such as Gradle or Maven.

Configuring Eclipse IDE

Configuring Visual Studio Code

./gradlew eclipse

Configuring Gradle

plugins {
  id "net.ltgt.apt" version "0.21" // <1>
}

...
dependencies {
    annotationProcessor("io.micronaut:micronaut-inject-java:2.0.0") // <2>
    implementation("io.micronaut:micronaut-inject:2.0.0")
    ...
    testAnnotationProcessor("io.micronaut:micronaut-inject-java:2.0.0") // <3>
    ...
}

try (ApplicationContext context = ApplicationContext.run()) { <i data-value="1"></i><b>(1)</b>
    MyBean myBean = context.getBean(MyBean.class); <i data-value="2"></i><b>(2)</b>
    // do something with your bean
}

Qualifying By Name

public interface Engine { <b>(1)</b>
    int getCylinders();
    String start();
}

@Singleton
public class V6Engine implements Engine {  <b>(2)</b>
    public String start() {
        return "Starting V6";
    }

    public int getCylinders() {
        return 6;
    }
}

@Singleton
public class V8Engine implements Engine {
    public String start() {
        return "Starting V8";
    }

    public int getCylinders() {
        return 8;
    }

}

@Singleton
public class Vehicle {
    private final Engine engine;

    @Inject
    public Vehicle(@Named("v8") Engine engine) {<b>(4)</b>
        this.engine = engine;
    }

    public String start() {
        return engine.start();<b>(5)</b>
    }
}

interface Engine { <b>(1)</b>
    int getCylinders()
    String start()
}

@Singleton
class V6Engine implements Engine { <b>(2)</b>
    int cylinders = 6

    String start() {
        "Starting V6"
    }
}

@Singleton
class V8Engine implements Engine { <b>(3)</b>
    int cylinders = 8

    String start() {
        "Starting V8"
    }
}

@Singleton
class Vehicle {
    final Engine engine

    @Inject Vehicle(@Named('v8') Engine engine) { <b>(4)</b>
        this.engine = engine
    }

    String start() {
        engine.start() <b>(5)</b>
    }
}

interface Engine { <b>(1)</b>
    val cylinders: Int
    fun start(): String
}

@Singleton
class V6Engine : Engine {  <b>(2)</b>

    override var cylinders: Int = 6

    override fun start(): String {
        return "Starting V6"
    }
}

@Singleton
class V8Engine : Engine {

    override var cylinders: Int = 8

    override fun start(): String {
        return "Starting V8"
    }

}

@Singleton
class Vehicle @Inject
constructor(@param:Named("v8") private val engine: Engine)<b>(4)</b>
{

    fun start(): String {
        return engine.start()<b>(5)</b>
    }
}

Qualifying By Annotation

import javax.inject.Qualifier;
import java.lang.annotation.Retention;

import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Qualifier
@Retention(RUNTIME)
public @interface V8 {
}

import javax.inject.Qualifier
import java.lang.annotation.Retention

import static java.lang.annotation.RetentionPolicy.RUNTIME

@Qualifier
@Retention(RUNTIME)
@interface V8 {
}

import javax.inject.Qualifier
import java.lang.annotation.Retention
import java.lang.annotation.RetentionPolicy.RUNTIME

@Qualifier
@Retention(RUNTIME)
annotation class V8

@Inject Vehicle(@V8 Engine engine) {
        this.engine = engine;
    }

@Inject Vehicle(@V8 Engine engine) {
        this.engine = engine
    }

@Inject constructor(@V8 val engine: Engine) {

Primary and Secondary Beans

public interface ColorPicker {
    String color();
}

interface ColorPicker {
    String color()
}

interface ColorPicker {
    fun color(): String
}

import io.micronaut.context.annotation.Primary;
import javax.inject.Singleton;

@Primary
@Singleton
class Green implements ColorPicker {

    @Override
    public String color() {
        return "green";
    }
}

import io.micronaut.context.annotation.Primary
import javax.inject.Singleton

@Primary
@Singleton
class Green implements ColorPicker {

    @Override
    String color() {
        return "green"
    }
}

import io.micronaut.context.annotation.Primary
import javax.inject.Singleton


@Primary
@Singleton
class Green: ColorPicker {
    override fun color(): String {
        return "green"
    }
}

import javax.inject.Singleton;


@Singleton
public class Blue implements ColorPicker {

    @Override
    public String color() {
        return "blue";
    }
}

import javax.inject.Singleton


@Singleton
class Blue implements ColorPicker {

    @Override
    String color() {
        return "blue"
    }
}

import javax.inject.Singleton


@Singleton
class Blue: ColorPicker {
    override fun color(): String {
        return "blue"
    }
}

@Controller("/testPrimary")
public class TestController {

    protected final ColorPicker colorPicker;

    public TestController(ColorPicker colorPicker) { <b>(1)</b>
        this.colorPicker = colorPicker;
    }

    @Get
    public String index() {
        return colorPicker.color();
    }
}

@Controller("/test")
class TestController {

    protected final ColorPicker colorPicker

    TestController(ColorPicker colorPicker) { <b>(1)</b>
        this.colorPicker = colorPicker
    }

    @Get
    String index() {
        colorPicker.color()
    }
}

@Controller("/test")
class TestController(val colorPicker: ColorPicker) { <b>(1)</b>

    @Get
    fun index(): String {
        return colorPicker.color()
    }
}

Enabling Eager Initialization of Singletons

public class Application {

    public static void main(String[] args) {
        Micronaut.build(args)
            .eagerInitSingletons(true) <i data-value="1"></i><b>(1)</b>
            .mainClass(Application.class)
            .start();
    }
}

Override of newApplicationContextBuilder()

public class MyFunctionHandler extends MicronautRequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
...
    @Nonnull
    @Override
    protected ApplicationContextBuilder newApplicationContextBuilder() {
        ApplicationContextBuilder builder = super.newApplicationContextBuilder();
        builder.eagerInitSingletons(true);
        return builder;
    }
    ...
}

Enabling Eager Initialization of Configuration

public class Application {

    public static void main(String[] args) {
        Micronaut.build(args)
            .eagerInitConfiguration(true) <i data-value="1"></i><b>(1)</b>
            .mainClass(Application.class)
            .start();
    }
}

Declaring Another Scope

@Driver
@Prototype
class Foo {}

Using @DefaultScope

@Requires(classes = Car.class )
@DefaultScope(Singleton.class) <i data-value="1"></i><b>(1)</b>
@Documented
@Retention(RUNTIME)
public @interface Driver {
}

Programmatically Disabling Beans

Factory methods can return throw DisabledBeanException to allow for beans to be disabled conditionally. The use of@Requires should always be the preferred method to conditionally create beans and throwing an exception a factory method should only be done if using@Requires is not possible.

For example:

public interface Engine {
    Integer getCylinders();
}

@EachProperty("engines")
public class EngineConfiguration implements Toggleable {

    private boolean enabled = true;
    private Integer cylinders;

    @NotNull
    public Integer getCylinders() {
        return cylinders;
    }

    public void setCylinders(Integer cylinders) {
        this.cylinders = cylinders;
    }

    @Override
    public boolean isEnabled() {
        return enabled;
    }

    public void setEnabled(boolean enabled) {
        this.enabled = enabled;
    }

}

@Factory
public class EngineFactory {

    @EachBean(EngineConfiguration.class)
    public Engine buildEngine(EngineConfiguration engineConfiguration) {
        if (engineConfiguration.isEnabled()) {
            return engineConfiguration::getCylinders;
        } else {
            throw new DisabledBeanException("Engine configuration disabled");
        }
    }
}

interface Engine {
    Integer getCylinders()
}

@EachProperty("engines")
class EngineConfiguration implements Toggleable {
    boolean enabled = true
    @NotNull
    Integer cylinders
}

@Factory
class EngineFactory {

    @EachBean(EngineConfiguration)
    Engine buildEngine(EngineConfiguration engineConfiguration) {
        if (engineConfiguration.enabled) {
            (Engine){ -> engineConfiguration.cylinders }
        } else {
            throw new DisabledBeanException("Engine configuration disabled")
        }
    }
}

interface Engine {
    fun getCylinders(): Int
}

@EachProperty("engines")
class EngineConfiguration : Toggleable {

    val enabled = true

    @NotNull
    val cylinders: Int? = null

    override fun isEnabled(): Boolean {
        return enabled
    }
}

@Factory
class EngineFactory {

    @EachBean(EngineConfiguration::class)
    fun buildEngine(engineConfiguration: EngineConfiguration): Engine? {
        return if (engineConfiguration.isEnabled) {
            object : Engine {
                override fun getCylinders(): Int {
                    return engineConfiguration.cylinders!!
                }
            }
        } else {
            throw DisabledBeanException("Engine configuration disabled")
        }
    }
}

Injection Point

A common use case with factories is to take advantage of annotation metadata from the point at which an object is injected such that behaviour can be modified based on said metadata.

Consider an annotation such as the following:

@Documented
@Retention(RUNTIME)
@Target(ElementType.PARAMETER)
public @interface Cylinders {
    int value() default 8;
}

@Documented
@Retention(RUNTIME)
@Target(ElementType.PARAMETER)
@interface Cylinders {
    int value() default 8
}

@MustBeDocumented
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class Cylinders(val value: Int = 8)

The above annotation could be used to customize the type of engine we want to inject into a vehicle at the point at which the injection point is defined:

@Singleton
class Vehicle {
    private final Engine engine;
    Vehicle(@Cylinders(6) Engine engine) {
        this.engine = engine;
    }

    String start() {
        return engine.start();
    }
}

@Singleton
class Vehicle {
    private final Engine engine
    Vehicle(@Cylinders(6) Engine engine) {
        this.engine = engine
    }

    String start() {
        return engine.start()
    }
}

@Singleton
internal class Vehicle(@param:Cylinders(6) private val engine: Engine) {
    fun start(): String {
        return engine.start()
    }
}

The above Vehicle class specifies an annotation value of @Cylinders(6) indicating an Engine of six cylinders is needed.

To implement this use case you can define a factory that accepts theInjectionPoint instance which can be used to analyze the annotation values defined:

@Factory
class EngineFactory {

    @Prototype
    Engine v8Engine(InjectionPoint<?> injectionPoint, CrankShaft crankShaft) { <b>(1)</b>
        final int cylinders = injectionPoint
                .getAnnotationMetadata()
                .intValue(Cylinders.class).orElse(8); <b>(2)</b>
        switch (cylinders) { <b>(3)</b>
            case 6:
                return new V6Engine(crankShaft);
            case 8:
                return new V8Engine(crankShaft);
            default:
                throw new IllegalArgumentException("Unsupported number of cylinders specified: " + cylinders);
        }
    }
}

@Factory
class EngineFactory {

    @Prototype
    Engine v8Engine(InjectionPoint<?> injectionPoint, CrankShaft crankShaft) { <b>(1)</b>
        final int cylinders = injectionPoint
                .getAnnotationMetadata()
                .intValue(Cylinders.class).orElse(8) <b>(2)</b>
        switch (cylinders) { <b>(3)</b>
            case 6:
                return new V6Engine(crankShaft)
            case 8:
                return new V8Engine(crankShaft)
            default:
                throw new IllegalArgumentException("Unsupported number of cylinders specified: $cylinders")
        }
    }
}

@Factory
internal class EngineFactory {

    @Prototype
    fun v8Engine(injectionPoint: InjectionPoint<*>, crankShaft: CrankShaft): Engine { <b>(1)</b>
        val cylinders = injectionPoint
                .annotationMetadata
                .intValue(Cylinders::class.java).orElse(8) <b>(2)</b>
        return when (cylinders) { <b>(3)</b>
            6 -> V6Engine(crankShaft)
            8 -> V8Engine(crankShaft)
            else -> throw IllegalArgumentException("Unsupported number of cylinders specified: $cylinders")
        }
    }
}

Using @Requires

@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
public class JdbcBookService implements BookService {

    DataSource dataSource;

    public JdbcBookService(DataSource dataSource) {
        this.dataSource = dataSource;
    }

Using @Requires

@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
class JdbcBookService implements BookService {

    DataSource dataSource

Using @Requires

@Singleton
@Requirements(Requires(beans = [DataSource::class]), Requires(property = "datasource.url"))
class JdbcBookService(internal var dataSource: DataSource) : BookService {

Using a @Requires meta-annotation

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PACKAGE, ElementType.TYPE})
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
public @interface RequiresJdbc {
}

Using a @Requires meta-annotation

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target([ElementType.PACKAGE, ElementType.TYPE])
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
@interface RequiresJdbc {
}

Using a @Requires meta-annotation

@Documented
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FILE)
@Requirements(Requires(beans = [DataSource::class]), Requires(property = "datasource.url"))
annotation class RequiresJdbc

Using a meta-annotation

@RequiresJdbc
public class JdbcBookService implements BookService {
    ...
}

Configuration Requirements

@Requires(property="foo") <i data-value="1"></i><b>(1)</b>
@Requires(property="foo", value="John") <i data-value="2"></i><b>(2)</b>
@Requires(property="foo", value="John", defaultValue="John") <i data-value="3"></i><b>(3)</b>
@Requires(property="foo", notEquals="Sally") <i data-value="4"></i><b>(4)</b>

Debugging Conditional Beans

<logger name="io.micronaut.context.condition" level="DEBUG"/>

JdbcBookService

@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
public class JdbcBookService implements BookService {

    DataSource dataSource;

    public JdbcBookService(DataSource dataSource) {
        this.dataSource = dataSource;
    }

JdbcBookService

@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
class JdbcBookService implements BookService {

    DataSource dataSource

JdbcBookService

@Singleton
@Requirements(Requires(beans = [DataSource::class]), Requires(property = "datasource.url"))
class JdbcBookService(internal var dataSource: DataSource) : BookService {

Using @Replaces

@Replaces(JdbcBookService.class) <b>(1)</b>
@Singleton
public class MockBookService implements BookService {

    Map<String, Book> bookMap = new LinkedHashMap<>();

    @Override
    public Book findBook(String title) {
        return bookMap.get(title);
    }
}

Using @Replaces

@Replaces(JdbcBookService.class) <b>(1)</b>
@Singleton
class MockBookService implements BookService {

    Map<String, Book> bookMap = [:]

    @Override
    Book findBook(String title) {
        bookMap.get(title)
    }
}

Using @Replaces

@Replaces(JdbcBookService::class) <b>(1)</b>
@Singleton
class MockBookService : BookService {

    var bookMap: Map<String, Book> = LinkedHashMap()

    override fun findBook(title: String): Book? {
        return bookMap[title]
    }
}

Factory Replacement

The @Replaces annotation also supports a factory argument. That argument allows the replacement of factory beans in their entirety or specific types created by the factory.

For example, it may be desired to replace all or part of the given factory class:

@Factory
public class BookFactory {

    @Singleton
    Book novel() {
        return new Book("A Great Novel");
    }

    @Singleton
    TextBook textBook() {
        return new TextBook("Learning 101");
    }
}

@Factory
class BookFactory {

    @Singleton
    Book novel() {
        new Book('A Great Novel')
    }

    @Singleton
    TextBook textBook() {
        new TextBook('Learning 101')
    }
}

@Factory
class BookFactory {

    @Singleton
    internal fun novel(): Book {
        return Book("A Great Novel")
    }

    @Singleton
    internal fun textBook(): TextBook {
        return TextBook("Learning 101")
    }
}

In this example, the BookFactory#textBook() will not be replaced because this factory does not have a factory method that returns a TextBook.

@Factory
@Replaces(factory = BookFactory.class)
public class CustomBookFactory {

    @Singleton
    Book otherNovel() {
        return new Book("An OK Novel");
    }
}

@Factory
@Replaces(factory = BookFactory.class)
class CustomBookFactory {

    @Singleton
    Book otherNovel() {
        new Book('An OK Novel')
    }
}

@Factory
@Replaces(factory = BookFactory::class)
class CustomBookFactory {

    @Singleton
    internal fun otherNovel(): Book {
        return Book("An OK Novel")
    }
}

It may be the case that you don’t wish for the factory methods to be replaced, except for a select few. For that use case, you can apply the @Replaces annotation on the method and denote the factory that it should apply to.

@Factory
public class TextBookFactory {

    @Singleton
    @Replaces(value = TextBook.class, factory = BookFactory.class)
    TextBook textBook() {
        return new TextBook("Learning 305");
    }
}

@Factory
class TextBookFactory {

    @Singleton
    @Replaces(value = TextBook.class, factory = BookFactory.class)
    TextBook textBook() {
        new TextBook('Learning 305')
    }
}

@Factory
class TextBookFactory {

    @Singleton
    @Replaces(value = TextBook::class, factory = BookFactory::class)
    internal fun textBook(): TextBook {
        return TextBook("Learning 305")
    }
}

The BookFactory#novel() method will not be replaced because the TextBook class is defined in the annotation.

Default Implementation

When exposing an API, it may be desirable for the default implementation of an interface to not be exposed as part of the public API. Doing so would prevent users from being able to replace the implementation because they would not be able to reference the class. The solution is to annotate the interface with DefaultImplementation to indicate which implementation should be replaced if a user creates a bean that @Replaces(YourInterface.class) .

For example consider:

A public API contract

import io.micronaut.context.annotation.DefaultImplementation;

@DefaultImplementation(DefaultResponseStrategy.class)
public interface ResponseStrategy {

}

import io.micronaut.context.annotation.DefaultImplementation

@DefaultImplementation(DefaultResponseStrategy)
interface ResponseStrategy {
}

import io.micronaut.context.annotation.DefaultImplementation

@DefaultImplementation(DefaultResponseStrategy::class)
interface ResponseStrategy

The default implementation

import javax.inject.Singleton;

@Singleton
class DefaultResponseStrategy implements ResponseStrategy {

}

import javax.inject.Singleton

@Singleton
class DefaultResponseStrategy implements ResponseStrategy {

}

import javax.inject.Singleton

@Singleton
internal class DefaultResponseStrategy : ResponseStrategy

The custom implementation

import io.micronaut.context.annotation.Replaces;
import javax.inject.Singleton;

@Singleton
@Replaces(ResponseStrategy.class)
public class CustomResponseStrategy implements ResponseStrategy {

}

import io.micronaut.context.annotation.Replaces
import javax.inject.Singleton

@Singleton
@Replaces(ResponseStrategy)
class CustomResponseStrategy implements ResponseStrategy {

}

import io.micronaut.context.annotation.Replaces
import javax.inject.Singleton

@Singleton
@Replaces(ResponseStrategy::class)
class CustomResponseStrategy : ResponseStrategy

In the above example, the CustomResponseStrategy will replace the DefaultResponseStrategy because the DefaultImplementation annotation points to the DefaultResponseStrategy .

package-info.groovy

@Configuration
package my.package

import io.micronaut.context.annotation.Configuration

package-info.groovy

@Configuration
@Requires(beans = javax.sql.DataSource)
package my.package

When The Context Starts

import javax.annotation.PostConstruct; <b>(1)</b>
import javax.inject.Singleton;

@Singleton
public class V8Engine implements Engine {
    private int cylinders = 8;
    private boolean initialized = false; <b>(2)</b>

    public String start() {
        if(!initialized) {
            throw new IllegalStateException("Engine not initialized!");
        }

        return "Starting V8";
    }

    @Override
    public int getCylinders() {
        return cylinders;
    }

    public boolean isIntialized() {
        return this.initialized;
    }

    @PostConstruct <b>(3)</b>
    public void initialize() {
        this.initialized = true;
    }
}

import javax.annotation.PostConstruct <b>(1)</b>
import javax.inject.Singleton

@Singleton
class V8Engine implements Engine {
    int cylinders = 8
    boolean initialized = false <b>(2)</b>

    String start() {
        if(!initialized) throw new IllegalStateException("Engine not initialized!")

        return "Starting V8"
    }

    @PostConstruct <b>(3)</b>
    void initialize() {
        this.initialized = true
    }
}

import javax.annotation.PostConstruct
import javax.inject.Singleton


@Singleton
class V8Engine : Engine {
    override val cylinders = 8
    var isIntialized = false
        private set <b>(2)</b>

    override fun start(): String {
        check(isIntialized) { "Engine not initialized!" }

        return "Starting V8"
    }

    @PostConstruct <b>(3)</b>
    fun initialize() {
        this.isIntialized = true
    }
}

When The Context Closes

import javax.annotation.PreDestroy; <b>(1)</b>
import javax.inject.Singleton;
import java.util.concurrent.atomic.AtomicBoolean;

@Singleton
public class PreDestroyBean implements AutoCloseable {

    AtomicBoolean stopped = new AtomicBoolean(false);

    @PreDestroy <b>(2)</b>
    @Override
    public void close() throws Exception {
        stopped.compareAndSet(false, true);
    }
}

import javax.annotation.PreDestroy <b>(1)</b>
import java.util.concurrent.atomic.AtomicBoolean
import javax.inject.Singleton

@Singleton
class PreDestroyBean implements AutoCloseable {

    AtomicBoolean stopped = new AtomicBoolean(false)

    @PreDestroy <b>(2)</b>
    @Override
    void close() throws Exception {
        stopped.compareAndSet(false, true)
    }
}

import javax.annotation.PreDestroy
import javax.inject.Singleton
import java.util.concurrent.atomic.AtomicBoolean

@Singleton
class PreDestroyBean : AutoCloseable {

    internal var stopped = AtomicBoolean(false)

    @PreDestroy <b>(2)</b>
    @Throws(Exception::class)
    override fun close() {
        stopped.compareAndSet(false, true)
    }
}

import io.micronaut.context.annotation.Bean;
import io.micronaut.context.annotation.Factory;

import javax.inject.Singleton;

@Factory
public class ConnectionFactory {

    @Bean(preDestroy = "stop") <b>(1)</b>
    @Singleton
    public Connection connection() {
        return new Connection();
    }
}

import io.micronaut.context.annotation.Bean
import io.micronaut.context.annotation.Factory

import javax.inject.Singleton

@Factory
class ConnectionFactory {

    @Bean(preDestroy = "stop") <b>(1)</b>
    @Singleton
    Connection connection() {
        new Connection()
    }
}

import io.micronaut.context.annotation.Bean
import io.micronaut.context.annotation.Factory

import javax.inject.Singleton

@Factory
class ConnectionFactory {

    @Bean(preDestroy = "stop") <b>(1)</b>
    @Singleton
    fun connection(): Connection {
        return Connection()
    }
}

import java.util.concurrent.atomic.AtomicBoolean;

public class Connection {

    AtomicBoolean stopped = new AtomicBoolean(false);

    public void stop() { <b>(2)</b>
        stopped.compareAndSet(false, true);
    }

}

import java.util.concurrent.atomic.AtomicBoolean

class Connection {

    AtomicBoolean stopped = new AtomicBoolean(false)

    void stop() { <b>(2)</b>
        stopped.compareAndSet(false, true)
    }

}

import java.util.concurrent.atomic.AtomicBoolean

class Connection {

    internal var stopped = AtomicBoolean(false)

    fun stop() { <b>(2)</b>
        stopped.compareAndSet(false, true)
    }

}

Publishing Events

The ApplicationEventPublisher API supports events of any type, however all events that Micronaut publishes extendApplicationEvent.

To publish an event, obtain an instance of ApplicationEventPublisher either directly from the context or through dependency injection, and execute the publishEvent method with your event object.

public class SampleEvent {
    private String message = "Something happened";

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

import io.micronaut.context.event.ApplicationEventPublisher;
import javax.inject.Inject;
import javax.inject.Singleton;

@Singleton
public class SampleEventEmitterBean {

    @Inject
    ApplicationEventPublisher eventPublisher;

    public void publishSampleEvent() {
        eventPublisher.publishEvent(new SampleEvent());
    }

}

class SampleEvent {
    String message = "Something happened"
}

import io.micronaut.context.event.ApplicationEventPublisher
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class SampleEventEmitterBean {

    @Inject
    ApplicationEventPublisher eventPublisher

    void publishSampleEvent() {
        eventPublisher.publishEvent(new SampleEvent())
    }

}

data class SampleEvent(val message: String = "Something happened")

import io.micronaut.context.event.ApplicationEventPublisher
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class SampleEventEmitterBean {

    @Inject
    internal var eventPublisher: ApplicationEventPublisher? = null

    fun publishSampleEvent() {
        eventPublisher!!.publishEvent(SampleEvent())
    }

}

Listening for Events

To listen to an event, register a bean that implements ApplicationEventListener where the generic type is the type of event the listener should be executed for.

import io.micronaut.context.event.ApplicationEventListener;
import io.micronaut.docs.context.events.SampleEvent;

@Singleton
public class SampleEventListener implements ApplicationEventListener<SampleEvent> {
    private int invocationCounter = 0;

    @Override
    public void onApplicationEvent(SampleEvent event) {
        invocationCounter++;
    }

    public int getInvocationCounter() {
        return invocationCounter;
    }
}

import io.micronaut.context.ApplicationContext;
import io.micronaut.docs.context.events.SampleEventEmitterBean;
import org.junit.Test;

import static org.junit.Assert.assertEquals;

public class SampleEventListenerSpec {

    @Test
    public void testEventListenerIsNotified() {
        try (ApplicationContext context = ApplicationContext.run()) {
            SampleEventEmitterBean emitter = context.getBean(SampleEventEmitterBean.class);
            SampleEventListener listener = context.getBean(SampleEventListener.class);
            assertEquals(0, listener.getInvocationCounter());
            emitter.publishSampleEvent();
            assertEquals(1, listener.getInvocationCounter());
        }

    }

}

import io.micronaut.context.event.ApplicationEventListener
import io.micronaut.docs.context.events.SampleEvent

@Singleton
class SampleEventListener implements ApplicationEventListener<SampleEvent> {
    int invocationCounter = 0

    @Override
    void onApplicationEvent(SampleEvent event) {
        invocationCounter++
    }
}

import io.micronaut.context.ApplicationContext
import io.micronaut.docs.context.events.SampleEventEmitterBean
import spock.lang.Specification

class SampleEventListenerSpec extends Specification {

    void "test event listener is notified"() {
        given:
        ApplicationContext context = ApplicationContext.run()
        SampleEventEmitterBean emitter = context.getBean(SampleEventEmitterBean)
        SampleEventListener listener = context.getBean(SampleEventListener)
        assert listener.invocationCounter == 0

        when:
        emitter.publishSampleEvent()

        then:
        listener.invocationCounter == 1

        cleanup:
        context.close()
    }
}

import io.micronaut.context.event.ApplicationEventListener
import io.micronaut.docs.context.events.SampleEvent

@Singleton
class SampleEventListener : ApplicationEventListener<SampleEvent> {
    var invocationCounter = 0

    override fun onApplicationEvent(event: SampleEvent) {
        invocationCounter++
    }
}

import io.kotlintest.shouldBe
import io.kotlintest.specs.AnnotationSpec
import io.micronaut.context.ApplicationContext
import io.micronaut.docs.context.events.SampleEventEmitterBean

class SampleEventListenerSpec : AnnotationSpec() {

    @Test
    fun testEventListenerWasNotified() {
        val context = ApplicationContext.run()
        val emitter = context.getBean(SampleEventEmitterBean::class.java)
        val listener = context.getBean(SampleEventListener::class.java)
        listener.invocationCounter.shouldBe(0)
        emitter.publishSampleEvent()
        listener.invocationCounter.shouldBe(1)

        context.close()
    }
}

Alternatively you can use the@EventListener annotation if you do not wish to specifically implement an interface or utilize one of the built in events likeStartupEvent andShutdownEvent:

import io.micronaut.docs.context.events.SampleEvent;
import io.micronaut.context.event.StartupEvent;
import io.micronaut.context.event.ShutdownEvent;
import io.micronaut.runtime.event.annotation.EventListener;

@Singleton
public class SampleEventListener {
    private int invocationCounter = 0;

    @EventListener
    public void onSampleEvent(SampleEvent event) {
        invocationCounter++;
    }

    @EventListener
    public void onStartupEvent(StartupEvent event) {
        // startup logic here
    }

    @EventListener
    public void onShutdownEvent(ShutdownEvent event) {
        // shutdown logic here
    }

    public int getInvocationCounter() {
        return invocationCounter;
    }
}

import io.micronaut.docs.context.events.SampleEvent
import io.micronaut.context.event.StartupEvent
import io.micronaut.context.event.ShutdownEvent
import io.micronaut.runtime.event.annotation.EventListener

@Singleton
class SampleEventListener {
    int invocationCounter = 0

    @EventListener
    void onSampleEvent(SampleEvent event) {
        invocationCounter++
    }

    @EventListener
    void onStartupEvent(StartupEvent event) {
        // startup logic here
    }

    @EventListener
    void onShutdownEvent(ShutdownEvent event) {
        // shutdown logic here
    }
}

import io.micronaut.docs.context.events.SampleEvent
import io.micronaut.context.event.StartupEvent
import io.micronaut.context.event.ShutdownEvent
import io.micronaut.runtime.event.annotation.EventListener

@Singleton
class SampleEventListener {
    var invocationCounter = 0

    @EventListener
    internal fun onSampleEvent(event: SampleEvent) {
        invocationCounter++
    }

    @EventListener
    internal fun onStartupEvent(event: StartupEvent) {
        // startup logic here
    }

    @EventListener
    internal fun onShutdownEvent(event: ShutdownEvent) {
        // shutdown logic here
    }
}

If your listener performs work that could take a while then you can use the@Async annotation to run the operation on a separate thread:

import io.micronaut.docs.context.events.SampleEvent;
import io.micronaut.runtime.event.annotation.EventListener;
import io.micronaut.scheduling.annotation.Async;

@Singleton
public class SampleEventListener {
    private AtomicInteger invocationCounter = new AtomicInteger(0);

    @EventListener
    @Async
    public void onSampleEvent(SampleEvent event) {
        invocationCounter.getAndIncrement();
    }

    public int getInvocationCounter() {
        return invocationCounter.get();
    }
}

import io.micronaut.context.ApplicationContext;
import io.micronaut.docs.context.events.SampleEventEmitterBean;
import org.junit.Test;

import static org.junit.Assert.assertEquals;
import static java.util.concurrent.TimeUnit.SECONDS;
import static org.awaitility.Awaitility.await;
import static org.hamcrest.Matchers.equalTo;

public class SampleEventListenerSpec {

    @Test
    public void testEventListenerIsNotified() {
        try (ApplicationContext context = ApplicationContext.run()) {
            SampleEventEmitterBean emitter = context.getBean(SampleEventEmitterBean.class);
            SampleEventListener listener = context.getBean(SampleEventListener.class);
            assertEquals(0, listener.getInvocationCounter());
            emitter.publishSampleEvent();
            await().atMost(10, SECONDS).until(listener::getInvocationCounter, equalTo(1));
        }
    }

}

import io.micronaut.docs.context.events.SampleEvent
import io.micronaut.runtime.event.annotation.EventListener
import io.micronaut.scheduling.annotation.Async

@Singleton
class SampleEventListener {
    AtomicInteger invocationCounter = new AtomicInteger(0)

    @EventListener
    @Async
    void onSampleEvent(SampleEvent event) {
        invocationCounter.getAndIncrement()
    }
}

import io.micronaut.context.ApplicationContext
import io.micronaut.docs.context.events.SampleEventEmitterBean
import spock.lang.Specification
import spock.util.concurrent.PollingConditions

class SampleEventListenerSpec extends Specification {

    void "test event listener is notified"() {
        given:
        ApplicationContext context = ApplicationContext.run()
        SampleEventEmitterBean emitter = context.getBean(SampleEventEmitterBean)
        SampleEventListener listener = context.getBean(SampleEventListener)
        assert listener.invocationCounter.get() == 0

        when:
        emitter.publishSampleEvent()

        then:
        new PollingConditions().eventually {
            listener.invocationCounter.get() == 1
        }

        cleanup:
        context.close()

    }
}

import io.micronaut.docs.context.events.SampleEvent
import io.micronaut.runtime.event.annotation.EventListener
import io.micronaut.scheduling.annotation.Async
import java.util.concurrent.atomic.AtomicInteger

@Singleton
open class SampleEventListener {

    var invocationCounter = AtomicInteger(0)

    @EventListener
    @Async
    open fun onSampleEvent(event: SampleEvent) {
        println("Incrementing invocation counter...")
        invocationCounter.getAndIncrement()
    }
}

import io.kotlintest.eventually
import io.kotlintest.seconds
import io.kotlintest.shouldBe
import io.kotlintest.specs.AnnotationSpec
import io.micronaut.context.ApplicationContext
import io.micronaut.docs.context.events.SampleEventEmitterBean
import org.opentest4j.AssertionFailedError

class SampleEventListenerSpec : AnnotationSpec() {

    @Test
//    @Ignore // TODO can't get this to pass on CI, any help is welcome
    fun testEventListenerWasNotified() {
        val context = ApplicationContext.run()
        val emitter = context.getBean(SampleEventEmitterBean::class.java)
        val listener = context.getBean(SampleEventListener::class.java)
        listener.invocationCounter.get().shouldBe(0)
        emitter.publishSampleEvent()

        eventually(5.seconds,  AssertionFailedError::class.java) {
            println("Current value of counter: " + listener.invocationCounter.get())
            listener.invocationCounter.get().shouldBe(1)
        }

        context.close()
    }
}

The event listener will by default run on the scheduled executor. You can configure this thread pool as required in application.yml :

micronaut:
    executors:
        scheduled:
            type: scheduled
            core-pool-size: 30

Making a Bean Available for Introspection

Unlike the JDK’s Introspector every class is not automatically available for introspection, to make a class available for introspection you must as a minimum enable Micronaut’s annotation processor ( micronaut-inject-java for Java and Kotlin and micronaut-inject-groovy for Groovy) in your build and ensure you have a runtime time dependency on micronaut-core .

annotationProcessor("io.micronaut:micronaut-inject-java:2.0.0")

<annotationProcessorPaths>
    <path>
        <groupId>io.micronaut</groupId>
        <artifactId>micronaut-inject-java</artifactId>
        <version>2.0.0</version>
    </path>
</annotationProcessorPaths>

runtime("io.micronaut:micronaut-core:2.0.0")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-core</artifactId>
    <version>2.0.0</version>
    <scope>runtime</scope>
</dependency>

Once your build is configured you have a few ways to generate introspection data.

import io.micronaut.core.annotation.Introspected;

@Introspected
public class Person {

    private String name;
    private int age = 18;

    public Person(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

import groovy.transform.Canonical
import io.micronaut.core.annotation.Introspected

@Introspected
@Canonical
class Person {

    String name
    int age = 18

    Person(String name) {
        this.name = name
    }
}

import io.micronaut.core.annotation.Introspected

@Introspected
data class Person(var name : String) {
    var age : Int = 18
}

final BeanIntrospection<Person> introspection = BeanIntrospection.getIntrospection(Person.class); <b>(1)</b>
        Person person = introspection.instantiate("John"); <b>(2)</b>
        System.out.println("Hello " + person.getName());

        final BeanProperty<Person, String> property = introspection.getRequiredProperty("name", String.class); <b>(3)</b>
        property.set(person, "Fred"); <b>(4)</b>
        String name = property.get(person); <b>(5)</b>
        System.out.println("Hello " + person.getName());

def introspection = BeanIntrospection.getIntrospection(Person) <b>(1)</b>
        Person person = introspection.instantiate("John") <b>(2)</b>
        println("Hello ${person.name}")

        BeanProperty<Person, String> property = introspection.getRequiredProperty("name", String) <b>(3)</b>
        property.set(person, "Fred") <b>(4)</b>
        String name = property.get(person) <b>(5)</b>
        println("Hello ${person.name}")

val introspection = BeanIntrospection.getIntrospection(Person::class.java) <b>(1)</b>
        val person : Person = introspection.instantiate("John") <b>(2)</b>
        print("Hello ${person.name}")

        val property : BeanProperty<Person, String> = introspection.getRequiredProperty("name", String::class.java) <b>(3)</b>
        property.set(person, "Fred") <b>(4)</b>
        val name = property.get(person) <b>(5)</b>
        print("Hello ${person.name}")

import io.micronaut.core.annotation.Creator;
import io.micronaut.core.annotation.Introspected;

import javax.annotation.concurrent.Immutable;

@Introspected
@Immutable
public class Vehicle {

    private final String make;
    private final String model;
    private final int axels;

    public Vehicle(String make, String model) {
        this(make, model, 2);
    }

    @Creator <b>(1)</b>
    public Vehicle(String make, String model, int axels) {
        this.make = make;
        this.model = model;
        this.axels = axels;
    }

    public String getMake() {
        return make;
    }

    public String getModel() {
        return model;
    }

    public int getAxels() {
        return axels;
    }
}

import io.micronaut.core.annotation.Creator
import io.micronaut.core.annotation.Introspected

import javax.annotation.concurrent.Immutable

@Introspected
@Immutable
class Vehicle {

    private final String make
    private final String model
    private final int axels

    Vehicle(String make, String model) {
        this(make, model, 2)
    }

    @Creator <b>(1)</b>
    Vehicle(String make, String model, int axels) {
        this.make = make
        this.model = model
        this.axels = axels
    }

    String getMake() {
        make
    }

    String getModel() {
        model
    }

    int getAxels() {
        axels
    }
}

import io.micronaut.core.annotation.Creator
import io.micronaut.core.annotation.Introspected

import javax.annotation.concurrent.Immutable

@Introspected
@Immutable
class Vehicle @Creator constructor(val make: String, val model: String, val axels: Int) { <b>(1)</b>

    constructor(make: String, model: String) : this(make, model, 2) {}
}

import io.micronaut.core.annotation.Creator;
import io.micronaut.core.annotation.Introspected;

import javax.annotation.concurrent.Immutable;

@Introspected
@Immutable
public class Business {

    private String name;

    private Business(String name) {
        this.name = name;
    }

    @Creator <b>(1)</b>
    public static Business forName(String name) {
        return new Business(name);
    }

    public String getName() {
        return name;
    }

}

import io.micronaut.core.annotation.Creator
import io.micronaut.core.annotation.Introspected

import javax.annotation.concurrent.Immutable

@Introspected
@Immutable
class Business {

    private String name

    private Business(String name) {
        this.name = name
    }

    @Creator <b>(1)</b>
    static Business forName(String name) {
        new Business(name)
    }

    String getName() {
        name
    }

}

import io.micronaut.core.annotation.Creator
import io.micronaut.core.annotation.Introspected

import javax.annotation.concurrent.Immutable

@Introspected
@Immutable
class Business private constructor(val name: String) {
    companion object {

        @Creator <b>(1)</b>
        fun forName(name: String): Business {
            return Business(name)
        }
    }

}

import io.micronaut.core.annotation.Introspected;

@Introspected(classes = Person.class)
public class PersonConfiguration {
}

import io.micronaut.core.annotation.Introspected

@Introspected(classes = Person)
class PersonConfiguration {
}

import io.micronaut.core.annotation.Introspected

@Introspected(classes = [Person::class])
class PersonConfiguration

The BeanWrapper API

ABeanProperty provides raw access to read and write a property value for a given class and does not provide any automatic type conversion.

It is expected that the values you pass to the set and get methods match the underlying property type otherwise an exception will occur.

To provide additional type conversion smarts theBeanWrapper interface allows wrapping an existing bean instance and setting and getting properties from the bean, plus performing type conversion as necessary.

final BeanWrapper<Person> wrapper = BeanWrapper.getWrapper(new Person("Fred")); <b>(1)</b>

        wrapper.setProperty("age", "20"); <b>(2)</b>
        int newAge = wrapper.getRequiredProperty("age", int.class); <b>(3)</b>

        System.out.println("Person's age now " + newAge);

final BeanWrapper<Person> wrapper = BeanWrapper.getWrapper(new Person("Fred")) <b>(1)</b>

        wrapper.setProperty("age", "20") <b>(2)</b>
        int newAge = wrapper.getRequiredProperty("age", Integer) <b>(3)</b>

        println("Person's age now $newAge")

val wrapper = BeanWrapper.getWrapper(Person("Fred")) <b>(1)</b>

        wrapper.setProperty("age", "20") <b>(2)</b>
        val newAge = wrapper.getRequiredProperty("age", Int::class.java) <b>(3)</b>

        println("Person's age now $newAge")

Jackson and Bean Introspection

You can enable bean introspection integration with Jackson for reflection-free JSON serialization and deserialization using the jackson.bean-introspection-module setting.

jackson:
    bean-introspection-module: true

With the above configuration in place Jackson will be configured to use theBeanIntrospection API to read and write property values and construct objects resulting in reflection-free serialization/deserialization which is benefitial from a performance perspective and requires less configuring to operate correctly with runtimes such as GraalVM native.

implementation("io.micronaut:micronaut-validation")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-validation</artifactId>
</dependency>

implementation("io.micronaut.beanvalidation:micronaut-hibernate-validator")

<dependency>
    <groupId>io.micronaut.beanvalidation</groupId>
    <artifactId>micronaut-hibernate-validator</artifactId>
</dependency>

Validating Bean Methods

You can validate methods of any class declared as a Micronaut bean simply by using the javax.validation annotation as arguments:

import javax.inject.Singleton;
import javax.validation.constraints.NotBlank;

@Singleton
public class PersonService {
    public void sayHello(@NotBlank String name) {
        System.out.println("Hello " + name);
    }
}

import javax.inject.Singleton
import javax.validation.constraints.NotBlank

@Singleton
class PersonService {

    void sayHello(@NotBlank String name) {
        println "Hello $name"
    }
}

import javax.inject.Singleton
import javax.validation.constraints.NotBlank


@Singleton
open class PersonService {
    open fun sayHello(@NotBlank name: String) {
        println("Hello $name")
    }
}

The above example declares that the @NotBlank annotation should be validated when executing the sayHello method.

If a validation error occurs a javax.validation.ConstraintViolationException will be thrown. For example:

import io.micronaut.test.annotation.MicronautTest;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

import javax.inject.Inject;
import javax.validation.ConstraintViolationException;

@MicronautTest
class PersonServiceSpec {

    @Inject PersonService personService;

    @Test
    void testThatNameIsValidated() {
        final ConstraintViolationException exception =
                assertThrows(ConstraintViolationException.class, () ->
                personService.sayHello("") <b>(1)</b>
        );

        assertEquals("sayHello.name: must not be blank", exception.getMessage()); <b>(2)</b>
    }
}

import io.micronaut.test.annotation.MicronautTest
import spock.lang.Specification

import javax.inject.Inject
import javax.validation.ConstraintViolationException

@MicronautTest
class PersonServiceSpec extends Specification {

    @Inject PersonService personService

    void "test person name is validated"() {
        when:"The sayHello method is called with a blank string"
        personService.sayHello("") <b>(1)</b>

        then:"A validation error occurs"
        def e = thrown(ConstraintViolationException)
        e.message == "sayHello.name: must not be blank" //  <b>(2)</b>
    }
}

import io.micronaut.test.annotation.MicronautTest
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.Assertions.*

import javax.inject.Inject
import javax.validation.ConstraintViolationException

@MicronautTest
class PersonServiceSpec {

    @Inject
    lateinit var personService: PersonService

    @Test
    fun testThatNameIsValidated() {
        val exception = assertThrows(ConstraintViolationException::class.java
        ) { personService.sayHello("") } <b>(1)</b>

        assertEquals("sayHello.name: must not be blank", exception.message) <b>(2)</b>
    }
}

Validating Data Classes

If you wish to validate data classes, such as POJOs and so on, typically used in JSON interchange, the class must be annotated with@Introspected (see the previous section on) or, if the class is external, be imported by the @Introspected annotation.

import io.micronaut.core.annotation.Introspected;
import javax.validation.constraints.*;

@Introspected
public class Person {
    private String name;
    @Min(18)
    private int age;

    @NotBlank
    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }

    public void setName(String name) {
        this.name = name;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

import io.micronaut.core.annotation.Introspected

import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank

@Introspected
class Person {
    @NotBlank
    String name
    @Min(18l)
    int age
}

import io.micronaut.core.annotation.Introspected
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank

@Introspected
data class Person(
    @field:NotBlank var name: String,
    @field:Min(18) var age: Int
)

The above example defines a class called Person that has 2 properties ( name and age ) that have constraints applied to them. Note that in Java the annotations can be on the field or the getter and with Kotlin data classes the annotation should target the field.

If you wish to validate the class manually then you can inject an instance ofValidator:

@Inject
Validator validator;

@Test
void testThatPersonIsValidWithValidator() {
    Person person = new Person();
    person.setName("");
    person.setAge(10);

    final Set<ConstraintViolation<Person>> constraintViolations = validator.validate(person);  <b>(1)</b>

    assertEquals(2, constraintViolations.size()); <b>(2)</b>
}

@Inject Validator validator

void "test person is validated with validator"() {
    when:"The person is validated"
    def constraintViolations = validator.validate(new Person(name: "", age: 10)) <b>(1)</b>

    then:"A validation error occurs"
    constraintViolations.size() == 2 //  <b>(2)</b>
}

@Inject
lateinit var validator: Validator

@Test
fun testThatPersonIsValidWithValidator() {
    val person = Person("", 10)
    val constraintViolations = validator.validate(person)  <b>(1)</b>

    assertEquals(2, constraintViolations.size) <b>(2)</b>
}

Alternatively on Bean methods you can use javax.validation.Valid to trigger cascading validation:

@Singleton
public class PersonService {
    public void sayHello(@Valid Person person) {
        System.out.println("Hello " + person.getName());
    }
}

@Singleton
class PersonService {
    void sayHello(@Valid Person person) {
        println "Hello $person.name"
    }
}

@Singleton
open class PersonService {
    open fun sayHello(@Valid person: Person) {
        println("Hello ${person.name}")
    }
}

The PersonService will now validate the Person class when invoked:

@Inject
PersonService personService;

@Test
void testThatPersonIsValid() {
    Person person = new Person();
    person.setName("");
    person.setAge(10);

    final ConstraintViolationException exception =
            assertThrows(ConstraintViolationException.class, () ->
                    personService.sayHello(person) <b>(1)</b>
            );

    assertEquals(2, exception.getConstraintViolations().size()); <b>(2)</b>
}

@Inject PersonService personService

void "test person name is validated"() {
    when:"The sayHello method is called with an invalid person"
    personService.sayHello(new Person(name: "", age: 10)) <b>(1)</b>

    then:"A validation error occurs"
    def e = thrown(ConstraintViolationException)
    e.constraintViolations.size() == 2 //  <b>(2)</b>
}

@Inject
lateinit var personService: PersonService

@Test
fun testThatPersonIsValid() {
    val person = Person("", 10)
    val exception = assertThrows(ConstraintViolationException::class.java  <b>(1)</b>
    ) { personService.sayHello(person) }

    assertEquals(2, exception.constraintViolations.size) <b>(2)</b>
}

Validating Configuration Properties

You can also validate the properties of classes that are annotated with @ConfigurationProperties to ensure configuration is correct.

Defining Additional Constraints

To define additional constraints you can define a new annotation, for example:

import javax.validation.Constraint;
import java.lang.annotation.*;

import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = { }) <b>(1)</b>
public @interface DurationPattern {

    String message() default "invalid duration ({validatedValue})"; <b>(2)</b>

    /**
     * Defines several constraints on the same element.
     */
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Documented
    @interface List {
        DurationPattern[] value(); <b>(3)</b>
    }
}

import javax.validation.Constraint
import java.lang.annotation.*

import static java.lang.annotation.RetentionPolicy.RUNTIME

@Retention(RUNTIME)
@Constraint(validatedBy = []) <b>(1)</b>
@interface DurationPattern {
    String message() default "invalid duration ({validatedValue})" <b>(2)</b>
}

import javax.validation.Constraint

@Retention(AnnotationRetention.RUNTIME)
@Constraint(validatedBy = []) <b>(1)</b>
annotation class DurationPattern(
    val message: String = "invalid duration ({validatedValue})" <b>(2)</b>
)

Once you have defined the annotation you need to implement aConstraintValidator that validates the annotation. You can either implement a bean that implements the interface directly or define a factory that returns one or more validators.

The latter approach is recommended if you plan to define multiple validators:

import io.micronaut.context.annotation.Factory;
import io.micronaut.validation.validator.constraints.ConstraintValidator;
import javax.inject.Singleton;

@Factory
public class MyValidatorFactory {

    @Singleton
    ConstraintValidator<DurationPattern, CharSequence> durationPatternValidator() {
        return (value, annotationMetadata, context) ->
                value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$");
    }
}

import io.micronaut.context.annotation.Factory
import io.micronaut.core.annotation.AnnotationValue
import io.micronaut.validation.validator.constraints.*
import javax.inject.Singleton

@Factory
class MyValidatorFactory {

    @Singleton
    ConstraintValidator<DurationPattern, CharSequence> durationPatternValidator() {
        return { CharSequence value,
                 AnnotationValue<DurationPattern> annotation,
                 ConstraintValidatorContext context ->
            return value == null || value.toString() ==~ /^PT?[\d]+[SMHD]{1}$/
        } as ConstraintValidator<DurationPattern, CharSequence>
    }
}

import io.micronaut.context.annotation.Factory
import io.micronaut.validation.validator.constraints.ConstraintValidator
import javax.inject.Singleton

@Factory
class MyValidatorFactory {

    @Singleton
    fun durationPatternValidator() : ConstraintValidator<DurationPattern, CharSequence> {
        return ConstraintValidator { value, annotation, context ->
            value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$".toRegex())
        }
    }
}

The above example implements a validator that validates any field, parameter etc. that is annotated with DurationPattern , ensuring that the string can be parsed with java.time.Duration.parse .

For example:

@Singleton
public class HolidayService {

    public String startHoliday(@NotBlank String person,
                        @DurationPattern String duration) {
        final Duration d = Duration.parse(duration);
        return "Person " + person + " is off on holiday for " + d.toMinutes() + " minutes";
    }
}

@Singleton
class HolidayService {

    String startHoliday(@NotBlank String person,
                        @DurationPattern String duration) {
        final Duration d = Duration.parse(duration)
        return "Person $person is off on holiday for ${d.toMinutes()} minutes"
    }
}

@Singleton
open class HolidayService {

    open fun startHoliday( @NotBlank person: String,
                           @DurationPattern duration: String): String {
        val d = Duration.parse(duration)
        val mins = d.toMinutes()
        return "Person $person is off on holiday for $mins minutes"
    }
}

To verify the above examples validates the duration parameter you can define a test:

@Inject HolidayService holidayService;

@Test
void testCustomValidator() {
    final ConstraintViolationException exception =
            assertThrows(ConstraintViolationException.class, () ->
                    holidayService.startHoliday("Fred", "junk")   <b>(1)</b>
            );

    assertEquals("startHoliday.duration: invalid duration (junk)", exception.getMessage()); <b>(2)</b>
}

void "test test custom validator"() {
    when:"A custom validator is used"
    holidayService.startHoliday("Fred", "junk") <b>(1)</b>

    then:"A validation error occurs"
    def e = thrown(ConstraintViolationException)
    e.message == "startHoliday.duration: invalid duration (junk)" //  <b>(2)</b>
}

@Inject
lateinit var holidayService: HolidayService

@Test
fun testCustomValidator() {
    val exception = assertThrows(ConstraintViolationException::class.java
    ) { holidayService.startHoliday("Fred", "junk") }   <b>(1)</b>

    assertEquals("startHoliday.duration: invalid duration (junk)", exception.message) <b>(2)</b>
}

Validating Annotations at Compilation Time

You can use Micronaut’s validator to validate annotation usages at compilation time. To do so you should include micronaut-validation in the annotation processor classpath:

annotationProcessor("io.micronaut:micronaut-validation")

<annotationProcessorPaths>
    <path>
        <groupId>io.micronaut</groupId>
        <artifactId>micronaut-validation</artifactId>
    </path>
</annotationProcessorPaths>

Once this is done Micronaut will at compilation validate annotation values that are themselves annotated with javax.validation . For example consider the following annotation:

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
public @interface TimeOff {
    @DurationPattern
    String duration();
}

import java.lang.annotation.*

@Retention(RetentionPolicy.RUNTIME)
@interface TimeOff {
    @DurationPattern
    String duration()
}

@Retention(AnnotationRetention.RUNTIME)
annotation class TimeOff(
    @DurationPattern val duration: String
)

If your attempt to use @TimeOff(duration="junk") in your source Micronaut will fail compilation due to the value of duration violating the DurationPattern constraint.

Note that if you wish to allow use of a custom ConstraintValidator at compilation time you should instead define the validator as a class:

import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import io.micronaut.core.annotation.AnnotationValue;
import io.micronaut.validation.validator.constraints.*;

public class DurationPatternValidator implements ConstraintValidator<DurationPattern, CharSequence> {
    @Override
    public boolean isValid(
            @Nullable CharSequence value,
            @NonNull AnnotationValue<DurationPattern> annotationMetadata,
            @NonNull ConstraintValidatorContext context) {
        return value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$");
    }
}

import edu.umd.cs.findbugs.annotations.NonNull
import edu.umd.cs.findbugs.annotations.Nullable
import io.micronaut.core.annotation.AnnotationValue
import io.micronaut.validation.validator.constraints.*

class DurationPatternValidator implements ConstraintValidator<DurationPattern, CharSequence> {
    @Override
    boolean isValid(
            @Nullable CharSequence value,
            @NonNull AnnotationValue<DurationPattern> annotationMetadata,
            @NonNull ConstraintValidatorContext context) {
        return value == null || value.toString() ==~ /^PT?[\d]+[SMHD]{1}$/
    }
}

import io.micronaut.core.annotation.AnnotationValue
import io.micronaut.validation.validator.constraints.*

class DurationPatternValidator : ConstraintValidator<DurationPattern, CharSequence> {
    override fun isValid(
            value: CharSequence?,
            annotationMetadata: AnnotationValue<DurationPattern>,
            context: ConstraintValidatorContext): Boolean {
        return value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$".toRegex())
    }
}

In addition to the following requirements:

• Define a META-INF/services/io.micronaut.validation.validator.constraints.ConstraintValidator file that references the class.

• The class should be public and feature a zero argument public constructor

• The class should be placed on the annotation processor classpath of the project that is to be validated.

Lookup Bean Definitions by Stereotype

BeanContext beanContext = ... // obtain the bean context
Collection<BeanDefinition> definitions =
    beanContext.getBeanDefinitions(Qualifiers.byStereotype(Controller.class))

for(BeanDefinition definition : definitions) {
    AnnotationValue<Controller> controllerAnn = definition.getAnnotation(Controller.class);
    // do something with the annotation
}

Synthesizing Annotation Instances

Controller controllerAnn = definition.synthesize(Controller.class);

Aliasing / Mapping Annotations

There are times when you may want to alias the value of an annotation member to the value of another annotation member. To do this you can use the@AliasFor annotation to alias the value of one member to the value of another.

A common use case is for example when an annotation defines the value() member, but also supports other members. For example the@Client annotation:

public @interface Client {

    /**
     * @return The URL or service ID of the remote service
     */
    @AliasFor(member = "id") <i data-value="1"></i><b>(1)</b>
    String value() default "";

    /**
     * @return The ID of the client
     */
    @AliasFor(member = "value") <i data-value="2"></i><b>(2)</b>
    String id() default "";
}

With these aliases in place, regardless whether you define @Client("foo") or @Client(id="foo") both the value and id members are always set, making it much easier to parse and deal with the annotation.

If you do not have control over the annotation then another approach is to use anAnnotationMapper. To create an AnnotationMapper you must perform the following steps:

• Implement theAnnotationMapper interface

• Define a META-INF/services/io.micronaut.inject.annotation.AnnotationMapper file referencing the implementation class

• Add the JAR file containing the implementation to the annotationProcessor classpath ( kapt for Kotlin)

The following is an example the AnnotationMapper that improves the introspection capabilities of JPA entities

public class EntityIntrospectedAnnotationMapper implements NamedAnnotationMapper {
    @NonNull
    @Override
    public String getName() {
        return "javax.persistence.Entity";
    }

    @Override
    public List<AnnotationValue<?>> map(AnnotationValue<Annotation> annotation, VisitorContext visitorContext) { <i data-value="1"></i><b>(1)</b>
        final AnnotationValueBuilder<Introspected> builder = AnnotationValue.builder(Introspected.class)
                // don't bother with transients properties
                .member("excludedAnnotations", "javax.persistence.Transient"); <i data-value="2"></i><b>(2)</b>
        return Collections.singletonList(
                builder.build()
        );
    }
}

Configuring Your Android Build

dependencies {
    ...
    annotationProcessor "io.micronaut:micronaut-inject-java:2.0.0"
    compileOnly "io.micronaut:micronaut-inject-java:2.0.0"
    ...
}

android {
    ...
    lintOptions {
        lintOptions { warning 'InvalidPackage' }
    }
}

Enabling Dependency Injection

import android.app.Activity;
import android.app.Application;
import android.os.Bundle;

import io.micronaut.context.ApplicationContext;
import io.micronaut.context.env.Environment;

public class BaseApplication extends Application { <i data-value="1"></i><b>(1)</b>

    private ApplicationContext ctx;

    public BaseApplication() {
        super();
    }

    @Override
    public void onCreate() {
        super.onCreate();
        ctx = ApplicationContext.run(MainActivity.class, Environment.ANDROID); <i data-value="2"></i><b>(2)</b>
        registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacks() { <i data-value="3"></i><b>(3)</b>
            @Override
            public void onActivityCreated(Activity activity, Bundle bundle) {
                ctx.inject(activity);
            }
            ... // shortened for brevity, it is not necessary to implement other methods
        });
    }
}

Initializing the Environment

ApplicationContext applicationContext = ApplicationContext.run("test", "android");
        Environment environment = applicationContext.getEnvironment();

        assertTrue(environment.getActiveNames().contains("test"));
        assertTrue(environment.getActiveNames().contains("android"));

Initializing the Environment

when:
        ApplicationContext applicationContext = ApplicationContext.run("test", "android")
        Environment environment = applicationContext.getEnvironment()

        then:
        environment.getActiveNames().contains("test")
        environment.getActiveNames().contains("android")

Initializing the Environment

val applicationContext = ApplicationContext.run("test", "android")
        val environment = applicationContext.getEnvironment()

        assertTrue(environment.getActiveNames().contains("test"))
        assertTrue(environment.getActiveNames().contains("android"))

Specifying environments

$ java -Dmicronaut.environments=foo,bar -jar myapp.jar

Environment Priority

Disabling Environment Detection

$  java -Dmicronaut.env.deduction=false -jar myapp.jar

@Test
    public void testDisableEnvironmentDeductionViaBuilder() {
        ApplicationContext ctx = ApplicationContext.builder().deduceEnvironment(false).start();
        assertFalse(ctx.getEnvironment().getActiveNames().contains(Environment.TEST));
        ctx.close();
    }

void "test disable environment deduction via builder"() {
        when:
        ApplicationContext ctx = ApplicationContext.builder().deduceEnvironment(false).start()

        then:
        !ctx.environment.activeNames.contains(Environment.TEST)

        cleanup:
        ctx.close()
    }

"test disable environment deduction via builder"() {
        val ctx = ApplicationContext.builder().deduceEnvironment(false).start()
        assertFalse(ctx.environment.activeNames.contains(Environment.TEST))
        ctx.close()
    }

Initializing the Environment

ApplicationContext applicationContext = ApplicationContext.run(
                PropertySource.of(
                        "test",
                        CollectionUtils.mapOf(
                            "micronaut.server.host", "foo",
                            "micronaut.server.port", 8080
                        )
                ),
                "test", "android");
        Environment environment = applicationContext.getEnvironment();

        assertEquals(
                "foo",
                environment.getProperty("micronaut.server.host", String.class).orElse("localhost")
        );

Initializing the Environment

when:
        ApplicationContext applicationContext = ApplicationContext.run(
                PropertySource.of(
                        "test",
                        [
                            "micronaut.server.host": "foo",
                            "micronaut.server.port": 8080
                        ]
                ),
                "test", "android")
        Environment environment = applicationContext.getEnvironment()

        then:
        "foo" == environment.getProperty("micronaut.server.host", String.class).orElse("localhost")

Initializing the Environment

val applicationContext = ApplicationContext.run(
                PropertySource.of(
                        "test",
                        mapOf(
                                "micronaut.server.host" to "foo",
                                "micronaut.server.port" to 8080
                        )
                ),
                "test", "android")
        val environment = applicationContext.getEnvironment()

        assertEquals(
                "foo",
                environment.getProperty("micronaut.server.host", String::class.java).orElse("localhost")
        )

Included PropertySource Loaders

Micronaut by default contains PropertySourceLoader implementations that load properties from the given locations and priority:

1. Command line arguments

2. Properties from SPRING_APPLICATION_JSON (for Spring compatibility)

3. Properties from MICRONAUT_APPLICATION_JSON

4. Java System Properties

5. OS environment variables

6. Configuration files loaded in order from the system property 'micronaut.config.files' or the environment variable MICRONAUT_CONFIG_FILES . The value can be a comma separated list of paths with the last file having precedence. The files can be referenced from the file system as a path or the classpath with a classpath: prefix.

7. Enviroment-specific properties from application-{environment}.{extension}

8. Application-specific properties from application.{extension}

Property Value Placeholders

Micronaut includes a property placeholder syntax which can be used to reference configuration properties both within configuration values and with any Micronaut annotation (see@Value and the section onConfiguration Injection).

The basic syntax is to wrap a reference to a property in ${…​} . For example in application.yml :

myapp:
    endpoint: http://${micronaut.server.host}:${micronaut.server.port}/foo

The above example embeds references to the micronaut.server.host and micronaut.server.port properties.

You can specify default values by defining a value after the : character. For example:

myapp:
    endpoint: http://${micronaut.server.host:localhost}:${micronaut.server.port:8080}/foo

The above example will default to localhost and port 8080 if no value is found (rather than throwing an exception). Note that if default value itself contains a : character, you should escape it using back ticks:

myapp:
    endpoint: ${server.address:`http://localhost:8080`}/foo

The above example tries to read a server.address property otherwise fallbacks back to http://localhost:8080 , since the address has a : character we have to escape it with back ticks.

Property Value Binding

Note that these property references should always be in kebab case (lowercase and hyphen-separated) when placing references in code or in placeholder values. For example, you should use micronaut.server.default-charset and not micronaut.server.defaultCharset .

Micronaut still allows specifying the latter in configuration, but normalizes the properties into kebab case form to optimize memory consumption and reduce complexity when resolving properties. The following table summarizes how properties are normalized from different sources:

Environment variables are given special treatment to allow the definition of environment variables to be more flexible. Note that there is no way to reference an environment variable with camel-case.

To control how environment properties participate in configuration, call the respective methods on the Micronaut builder.

import io.micronaut.runtime.Micronaut;

public class Application {

    public static void main(String[] args) {
        Micronaut.build(null)
                .mainClass(Application.class)
                .environmentPropertySource(false)
                //or
                .environmentVariableIncludes("THIS_ENV_ONLY")
                //or
                .environmentVariableExcludes("EXCLUDED_ENV")
                .start();
    }
}

import io.micronaut.runtime.Micronaut

class Application {

    static void main(String[] args) {
        Micronaut.build()
                .mainClass(Application)
                .environmentPropertySource(false)
                //or
                .environmentVariableIncludes("THIS_ENV_ONLY")
                //or
                .environmentVariableExcludes("EXCLUDED_ENV")
                .start()
    }
}

import io.micronaut.runtime.Micronaut

object Application {

    @JvmStatic
    fun main(args: Array<String>) {
        Micronaut.build(null)
                .mainClass(Application::class.java)
                .environmentPropertySource(false)
                //or
                .environmentVariableIncludes("THIS_ENV_ONLY")
                //or
                .environmentVariableExcludes("EXCLUDED_ENV")
                .start()
    }
}

Using Random Properties

You can use random values by using the following properties. These can be used in configuration files as variables like the following.

micronaut:
  application:
    name: myapplication
    instance:
      id: ${random.shortuuid}

Fail Fast Property Injection

For beans that inject required properties, the injection and potential failure will not occur until the bean is requested. To verify at startup that the properties exist and can be injected, the bean can be annotated with@Context. Context scoped beans will be injected at startup time and thus will fail at startup time if any required properties are missing or could not be converted to the required type.

Controlling Log Levels with Properties

Log levels can be configured via properties defined in application.yml (and environment variables) with the log.level prefix:

logger:
    levels:
        foo.bar: ERROR

Note that the ability to control log levels via config is controlled via theLoggingSystem interface. Currently Micronaut ships with a single implementation that allows setting log levels for the Logback library. If another library is chosen you should provide a bean that implements this interface.

Using the @Value Annotation

Consider the following example:

import javax.inject.Singleton;

@Singleton
public class EngineImpl implements Engine {

    @Value("${my.engine.cylinders:6}") <b>(1)</b>
    protected int cylinders;

    @Override
    public int getCylinders() {
        return this.cylinders;
    }

    public String start() {<b>(2)</b>
        return "Starting V" + getCylinders() + " Engine";
    }

}

import javax.inject.Singleton

@Singleton
class EngineImpl implements Engine {

    @Value('${my.engine.cylinders:6}') <b>(1)</b>
    protected int cylinders

    @Override
    int getCylinders() {
        this.cylinders
    }

    String start() { <b>(2)</b>
        "Starting V${cylinders} Engine"
    }
}

import javax.inject.Singleton

@Singleton
class EngineImpl : Engine {

    @Value("\${my.engine.cylinders:6}") <b>(1)</b>
    override var cylinders: Int = 0
        protected set

    override fun start(): String {<b>(2)</b>
        return "Starting V$cylinders Engine"
    }
}

Note that @Value can also be used to inject a static value, for example the following will inject the number 10:

@Value("10")
int number;

However it is definitely more useful when used to compose injected values combining static content and placeholders. For example to setup a URL:

@Value("http://${my.host}:${my.port}")
URL url;

In the above example the URL is constructed from 2 placeholder properties that must be present in configuration: my.host and my.port .

Remember that to specify a default value in a placeholder expression, you should use the colon : character, however if the default you are trying to specify has a colon then you should escape the value with back ticks. For example:

@Value("${my.url:`http://foo.com`}")
URL url;

Note that there is nothing special about @Value itself regarding the resolution of property value placeholders.

Due to Micronaut’s extensive support for annotation metadata you can in fact use property placeholder expressions on any annotation. For example, to make the path of a @Controller configurable you can do:

@Controller("${hello.controller.path:/hello}")
class HelloController {
    ...
}

In the above case if hello.controller.path is specified in configuration then the controller will be mapped to the path specified otherwise it will be mapped to /hello .

You can also make the target server for@Client configurable (although service discovery approaches are often better), for example:

@Client("${my.server.url:`http://localhost:8080`}")
interface HelloClient {
    ...
}

In the above example the property my.server.url can be used to configure the client otherwise the client will fallback to a localhost address.

Using the @Property Annotation

Recall that the@Value annotation receives a String value which is a mix of static content and placeholder expressions. This can lead to confusion if you attempt to do the following:

@Value("my.url")
String url;

In the above case the value my.url will be injected and set to the url field and not the value of the my.url property from your application configuration, this is because @Value only resolves placeholders within the value specified to it.

If you wish to inject a specific property name then you may be better off using@Property:

import io.micronaut.context.annotation.Property;

import javax.inject.Inject;
import javax.inject.Singleton;

@Singleton
public class Engine {

    @Property(name = "my.engine.cylinders") <b>(1)</b>
    protected int cylinders; <b>(2)</b>

    private String manufacturer;

    public int getCylinders() {
        return cylinders;
    }

    public String getManufacturer() {
        return manufacturer;
    }

    @Inject
    public void setManufacturer(@Property(name = "my.engine.manufacturer") String manufacturer) { <b>(3)</b>
        this.manufacturer = manufacturer;
    }

}

import io.micronaut.context.annotation.Property

import javax.inject.Singleton

@Singleton
class Engine {

    @Property(name = "my.engine.cylinders") <b>(1)</b>
    protected int cylinders <b>(2)</b>

    @Property(name = "my.engine.manufacturer") <b>(3)</b>
    String manufacturer

    int getCylinders() {
        cylinders
    }
}

import io.micronaut.context.annotation.Property

import javax.inject.Inject
import javax.inject.Singleton


@Singleton
class Engine {

    @field:Property(name = "my.engine.cylinders") <b>(1)</b>
    protected var cylinders: Int = 0 <b>(2)</b>

    @set:Inject
    @setparam:Property(name = "my.engine.manufacturer") <b>(3)</b>
    var manufacturer: String? = null

    fun cylinders(): Int {
        return cylinders
    }
}

The above will instead inject the value of the my.url property resolved from application configuration. If the property can not be found in configuration, an exception will be thrown. As with other types of injection, the injection point can also be annotated with @Nullable to make the injection optional.

You can also use this feature to resolve sub maps. For example, consider the following configuration:

datasources:
    default:
        name: 'mydb'
jpa:
    default:
        properties:
            hibernate:
                hbm2ddl:
                    auto: update
                show_sql: true

If you wish to resolve a flattened map containing only the properties starting with hibernate then you can do so with @Property , for example:

@Property(name = "jpa.default.properties")
Map<String, String> jpaProperties;

The injected map will contain the keys hibernate.hbm2ddl.auto and hibernate.show_sql and their values.

@ConfigurationProperties Example

import io.micronaut.context.annotation.ConfigurationProperties;

import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;

@ConfigurationProperties("my.engine") <b>(1)</b>
public class EngineConfig {
    public String getManufacturer() {
        return manufacturer;
    }

    public void setManufacturer(String manufacturer) {
        this.manufacturer = manufacturer;
    }

    public int getCylinders() {
        return cylinders;
    }

    public void setCylinders(int cylinders) {
        this.cylinders = cylinders;
    }

    public CrankShaft getCrankShaft() {
        return crankShaft;
    }

    public void setCrankShaft(CrankShaft crankShaft) {
        this.crankShaft = crankShaft;
    }

    @NotBlank <b>(2)</b>
    private String manufacturer = "Ford"; <b>(3)</b>
    @Min(1L)
    private int cylinders;
    private CrankShaft crankShaft = new CrankShaft();

    @ConfigurationProperties("crank-shaft")
    public static class CrankShaft { <b>(4)</b>
        public Optional<Double> getRodLength() {
            return rodLength;
        }

        public void setRodLength(Optional<Double> rodLength) {
            this.rodLength = rodLength;
        }

        private Optional<Double> rodLength = Optional.empty(); <b>(5)</b>
    }
}

@ConfigurationProperties Example

import io.micronaut.context.annotation.ConfigurationProperties

import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank

@ConfigurationProperties('my.engine') <b>(1)</b>
class EngineConfig {

    @NotBlank <b>(2)</b>
    String manufacturer = "Ford" <b>(3)</b>

    @Min(1L)
    int cylinders
    CrankShaft crankShaft = new CrankShaft()

    @ConfigurationProperties('crank-shaft')
    static class CrankShaft { <b>(4)</b>
        Optional<Double> rodLength = Optional.empty() <b>(5)</b>
    }

}

@ConfigurationProperties Example

import io.micronaut.context.annotation.ConfigurationProperties
import java.util.*

import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank

@ConfigurationProperties("my.engine") <b>(1)</b>
class EngineConfig {

    @NotBlank <b>(2)</b>
    var manufacturer = "Ford" <b>(3)</b>
    @Min(1L)
    var cylinders: Int = 0
    var crankShaft = CrankShaft()

    @ConfigurationProperties("crank-shaft")
    class CrankShaft { <b>(4)</b>
        var rodLength: Optional<Double> = Optional.empty() <b>(5)</b>
    }
}

@ConfigurationProperties Dependency Injection

@Singleton
public class EngineImpl implements Engine {
    private final EngineConfig config;

    public EngineImpl(EngineConfig config) {<b>(1)</b>
        this.config = config;
    }

    @Override
    public int getCylinders() {
        return config.getCylinders();
    }

    public String start() {<b>(2)</b>
        return getConfig().getManufacturer() + " Engine Starting V" + getConfig().getCylinders() +
                " [rodLength=" + getConfig().getCrankShaft().getRodLength().orElse(6.0d) + "]";
    }

    public final EngineConfig getConfig() {
        return config;
    }
}

@ConfigurationProperties Dependency Injection

@Singleton
class EngineImpl implements Engine {
    final EngineConfig config

    EngineImpl(EngineConfig config) { <b>(1)</b>
        this.config = config
    }

    @Override
    int getCylinders() {
        config.cylinders
    }

    String start() { <b>(2)</b>
        "${config.manufacturer} Engine Starting V${config.cylinders} [rodLength=${config.crankShaft.rodLength.orElse(6.0d)}]"
    }
}

@ConfigurationProperties Dependency Injection

@Singleton
class EngineImpl(val config: EngineConfig) : Engine {<b>(1)</b>

    override val cylinders: Int
        get() = config.cylinders

    override fun start(): String {<b>(2)</b>
        return "${config.manufacturer} Engine Starting V${config.cylinders} [rodLength=${config.crankShaft.rodLength.orElse(6.0)}]"
    }
}

Supply Configuration

LinkedHashMap<String, Object> map = new LinkedHashMap(1);
        map.put("my.engine.cylinders", "8");
        ApplicationContext applicationContext = ApplicationContext.run(map, "test");

        Vehicle vehicle = applicationContext.getBean(Vehicle.class);
        System.out.println(vehicle.start());

Supply Configuration

ApplicationContext applicationContext = ApplicationContext.run(
                ['my.engine.cylinders': '8'],
                "test"
        )

        Vehicle vehicle = applicationContext
                .getBean(Vehicle)
        println(vehicle.start())

Supply Configuration

val map = mapOf( "my.engine.cylinders" to "8")
        val applicationContext = ApplicationContext.run(map, "test")

        val vehicle = applicationContext.getBean(Vehicle::class.java)
        println(vehicle.start())

Includes / Excludes

For the cases where the configuration properties class is inheriting properties from a parent class, it may be desirable to exclude properties from the parent class. The includes and excludes members of the @ConfigurationProperties annotation allow for that functionality. The list applies to both local properties and inherited properties.

The names supplied to the includes/excludes list should be the "property" name. For example if a setter method is injected, the property name is the de-capitalized setter name ( setConnectionTimeout → connectionTimeout ).

Property Type Conversion

micronaut:
    http:
        client:
            read-timeout: 15s

my:
    app:
        integers:
            - 1
            - 2
        urls:
            - http://foo.com
            - http://bar.com

my.app.integers=1,2
my.app.urls=http://foo.com,http://bar.com

my.app.integers[0]=1
my.app.integers[1]=2

List<Integer> integers;
List<URL> urls;

public void setMaxContentLength(@ReadableBytes int maxContentLength) {
    this.maxContentLength = maxContentLength;
}

public void setMyDate(@Format("yyyy-MM-dd") LocalDate date) {
    this.myDate = date;
}

Configuration Builder

import io.micronaut.context.annotation.ConfigurationBuilder;
import io.micronaut.context.annotation.ConfigurationProperties;

@ConfigurationProperties("my.engine") <b>(1)</b>
class EngineConfig {

    @ConfigurationBuilder(prefixes = "with") <b>(2)</b>
    EngineImpl.Builder builder = EngineImpl.builder();

    @ConfigurationBuilder(prefixes = "with", configurationPrefix = "crank-shaft") <b>(3)</b>
    CrankShaft.Builder crankShaft = CrankShaft.builder();

    private SparkPlug.Builder sparkPlug = SparkPlug.builder();

    SparkPlug.Builder getSparkPlug() { return this.sparkPlug; }

    @ConfigurationBuilder(prefixes = "with", configurationPrefix = "spark-plug") <b>(4)</b>
    void setSparkPlug(SparkPlug.Builder sparkPlug) {
        this.sparkPlug = sparkPlug;
    }
}

import io.micronaut.context.annotation.ConfigurationBuilder
import io.micronaut.context.annotation.ConfigurationProperties

@ConfigurationProperties('my.engine') <b>(1)</b>
class EngineConfig {

    @ConfigurationBuilder(prefixes = "with") <b>(2)</b>
    EngineImpl.Builder builder = EngineImpl.builder()

    @ConfigurationBuilder(prefixes = "with", configurationPrefix = "crank-shaft") <b>(3)</b>
    CrankShaft.Builder crankShaft = CrankShaft.builder()

    SparkPlug.Builder sparkPlug = SparkPlug.builder()

    @ConfigurationBuilder(prefixes = "with", configurationPrefix = "spark-plug") <b>(4)</b>
    void setSparkPlug(SparkPlug.Builder sparkPlug) {
        this.sparkPlug = sparkPlug
    }
}

import io.micronaut.context.annotation.ConfigurationBuilder
import io.micronaut.context.annotation.ConfigurationProperties

@ConfigurationProperties("my.engine") <b>(1)</b>
internal class EngineConfig {
    @ConfigurationBuilder(prefixes = ["with"])  <b>(2)</b>
    val builder = EngineImpl.builder()

    @ConfigurationBuilder(prefixes = ["with"], configurationPrefix = "crank-shaft") <b>(3)</b>
    val crankShaft = CrankShaft.builder()

    @set:ConfigurationBuilder(prefixes = ["with"], configurationPrefix = "spark-plug") <b>(4)</b>
    var sparkPlug = SparkPlug.builder()
}

import io.micronaut.context.annotation.Factory;

import javax.inject.Singleton;

@Factory
class EngineFactory {

    @Singleton
    EngineImpl buildEngine(EngineConfig engineConfig) {
        return engineConfig.builder.build(engineConfig.crankShaft, engineConfig.getSparkPlug());
    }
}

import io.micronaut.context.annotation.Factory

import javax.inject.Singleton

@Factory
class EngineFactory {

    @Singleton
    EngineImpl buildEngine(EngineConfig engineConfig) {
        engineConfig.builder.build(engineConfig.crankShaft, engineConfig.sparkPlug)
    }
}

import io.micronaut.context.annotation.Factory
import javax.inject.Singleton

@Factory
internal class EngineFactory {

    @Singleton
    fun buildEngine(engineConfig: EngineConfig): EngineImpl {
        return engineConfig.builder.build(engineConfig.crankShaft, engineConfig.sparkPlug)
    }
}

HashMap<String, Object> properties = new HashMap<>();
        properties.put("my.engine.cylinders"             ,"4");
        properties.put("my.engine.manufacturer"          , "Subaru");
        properties.put("my.engine.crank-shaft.rod-length", 4);
        properties.put("my.engine.spark-plug.name"       , "6619 LFR6AIX");
        properties.put("my.engine.spark-plug.type"       , "Iridium");
        properties.put("my.engine.spark-plug.companyName", "NGK");
        ApplicationContext applicationContext = ApplicationContext.run(properties, "test");

        Vehicle vehicle = applicationContext.getBean(Vehicle.class);
        System.out.println(vehicle.start());

ApplicationContext applicationContext = ApplicationContext.run(
                ['my.engine.cylinders'             : '4',
                 'my.engine.manufacturer'          : 'Subaru',
                 'my.engine.crank-shaft.rod-length': 4,
                 'my.engine.spark-plug.name'       : '6619 LFR6AIX',
                 'my.engine.spark-plug.type'       : 'Iridium',
                 'my.engine.spark-plug.companyName': 'NGK'
                ],
                "test"
        )

        Vehicle vehicle = applicationContext
                .getBean(Vehicle)
        println(vehicle.start())

val applicationContext = ApplicationContext.run(
                mapOf(
                        "my.engine.cylinders" to "4",
                        "my.engine.manufacturer" to "Subaru",
                        "my.engine.crank-shaft.rod-length" to 4,
                        "my.engine.spark-plug.name" to "6619 LFR6AIX",
                        "my.engine.spark-plug.type" to "Iridium",
                        "my.engine.spark-plug.company" to "NGK"
                ),
                "test"
        )

        val vehicle = applicationContext.getBean(Vehicle::class.java)
        println(vehicle.start())

MapFormat

import io.micronaut.context.annotation.ConfigurationProperties;
import javax.validation.constraints.Min;
import java.util.Map;
import io.micronaut.core.convert.format.MapFormat;

@ConfigurationProperties("my.engine")
public class EngineConfig {
    public int getCylinders() {
        return cylinders;
    }

    public void setCylinders(int cylinders) {
        this.cylinders = cylinders;
    }

    public Map<Integer, String> getSensors() {
        return sensors;
    }

    public void setSensors(Map<Integer, String> sensors) {
        this.sensors = sensors;
    }

    @Min(1L)
    private int cylinders;
    @MapFormat(transformation = MapFormat.MapTransformation.FLAT) <b>(1)</b>
    private Map<Integer, String> sensors;
}

import io.micronaut.context.annotation.ConfigurationProperties
import javax.validation.constraints.Min
import io.micronaut.core.convert.format.MapFormat

@ConfigurationProperties('my.engine')
class EngineConfig {

    @Min(1L)
    int cylinders

    @MapFormat(transformation = MapFormat.MapTransformation.FLAT) <b>(1)</b>
    Map<Integer, String> sensors

}

import io.micronaut.context.annotation.ConfigurationProperties
import javax.validation.constraints.Min
import io.micronaut.core.convert.format.MapFormat

@ConfigurationProperties("my.engine")
class EngineConfig {

    @Min(1L)
    var cylinders: Int = 0
    @MapFormat(transformation = MapFormat.MapTransformation.FLAT) <b>(1)</b>
    var sensors: Map<Int, String>? = null
}

@Singleton
public class EngineImpl implements Engine {
    @Override
    public Map getSensors() {
        return config.getSensors();
    }

    public String start() {
        return "Engine Starting V" + getConfig().getCylinders() + " [sensors=" + getSensors().size() + "]";
    }

    public EngineConfig getConfig() {
        return config;
    }

    public void setConfig(EngineConfig config) {
        this.config = config;
    }

    @Inject
    private EngineConfig config;
}

@Singleton
class EngineImpl implements Engine {

    @Inject EngineConfig config

    @Override
    Map getSensors() {
        config.sensors
    }

    String start() {
        "Engine Starting V${config.cylinders} [sensors=${sensors.size()}]"
    }
}

@Singleton
class EngineImpl : Engine {
    override val sensors: Map<*, *>?
        get() = config!!.sensors

    @Inject
    var config: EngineConfig? = null

    override fun start(): String {
        return "Engine Starting V${config!!.cylinders} [sensors=${sensors!!.size}]"
    }
}

LinkedHashMap<String, Object> map = new LinkedHashMap(2);
        map.put("my.engine.cylinders", "8");
        LinkedHashMap<Integer, String> map1 = new LinkedHashMap(2);
        map1.put(0, "thermostat");
        map1.put(1, "fuel pressure");
        map.put("my.engine.sensors", map1);
        ApplicationContext applicationContext = ApplicationContext.run(map, "test");

        Vehicle vehicle = applicationContext.getBean(Vehicle.class);
        DefaultGroovyMethods.println(this, vehicle.start());

ApplicationContext applicationContext = ApplicationContext.run(
                ['my.engine.cylinders': '8', 'my.engine.sensors': [0: 'thermostat', 1: 'fuel pressure']],
                "test"
        )

        Vehicle vehicle = applicationContext
                .getBean(Vehicle)
        println(vehicle.start())

val subMap = mapOf(
                0 to "thermostat",
                1 to "fuel pressure"
        )
        val map = mapOf(
                "my.engine.cylinders" to "8",
                "my.engine.sensors" to subMap
        )
        val applicationContext = ApplicationContext.run(map, "test")

        val vehicle = applicationContext.getBean(Vehicle::class.java)
        DefaultGroovyMethods.println(this, vehicle.start())

Using @EachProperty

import io.micronaut.context.annotation.Parameter;
import io.micronaut.context.annotation.EachProperty;

@EachProperty("test.datasource")  <b>(1)</b>
public class DataSourceConfiguration {

    private final String name;
    private URI url = new URI("localhost");

    public DataSourceConfiguration(@Parameter String name) <b>(2)</b>
            throws URISyntaxException {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public URI getUrl() { <b>(3)</b>
        return url;
    }

    public void setUrl(URI url) {
        this.url = url;
    }
}

Using @EachProperty

@EachProperty("test.datasource")
<b>(1)</b>
class DataSourceConfiguration {

    final String name
    URI url = new URI("localhost")

    DataSourceConfiguration(@Parameter String name) <b>(2)</b>
            throws URISyntaxException {
        this.name = name
    }
}

Using @EachProperty

@EachProperty("test.datasource")  <b>(1)</b>
class DataSourceConfiguration <b>(2)</b>
@Throws(URISyntaxException::class)
constructor(@param:Parameter val name: String) {
    <b>(3)</b>
    var url = URI("localhost")
}

Providing Configuration to @EachProperty

ApplicationContext applicationContext = ApplicationContext.run(PropertySource.of(
                "test",
                CollectionUtils.mapOf(
                        "test.datasource.one.url", "jdbc:mysql://localhost/one",
                        "test.datasource.two.url", "jdbc:mysql://localhost/two")

        ));

Providing Configuration to @EachProperty

ApplicationContext applicationContext = ApplicationContext.run(PropertySource.of(
            "test",
            [
                    "test.datasource.one.url": "jdbc:mysql://localhost/one",
                    "test.datasource.two.url": "jdbc:mysql://localhost/two"
            ]
    ))

Providing Configuration to @EachProperty

val applicationContext = ApplicationContext.run(PropertySource.of(
                "test",
                mapOf(
                        "test.datasource.one.url" to "jdbc:mysql://localhost/one",
                        "test.datasource.two.url" to "jdbc:mysql://localhost/two"
                )
        ))

Evaluating Beans Built by @EachProperty

Collection<DataSourceConfiguration> beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration.class);
        assertEquals(2, beansOfType.size()); <b>(1)</b>

        DataSourceConfiguration firstConfig = applicationContext.getBean(
                DataSourceConfiguration.class,
                Qualifiers.byName("one") <b>(2)</b>
        );

        assertEquals(
                new URI("jdbc:mysql://localhost/one"),
                firstConfig.getUrl()
        );

Evaluating Beans Built by @EachProperty

when:
        Collection<DataSourceConfiguration> beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration.class)
        assertEquals(2, beansOfType.size()) <b>(1)</b>

        DataSourceConfiguration firstConfig = applicationContext.getBean(
                DataSourceConfiguration.class,
                Qualifiers.byName("one") <b>(2)</b>
        )

        then:
        new URI("jdbc:mysql://localhost/one") == firstConfig.getUrl()

Evaluating Beans Built by @EachProperty

val beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration::class.java)
        assertEquals(2, beansOfType.size.toLong()) <b>(1)</b>

        val firstConfig = applicationContext.getBean(
                DataSourceConfiguration::class.java,
                Qualifiers.byName("one") <b>(2)</b>
        )

        assertEquals(
                URI("jdbc:mysql://localhost/one"),
                firstConfig.url
        )

List Based Binding

The default behavior of@EachProperty is to bind from a map style of configuration where the key is the named qualifier of the bean and the value is the data to bind from. For cases where map style configuration doesn’t make sense, it is possible to inform Micronaut the class should be bound from a list. Simply set the list member on the annotation to true.

/*
 * Copyright 2017-2020 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.micronaut.docs.config.env;

import io.micronaut.context.annotation.EachProperty;
import io.micronaut.context.annotation.Parameter;
import io.micronaut.core.order.Ordered;

import java.time.Duration;

@EachProperty(value = "ratelimits", list = true) <b>(1)</b>
public class RateLimitsConfiguration implements Ordered { <b>(2)</b>

    private final Integer index;
    private Duration period;
    private Integer limit;

    RateLimitsConfiguration(@Parameter Integer index) { <b>(3)</b>
        this.index = index;
    }

    @Override
    public int getOrder() {
        return index;
    }

    public Duration getPeriod() {
        return period;
    }

    public void setPeriod(Duration period) {
        this.period = period;
    }

    public Integer getLimit() {
        return limit;
    }

    public void setLimit(Integer limit) {
        this.limit = limit;
    }

}

/*
 * Copyright 2017-2020 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.micronaut.docs.config.env

import io.micronaut.context.annotation.EachProperty
import io.micronaut.context.annotation.Parameter
import io.micronaut.core.order.Ordered

import java.time.Duration

@EachProperty(value = "ratelimits", list = true) <b>(1)</b>
class RateLimitsConfiguration implements Ordered { <b>(2)</b>

    private final Integer index
    Duration period
    Integer limit

    RateLimitsConfiguration(@Parameter Integer index) { <b>(3)</b>
        this.index = index
    }

    @Override
    int getOrder() {
        index
    }
}

/*
 * Copyright 2017-2020 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.micronaut.docs.config.env

import io.micronaut.context.annotation.EachProperty
import io.micronaut.context.annotation.Parameter
import io.micronaut.core.order.Ordered
import java.time.Duration

@EachProperty(value = "ratelimits", list = true) <b>(1)</b>
class RateLimitsConfiguration
    constructor(@param:Parameter private val index: Int) <b>(3)</b>
    : Ordered { <b>(2)</b>

    var period: Duration? = null
    var limit: Int? = null

    override fun getOrder(): Int {
        return index
    }

}

Using @EachBean

@Factory <b>(1)</b>
public class DataSourceFactory {

    @EachBean(DataSourceConfiguration.class) <b>(2)</b>
    DataSource dataSource(DataSourceConfiguration configuration) { <b>(3)</b>
        URI url = configuration.getUrl();
        return new DataSource(url);
    }

Using @EachBean

@Factory <b>(1)</b>
class DataSourceFactory {

    @EachBean(DataSourceConfiguration.class) <b>(2)</b>
    DataSource dataSource(DataSourceConfiguration configuration) { <b>(3)</b>
        URI url = configuration.getUrl()
        return new DataSource(url)
    }

Using @EachBean

@Factory <b>(1)</b>
class DataSourceFactory {

    @EachBean(DataSourceConfiguration::class) <b>(2)</b>
    internal fun dataSource(configuration: DataSourceConfiguration): DataSource { <b>(3)</b>
        val url = configuration.url
        return DataSource(url)
    }

Using a Qualifier

Collection<DataSource> beansOfType = applicationContext.getBeansOfType(DataSource.class);
        assertEquals(2, beansOfType.size()); <b>(1)</b>

        DataSource firstConfig = applicationContext.getBean(
                DataSource.class,
                Qualifiers.byName("one") <b>(2)</b>
        );

Using a Qualifier

when:
        Collection<DataSource> beansOfType = applicationContext.getBeansOfType(DataSource.class)
        assertEquals(2, beansOfType.size()) <b>(1)</b>

        DataSource firstConfig = applicationContext.getBean(
                DataSource.class,
                Qualifiers.byName("one") <b>(2)</b>
        )

Using a Qualifier

val beansOfType = applicationContext.getBeansOfType(DataSource::class.java)
        assertEquals(2, beansOfType.size.toLong()) <b>(1)</b>

        val firstConfig = applicationContext.getBean(
                DataSource::class.java,
                Qualifiers.byName("one") <b>(2)</b>
        )

@ConfigurationProperties Example

import io.micronaut.context.annotation.ConfigurationProperties;
import io.micronaut.core.bind.annotation.Bindable;
import javax.validation.constraints.*;
import java.util.Optional;

@ConfigurationProperties("my.engine") <b>(1)</b>
public interface EngineConfig {

    @Bindable(defaultValue = "Ford") <b>(2)</b>
    @NotBlank <b>(3)</b>
    String getManufacturer();

    @Min(1L)
    int getCylinders();

    @NotNull
    CrankShaft getCrankShaft(); <b>(4)</b>

    @ConfigurationProperties("crank-shaft")
    interface CrankShaft { <b>(5)</b>
        Optional<Double> getRodLength(); <b>(6)</b>
    }
}

@ConfigurationProperties Example

import io.micronaut.context.annotation.ConfigurationProperties
import io.micronaut.core.bind.annotation.Bindable
import javax.validation.constraints.*


@ConfigurationProperties("my.engine") <b>(1)</b>
interface EngineConfig {

    @Bindable(defaultValue = "Ford") <b>(2)</b>
    @NotBlank <b>(3)</b>
    String getManufacturer()

    @Min(1L)
    int getCylinders()

    @NotNull
    CrankShaft getCrankShaft() <b>(4)</b>

    @ConfigurationProperties("crank-shaft")
    static interface CrankShaft { <b>(5)</b>
        Optional<Double> getRodLength() <b>(6)</b>
    }
}

@ConfigurationProperties Example

import io.micronaut.context.annotation.ConfigurationProperties
import io.micronaut.core.bind.annotation.Bindable
import javax.validation.constraints.*
import java.util.Optional


@ConfigurationProperties("my.engine") <b>(1)</b>
interface EngineConfig {

    @get:Bindable(defaultValue = "Ford") <b>(2)</b>
    @get:NotBlank <b>(3)</b>
    val manufacturer: String

    @get:Min(1L)
    val cylinders: Int

    @get:NotNull
    val crankShaft: CrankShaft <b>(4)</b>

    @ConfigurationProperties("crank-shaft")
    interface CrankShaft { <b>(5)</b>
        val rodLength: Double? <b>(6)</b>
    }
}

@ConfigurationProperties Example

import io.micronaut.context.annotation.*;
import io.micronaut.core.bind.annotation.Bindable;
import edu.umd.cs.findbugs.annotations.Nullable;
import javax.validation.constraints.*;
import java.util.Optional;

@ConfigurationProperties("my.engine") <b>(1)</b>
public class EngineConfig {

    private final String manufacturer;
    private final int cylinders;
    private final CrankShaft crankShaft;

    @ConfigurationInject <b>(2)</b>
    public EngineConfig(
            @Bindable(defaultValue = "Ford") @NotBlank String manufacturer, <b>(3)</b>
            @Min(1L) int cylinders, <b>(4)</b>
            @NotNull CrankShaft crankShaft) {
        this.manufacturer = manufacturer;
        this.cylinders = cylinders;
        this.crankShaft = crankShaft;
    }

    public String getManufacturer() {
        return manufacturer;
    }

    public int getCylinders() {
        return cylinders;
    }

    public CrankShaft getCrankShaft() {
        return crankShaft;
    }

    @ConfigurationProperties("crank-shaft")
    public static class CrankShaft { <b>(5)</b>
        private final Double rodLength; <b>(6)</b>

        @ConfigurationInject
        public CrankShaft(@Nullable Double rodLength) {
            this.rodLength = rodLength;
        }

        public Optional<Double> getRodLength() {
            return Optional.ofNullable(rodLength);
        }
    }
}

@ConfigurationProperties Example

import io.micronaut.context.annotation.*
import io.micronaut.core.bind.annotation.Bindable
import javax.annotation.Nullable
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank
import javax.validation.constraints.NotNull


@ConfigurationProperties("my.engine") <b>(1)</b>
class EngineConfig {

    private final String manufacturer
    private final int cylinders
    private final CrankShaft crankShaft

    @ConfigurationInject <b>(2)</b>
    EngineConfig(
                  @Bindable(defaultValue = "Ford") @NotBlank String manufacturer, <b>(3)</b>
                  @Min(1L) int cylinders, <b>(4)</b>
                  @NotNull CrankShaft crankShaft) {
        this.manufacturer = manufacturer
        this.cylinders = cylinders
        this.crankShaft = crankShaft
    }

    String getManufacturer() {
        return manufacturer
    }

    int getCylinders() {
        return cylinders
    }

    CrankShaft getCrankShaft() {
        return crankShaft
    }

    @ConfigurationProperties("crank-shaft")
    static class CrankShaft { <b>(5)</b>
        private final Double rodLength <b>(6)</b>

        @ConfigurationInject
        CrankShaft(@Nullable Double rodLength) {
            this.rodLength = rodLength
        }

        Optional<Double> getRodLength() {
            return Optional.ofNullable(rodLength)
        }
    }
}

@ConfigurationProperties Example

import io.micronaut.context.annotation.*
import io.micronaut.core.bind.annotation.Bindable
import javax.validation.constraints.*
import java.util.Optional


@ConfigurationProperties("my.engine") <b>(1)</b>
data class EngineConfig @ConfigurationInject <b>(2)</b>
    constructor(
        @Bindable(defaultValue = "Ford") @NotBlank <b>(3)</b>
        val manufacturer: String,
        @Min(1L) <b>(4)</b>
        val cylinders: Int,
        @NotNull val crankShaft: CrankShaft) {

    @ConfigurationProperties("crank-shaft")
    data class CrankShaft @ConfigurationInject
    constructor(<b>(5)</b>
            private val rodLength: Double? <b>(6)</b>
    ) {

        fun getRodLength(): Optional<Double> {
            return Optional.ofNullable(rodLength)
        }
    }
}

Supply Configuration

ApplicationContext applicationContext = ApplicationContext.run(CollectionUtils.mapOf(
                "my.engine.cylinders", "8",
                "my.engine.crank-shaft.rod-length", "7.0"
        ));

        Vehicle vehicle = applicationContext.getBean(Vehicle.class);
        System.out.println(vehicle.start());

Supply Configuration

ApplicationContext applicationContext = ApplicationContext.run(
                "my.engine.cylinders": "8",
                "my.engine.crank-shaft.rod-length": "7.0"
        )

        Vehicle vehicle = applicationContext.getBean(Vehicle.class)
        System.out.println(vehicle.start())

Supply Configuration

val map = mapOf(
                "my.engine.cylinders" to "8",
                "my.engine.crank-shaft.rod-length" to "7.0"
        )
        val applicationContext = ApplicationContext.run(map)

        val vehicle = applicationContext.getBean(Vehicle::class.java)

Writing Around Advice

import io.micronaut.aop.*;
import io.micronaut.core.type.MutableArgumentValue;

import javax.inject.Singleton;
import java.util.*;

@Singleton
public class NotNullInterceptor implements MethodInterceptor<Object, Object> { <b>(1)</b>
    @Override
    public Object intercept(MethodInvocationContext<Object, Object> context) {
        Optional<Map.Entry<String, MutableArgumentValue<?>>> nullParam = context.getParameters()
            .entrySet()
            .stream()
            .filter(entry -> {
                MutableArgumentValue<?> argumentValue = entry.getValue();
                return Objects.isNull(argumentValue.getValue());
            })
            .findFirst(); <b>(2)</b>
        if (nullParam.isPresent()) {
            throw new IllegalArgumentException("Null parameter [" + nullParam.get().getKey() + "] not allowed"); <b>(3)</b>
        } else {
            return context.proceed(); <b>(4)</b>
        }
    }
}

import io.micronaut.aop.MethodInterceptor
import io.micronaut.aop.MethodInvocationContext
import io.micronaut.core.type.MutableArgumentValue

import javax.inject.Singleton

@Singleton
class NotNullInterceptor implements MethodInterceptor<Object, Object> { <b>(1)</b>
    @Override
    Object intercept(MethodInvocationContext<Object, Object> context) {
        Optional<Map.Entry<String, MutableArgumentValue<?>>> nullParam = context.getParameters()
            .entrySet()
            .stream()
            .filter({entry ->
                MutableArgumentValue<?> argumentValue = entry.getValue()
                return Objects.isNull(argumentValue.getValue())
            })
            .findFirst() <b>(2)</b>
        if (nullParam.isPresent()) {
            throw new IllegalArgumentException("Null parameter [" + nullParam.get().getKey() + "] not allowed") <b>(3)</b>
        } else {
            return context.proceed() <b>(4)</b>
        }
    }
}

import io.micronaut.aop.MethodInterceptor
import io.micronaut.aop.MethodInvocationContext
import io.micronaut.core.type.MutableArgumentValue

import javax.inject.Singleton
import java.util.Objects
import java.util.Optional


@Singleton
class NotNullInterceptor : MethodInterceptor<Any, Any> { <b>(1)</b>
    override fun intercept(context: MethodInvocationContext<Any, Any>): Any {
        val nullParam = context.parameters
                .entries
                .stream()
                .filter { entry ->
                    val argumentValue = entry.value
                    Objects.isNull(argumentValue.value)
                }
                .findFirst() <b>(2)</b>
        return if (nullParam.isPresent) {
            throw IllegalArgumentException("Null parameter [" + nullParam.get().key + "] not allowed") <b>(3)</b>
        } else {
            context.proceed() <b>(4)</b>
        }
    }
}

import io.micronaut.context.annotation.Type;
import io.micronaut.aop.Around;
import java.lang.annotation.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Documented
@Retention(RUNTIME) <b>(1)</b>
@Target({ElementType.TYPE, ElementType.METHOD}) <b>(2)</b>
@Around <b>(3)</b>
@Type(NotNullInterceptor.class) <b>(4)</b>
public @interface NotNull {
}

import io.micronaut.aop.Around
import io.micronaut.context.annotation.Type

import java.lang.annotation.Documented
import java.lang.annotation.ElementType
import java.lang.annotation.Retention
import java.lang.annotation.Target

import static java.lang.annotation.RetentionPolicy.RUNTIME

@Documented
@Retention(RUNTIME) <b>(1)</b>
@Target([ElementType.TYPE, ElementType.METHOD]) <b>(2)</b>
@Around <b>(3)</b>
@Type(NotNullInterceptor.class) <b>(4)</b>
@interface NotNull {
}

import io.micronaut.aop.Around
import io.micronaut.context.annotation.Type

import java.lang.annotation.Documented
import java.lang.annotation.Retention

import java.lang.annotation.RetentionPolicy.RUNTIME


@Documented
@Retention(RUNTIME) <b>(1)</b>
@Target(AnnotationTarget.CLASS, AnnotationTarget.FILE, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER) <b>(2)</b>
@Around <b>(3)</b>
@Type(NotNullInterceptor::class) <b>(4)</b>
annotation class NotNull

@Singleton
public class NotNullExample {

    @NotNull
    void doWork(String taskName) {
        System.out.println("Doing job: " + taskName);
    }
}

@Singleton
class NotNullExample {

    @NotNull
    void doWork(String taskName) {
        println("Doing job: " + taskName)
    }
}

@Singleton
open class NotNullExample {

    @NotNull
    open fun doWork(taskName: String?) {
        println("Doing job: $taskName")
    }
}

@Rule
    public ExpectedException thrown = ExpectedException.none();

    @Test
    public void testNotNull() {
        try (ApplicationContext applicationContext = ApplicationContext.run()) {
            NotNullExample exampleBean = applicationContext.getBean(NotNullExample.class);

            thrown.expect(IllegalArgumentException.class);
            thrown.expectMessage("Null parameter [taskName] not allowed");

            exampleBean.doWork(null);
        }
    }

void "test not null"() {
        when:
        ApplicationContext applicationContext = ApplicationContext.run()
        NotNullExample exampleBean = applicationContext.getBean(NotNullExample.class)

        exampleBean.doWork(null)

        then:
        IllegalArgumentException ex = thrown()
        ex.message == 'Null parameter [taskName] not allowed'

        cleanup:
        applicationContext.close()
    }

@Test
    fun testNotNull() {
        val applicationContext = ApplicationContext.run()
        val exampleBean = applicationContext.getBean(NotNullExample::class.java)

        val exception = shouldThrow<IllegalArgumentException> {
            exampleBean.doWork(null)
        }
        exception.message shouldBe "Null parameter [taskName] not allowed"
        applicationContext.close()
    }

Customizing Proxy Generation

AOP Advice on @Factory Beans

@Timed
@Factory
public class MyFactory {

    @Prototype
    public MyBean myBean() {
        return new MyBean();
    }
}

@Timed
@Factory
class MyFactory {

    @Prototype
    MyBean myBean() {
        return new MyBean()
    }
}

@Timed
@Factory
open class MyFactory {

    @Prototype
    open fun myBean(): MyBean {
        return MyBean()
    }
}

@Factory
public class MyFactory {

    @Prototype
    @Timed
    public MyBean myBean() {
        return new MyBean();
    }
}

@Factory
class MyFactory {

    @Prototype
    @Timed
    MyBean myBean() {
        return new MyBean()
    }
}

@Factory
open class MyFactory {

    @Prototype
    @Timed
    open fun myBean(): MyBean {
        return MyBean()
    }
}

Introduction Advice Annotation Example

import static java.lang.annotation.RetentionPolicy.RUNTIME;

import io.micronaut.aop.Introduction;
import io.micronaut.context.annotation.Bean;
import io.micronaut.context.annotation.Type;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

@Introduction <b>(1)</b>
@Type(StubIntroduction.class) <b>(2)</b>
@Bean <b>(3)</b>
@Documented
@Retention(RUNTIME)
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE, ElementType.METHOD})
public @interface Stub {
    String value() default "";
}

Introduction Advice Annotation Example

import io.micronaut.aop.Introduction
import io.micronaut.context.annotation.Bean
import io.micronaut.context.annotation.Type

import java.lang.annotation.Documented
import java.lang.annotation.ElementType
import java.lang.annotation.Retention
import java.lang.annotation.Target

import static java.lang.annotation.RetentionPolicy.RUNTIME

@Introduction <b>(1)</b>
@Type(StubIntroduction.class) <b>(2)</b>
@Bean <b>(3)</b>
@Documented
@Retention(RUNTIME)
@Target([ElementType.TYPE, ElementType.ANNOTATION_TYPE, ElementType.METHOD])
@interface Stub {
    String value() default ""
}

Introduction Advice Annotation Example

import io.micronaut.aop.Introduction
import io.micronaut.context.annotation.Bean
import io.micronaut.context.annotation.Type

import java.lang.annotation.Documented
import java.lang.annotation.Retention

import java.lang.annotation.RetentionPolicy.RUNTIME


@Introduction <b>(1)</b>
@Type(StubIntroduction::class) <b>(2)</b>
@Bean <b>(3)</b>
@Documented
@Retention(RUNTIME)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FILE, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER)
annotation class Stub(val value: String = "")

StubIntroduction

import io.micronaut.aop.*;
import javax.inject.Singleton;

@Singleton
public class StubIntroduction implements MethodInterceptor<Object,Object> { <b>(1)</b>

    @Override
    public Object intercept(MethodInvocationContext<Object, Object> context) {
        return context.getValue( <b>(2)</b>
                Stub.class,
                context.getReturnType().getType()
        ).orElse(null); <b>(3)</b>
    }
}

StubIntroduction

import io.micronaut.aop.MethodInterceptor
import io.micronaut.aop.MethodInvocationContext

import javax.inject.Singleton

@Singleton
class StubIntroduction implements MethodInterceptor<Object,Object> { <b>(1)</b>

    @Override
    Object intercept(MethodInvocationContext<Object, Object> context) {
        return context.getValue( <b>(2)</b>
                Stub.class,
                context.getReturnType().getType()
        ).orElse(null) <b>(3)</b>
    }
}

StubIntroduction

import io.micronaut.aop.MethodInterceptor
import io.micronaut.aop.MethodInvocationContext

import javax.inject.Singleton


@Singleton
class StubIntroduction : MethodInterceptor<Any, Any> { <b>(1)</b>

    override fun intercept(context: MethodInvocationContext<Any, Any>): Any? {
        return context.getValue<Any>( <b>(2)</b>
                Stub::class.java,
                context.returnType.type
        ).orElse(null) <b>(3)</b>
    }
}

StubExample

@Stub
public interface StubExample {

    @Stub("10")
    int getNumber();

    LocalDateTime getDate();
}

StubExample

@Stub
interface StubExample {

    @Stub("10")
    int getNumber()

    LocalDateTime getDate()
}

StubExample

@Stub
interface StubExample {

    @get:Stub("10")
    val number: Int

    val date: LocalDateTime?
}

Testing Introduction Advice

StubExample stubExample = applicationContext.getBean(StubExample.class);

            assertEquals(10, stubExample.getNumber());
            assertNull(stubExample.getDate());

Testing Introduction Advice

when:
        StubExample stubExample = applicationContext.getBean(StubExample.class)

        then:
        stubExample.getNumber() == 10
        stubExample.getDate() == null

Testing Introduction Advice

val stubExample = applicationContext.getBean(StubExample::class.java)

        stubExample.number.toLong().shouldBe(10)
        stubExample.date.shouldBe(null)

implementation("io.micronaut:micronaut-validation")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-validation</artifactId>
</dependency>

implementation("io.micronaut:micronaut-hibernate-validator")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-hibernate-validator</artifactId>
</dependency>

Cache Annotations

Configuring Caches

micronaut:
    caches:
        my-cache:
            maximum-size: 20

Dynamic Cache Creation

For use cases where caches cannot be configured ahead of time, aDynamicCacheManager bean can be registered. When a cache is attempted to be retrieved that was not predefined, the dynamic cache manager will be invoked to return a cache.

By default, if there is no other dynamic cache manager defined in the application, Micronaut registers an instance of DefaultDynamicCacheManager that will create Caffeine caches with default values.

Other Cache Implementations

Check the Micronaut Cache project for more information.

Simple Retry

@Retryable
    public List<Book> listBooks() {
        // ...

@Retryable
    List<Book> listBooks() {
        // ...

@Retryable
    open fun listBooks(): List<Book> {
        // ...

@Retryable( attempts = "5",
                delay = "2s" )
    public Book findBook(String title) {
        // ...

@Retryable( attempts = "5",
                delay = "2s" )
    Book findBook(String title) {
        // ...

@Retryable(attempts = "5", delay = "2s")
    open fun findBook(title: String): Book {
        // ...

@Retryable( attempts = "${book.retry.attempts:3}",
                delay = "${book.retry.delay:1s}" )
    public Book getBook(String title) {
        // ...

@Retryable( attempts = "\${book.retry.attempts:3}",
            delay = "\${book.retry.delay:1s}")
    Book getBook(String title) {
        // ...

@Retryable(attempts = "\${book.retry.attempts:3}", delay = "\${book.retry.delay:1s}")
    open fun getBook(title: String): Book {
        // ...

Reactive Retry

@Retryable
    public Flowable<Book> streamBooks() {
        // ...

@Retryable
    Flowable<Book> streamBooks() {
        // ...

@Retryable
    open fun streamBooks(): Flowable<Book> {
        // ...

Circuit Breaker

@CircuitBreaker(reset = "30s")
    public List<Book> findBooks() {
        // ...

@CircuitBreaker(reset = "30s")
    List<Book> findBooks() {
        // ...

@CircuitBreaker(reset = "30s")
    open fun findBooks(): List<Book> {
        // ...

Bean Creation Retry

@Factory <i data-value="1"></i><b>(1)</b>
public class Neo4jDriverFactory {
    ...
    @Retryable(ServiceUnavailableException.class) <i data-value="2"></i><b>(2)</b>
    @Bean(preDestroy = "close")
    public Driver buildDriver() {
        ...
    }
}

Retry Events

You can registerRetryEventListener instances as beans in order to listen forRetryEvent events that are published every time an operation is retried.

In addition, you can register event listeners forCircuitOpenEvent, when a circuit breaker circuit is opened, orCircuitClosedEvent for when a circuit is closed.

Using the @Scheduled Annotation

@Scheduled(fixedRate = "5m")
    void everyFiveMinutes() {
        System.out.println("Executing everyFiveMinutes()");
    }

@Scheduled(fixedRate = "5m")
    void everyFiveMinutes() {
        System.out.println("Executing everyFiveMinutes()")
    }

@Scheduled(fixedRate = "5m")
    internal fun everyFiveMinutes() {
        println("Executing everyFiveMinutes()")
    }

@Scheduled(fixedDelay = "5m")
    void fiveMinutesAfterLastExecution() {
        System.out.println("Executing fiveMinutesAfterLastExecution()");
    }

@Scheduled(fixedDelay = "5m")
    void fiveMinutesAfterLastExecution() {
        System.out.println("Executing fiveMinutesAfterLastExecution()")
    }

@Scheduled(fixedDelay = "5m")
    internal fun fiveMinutesAfterLastExecution() {
        println("Executing fiveMinutesAfterLastExecution()")
    }

@Scheduled(cron = "0 15 10 ? * MON" )
    void everyMondayAtTenFifteenAm() {
        System.out.println("Executing everyMondayAtTenFifteenAm()");
    }

@Scheduled(cron = "0 15 10 ? * MON" )
    void everyMondayAtTenFifteenAm() {
        System.out.println("Executing everyMondayAtTenFifteenAm()")
    }

@Scheduled(cron = "0 15 10 ? * MON")
    internal fun everyMondayAtTenFifteenAm() {
        println("Executing everyMondayAtTenFifteenAm()")
    }

@Scheduled(initialDelay = "1m" )
    void onceOneMinuteAfterStartup() {
        System.out.println("Executing onceOneMinuteAfterStartup()");
    }

@Scheduled(initialDelay = "1m" )
    void onceOneMinuteAfterStartup() {
        System.out.println("Executing onceOneMinuteAfterStartup()")
    }

@Scheduled(initialDelay = "1m")
    internal fun onceOneMinuteAfterStartup() {
        println("Executing onceOneMinuteAfterStartup()")
    }

Programmatically Scheduling Tasks

@Inject
    @Named(TaskExecutors.SCHEDULED)
    TaskScheduler taskScheduler;

@Inject
    @Named(TaskExecutors.SCHEDULED)
    TaskScheduler taskScheduler

@Inject
    @Named(TaskExecutors.SCHEDULED)
    lateinit var taskScheduler: TaskScheduler

Configuring Scheduled Tasks with Annotation Metadata

@Scheduled( fixedRate = "${my.task.rate:5m}",
                initialDelay = "${my.task.delay:1m}" )
    void configuredTask() {
        System.out.println("Executing configuredTask()");
    }

@Scheduled( fixedRate = "\${my.task.rate:5m}",
                initialDelay = "\${my.task.delay:1m}" )
    void configuredTask() {
        System.out.println("Executing configuredTask()")
    }

@Scheduled(fixedRate = "\${my.task.rate:5m}",
            initialDelay = "\${my.task.delay:1m}")
    internal fun configuredTask() {
        println("Executing configuredTask()")
    }

Configuring the Scheduled Task Thread Pool

micronaut:
    executors:
        scheduled:
            type: scheduled
            core-pool-size: 30

Handling Exceptions

By default Micronaut includes a DefaultTaskExceptionHandler bean that implements theTaskExceptionHandler and simply logs the exception if an error occurs invoking a scheduled task.

If you have custom requirements you can replace this bean with a custom implementation (for example if you wish to send an email or shutdown context to fail fast). To do so simply write your ownTaskExceptionHandler and annotate it with @Replaces(DefaultTaskExceptionHandler.class) .

implementation("io.micronaut:micronaut-spring")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-spring</artifactId>
</dependency>

Using @Transactional

import io.micronaut.spring.tx.annotation.*;
...

@Transactional
public Book saveBook(String title) {
    ...
}

implementation("io.micronaut:micronaut-http-server-netty")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-http-server-netty</artifactId>
</dependency>

URI Paths

UriMatchTemplate template = UriMatchTemplate.of("/hello/{name}");

        assertTrue(template.match("/hello/John").isPresent()); <b>(1)</b>
        assertEquals("/hello/John", template.expand(  <b>(2)</b>
                Collections.singletonMap("name", "John")
        ));

given:
        UriMatchTemplate template = UriMatchTemplate.of("/hello/{name}")

        expect:
        template.match("/hello/John").isPresent() <b>(1)</b>
        template.expand(["name": "John"]) == "/hello/John" <b>(2)</b>

val template = UriMatchTemplate.of("/hello/{name}")

        assertTrue(template.match("/hello/John").isPresent) <b>(1)</b>
        assertEquals("/hello/John", template.expand(mapOf("name" to "John")))  <b>(2)</b>

URI Path Variables

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;

@Controller("/issues") <b>(1)</b>
public class IssuesController {

    @Get("/{number}") <b>(2)</b>
    public String issue(@PathVariable Integer number) { <b>(3)</b>
        return "Issue # " + number + "!"; <b>(4)</b>
    }
}

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.PathVariable

@Controller("/issues") <b>(1)</b>
class IssuesController {

    @Get("/{number}") <b>(2)</b>
    String issue(@PathVariable Integer number) { <b>(3)</b>
        "Issue # " + number + "!" <b>(4)</b>
    }
}

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.PathVariable

@Controller("/issues") <b>(1)</b>
class IssuesController {

    @Get("/{number}") <b>(2)</b>
    fun issue(@PathVariable number: Int): String { <b>(3)</b>
        return "Issue # $number!" <b>(4)</b>
    }
}

import io.micronaut.context.ApplicationContext;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.exceptions.HttpClientResponseException;
import io.micronaut.runtime.server.EmbeddedServer;
import org.junit.AfterClass;
import org.junit.BeforeClass;
import org.junit.Test;
import org.junit.jupiter.api.Assertions;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

public class IssuesControllerTest {

    private static EmbeddedServer server;
    private static HttpClient client;

    @BeforeClass <b>(1)</b>
    public static void setupServer() {
        server = ApplicationContext.run(EmbeddedServer.class);
        client = server
                    .getApplicationContext()
                    .createBean(HttpClient.class, server.getURL());
    }

    @AfterClass <b>(2)</b>
    public static void stopServer() {
        if(server != null) {
            server.stop();
        }
        if(client != null) {
            client.stop();
        }
    }

    @Test
    public void testIssue() throws Exception {
        String body = client.toBlocking().retrieve("/issues/12"); <b>(3)</b>

        assertNotNull(body);
        assertEquals("Issue # 12!", body); <b>(4)</b>
    }

    @Test
    public void testShowWithInvalidInteger() {
        HttpClientResponseException e =Assertions.assertThrows(HttpClientResponseException.class, () ->
                client.toBlocking().exchange("/issues/hello"));

        assertEquals(400, e.getStatus().getCode()); <b>(5)</b>
    }

    @Test
    public void testIssueWithoutNumber() {
        HttpClientResponseException e = Assertions.assertThrows(HttpClientResponseException.class, () ->
                client.toBlocking().exchange("/issues/"));

        assertEquals(404, e.getStatus().getCode()); <b>(6)</b>
    }
}

import io.micronaut.context.ApplicationContext
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.runtime.server.EmbeddedServer
import spock.lang.AutoCleanup
import spock.lang.Shared
import spock.lang.Specification

class IssuesControllerTest extends Specification {

    @Shared
    @AutoCleanup <b>(2)</b>
    EmbeddedServer embeddedServer = ApplicationContext.run(EmbeddedServer) <b>(1)</b>

    @Shared
    @AutoCleanup <b>(2)</b>
    HttpClient client = HttpClient.create(embeddedServer.URL) <b>(1)</b>

    void "test issue"() {
        when:
        String body = client.toBlocking().retrieve("/issues/12") <b>(3)</b>

        then:
        body != null
        body == "Issue # 12!" <b>(4)</b>
    }

    void "/issues/{number} with an invalid Integer number responds 400"() {
        when:
        client.toBlocking().exchange("/issues/hello")

        then:
        HttpClientResponseException e = thrown(HttpClientResponseException)
        e.status.code == 400 <b>(5)</b>
    }

    void "/issues/{number} without number responds 404"() {
        when:
        client.toBlocking().exchange("/issues/")

        then:
        HttpClientResponseException e = thrown(HttpClientResponseException)
        e.status.code == 404 <b>(6)</b>
    }
}

import io.micronaut.context.ApplicationContext
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.runtime.server.EmbeddedServer
import io.kotlintest.shouldBe
import io.kotlintest.shouldNotBe
import io.kotlintest.shouldThrow
import io.kotlintest.specs.StringSpec
import io.micronaut.http.client.RxHttpClient

class IssuesControllerTest: StringSpec() {

    val embeddedServer = autoClose( <b>(2)</b>
            ApplicationContext.run(EmbeddedServer::class.java) <b>(1)</b>
    )

    val client = autoClose( <b>(2)</b>
            embeddedServer.applicationContext.createBean(RxHttpClient::class.java, embeddedServer.getURL()) <b>(1)</b>
    )

    init {
        "test issue" {
            val body = client.toBlocking().retrieve("/issues/12") <b>(3)</b>

            body shouldNotBe null
            body shouldBe "Issue # 12!" <b>(4)</b>
        }

        "test issue with invalid integer" {
            val e = shouldThrow<HttpClientResponseException> { client.toBlocking().exchange<Any>("/issues/hello") }

            e.status.code shouldBe 400 <b>(5)</b>
        }

        "test issue without number" {
            val e = shouldThrow<HttpClientResponseException> { client.toBlocking().exchange<Any>("/issues/") }

            e.status.code shouldBe 404 <b>(6)</b>
        }
    }
}

URI Reserved Character Matching

By default URI variables as defined by the RFC-6570 URI template spec cannot include reserved characters such as / , ? etc.

If you wish to match or expand entire paths then this can be problematic. As per section 3.2.3 of the specification , you can use reserved expansion or matching using the + operator.

For example the URI /books/{+path} will match both /books/foo and /books/foo/bar since the + indicates that the variable path should include reserved characters (in this case / ).

Routing Annotations

Multiple URIs

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

@Controller("/hello")
public class BackwardCompatibleController {

    @Get(uris = {"/{name}", "/person/{name}"}) <b>(1)</b>
    public String hello(String name) { <b>(2)</b>
        return "Hello, " + name;
    }
}

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller("/hello")
class BackwardCompatibleController {

    @Get(uris = ["/{name}", "/person/{name}"]) <b>(1)</b>
    String hello(String name) { <b>(2)</b>
        "Hello, " + name
    }
}

@Controller("/hello")
class BackwardCompatibleController {

    @Get(uris = ["/{name}", "/person/{name}"]) <b>(1)</b>
    fun hello(name: String): String { <b>(2)</b>
        return "Hello, $name"
    }
}

Building Routes Programmatically

import io.micronaut.context.ExecutionHandleLocator;
import io.micronaut.web.router.DefaultRouteBuilder;
import javax.inject.Inject;
import javax.inject.Singleton;

@Singleton
public class MyRoutes extends DefaultRouteBuilder { <b>(1)</b>

    public MyRoutes(ExecutionHandleLocator executionHandleLocator, UriNamingStrategy uriNamingStrategy) {
        super(executionHandleLocator, uriNamingStrategy);
    }

    @Inject
    void issuesRoutes(IssuesController issuesController) { <b>(2)</b>
        GET("/issues/show/{number}", issuesController, "issue", Integer.class); <b>(3)</b>
    }
}

import io.micronaut.web.router.GroovyRouteBuilder

import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class MyRoutes extends GroovyRouteBuilder { <b>(1)</b>

    MyRoutes(ExecutionHandleLocator executionHandleLocator, UriNamingStrategy uriNamingStrategy, ConversionService<?> conversionService) {
        super(executionHandleLocator, uriNamingStrategy, conversionService)
    }

    @Inject
    void issuesRoutes(IssuesController issuesController) { <b>(2)</b>
        GET("/issues/show/{number}", issuesController.&issue) <b>(3)</b>
    }
}

import io.micronaut.context.ExecutionHandleLocator
import io.micronaut.web.router.DefaultRouteBuilder
import io.micronaut.web.router.RouteBuilder

import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class MyRoutes(executionHandleLocator: ExecutionHandleLocator, uriNamingStrategy: RouteBuilder.UriNamingStrategy) :
        DefaultRouteBuilder(executionHandleLocator, uriNamingStrategy) { <b>(1)</b>

    @Inject
    fun issuesRoutes(issuesController: IssuesController) { <b>(2)</b>
        GET("/issues/show/{number}", issuesController, "issue", Int::class.java) <b>(3)</b>
    }
}

Route Compile Time Validation

annotationProcessor "io.micronaut:micronaut-validation" // Java only
kapt "io.micronaut:micronaut-validation" // Kotlin only
compile "io.micronaut:micronaut-validation"

Routing non-standard HTTP methods

@CustomHttpMethod(method = "LOCK", value = "/{name}")
String lock(String name)

Binding Annotations

@Get("/cookieName")
    public String cookieName(@CookieValue("myCookie") String myCookie) {
        // ...
    }

    @Get("/cookieInferred")
    public String cookieInferred(@CookieValue String myCookie) {
        // ...
    }

@Get("/cookieName")
    String cookieName(@CookieValue("myCookie") String myCookie) {
        // ...
    }

    @Get("/cookieInferred")
    String cookieInferred(@CookieValue String myCookie) {
        // ...
    }

@Get("/cookieName")
    fun cookieName(@CookieValue("myCookie") myCookie: String): String {
        // ...
    }

    @Get("/cookieInferred")
    fun cookieInferred(@CookieValue myCookie: String): String {
        // ...
    }

@Get("/headerName")
    public String headerName(@Header("Content-Type") String contentType) {
        // ...
    }

    @Get("/headerInferred")
    public String headerInferred(@Header String contentType) {
        // ...
    }

@Get("/headerName")
    String headerName(@Header("Content-Type") String contentType) {
        // ...
    }

    @Get("/headerInferred")
    String headerInferred(@Header String contentType) {
        // ...
    }

@Get("/headerName")
    fun headerName(@Header("Content-Type") contentType: String): String {
        // ...
    }

    @Get("/headerInferred")
    fun headerInferred(@Header contentType: String): String {
        // ...
    }

Binding from Multiple Query values

import io.micronaut.http.HttpStatus;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

import edu.umd.cs.findbugs.annotations.Nullable;
import javax.validation.Valid;

@Controller("/api")
public class BookmarkController {

    @Get("/bookmarks/list{?paginationCommand*}")
    public HttpStatus list(@Valid @Nullable PaginationCommand paginationCommand) {
        return HttpStatus.OK;
    }
}

import io.micronaut.http.HttpStatus
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

import javax.annotation.Nullable
import javax.validation.Valid

@Controller("/api")
class BookmarkController {

    @Get("/bookmarks/list{?paginationCommand*}")
    HttpStatus list(@Valid @Nullable PaginationCommand paginationCommand) {
        HttpStatus.OK
    }
}

import io.micronaut.http.HttpStatus
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.validation.Validated
import javax.validation.Valid

@Controller("/api")
open class BookmarkController {

    @Get("/bookmarks/list{?paginationCommand*}")
    open fun list(@Valid paginationCommand: PaginationCommand): HttpStatus {
        return HttpStatus.OK
    }
}

Binding from Multiple Bindable values

@Controller("/api")
public class MovieTicketController {

    // You can also omit query parameters like:
    // @Get("/movie/ticket/{movieId}
    @Get("/movie/ticket/{movieId}{?minPrice,maxPrice}")
    public HttpStatus list(@Valid @RequestBean MovieTicketBean bean) {
        return HttpStatus.OK;
    }
}

@Controller("/api")
class MovieTicketController {

    // You can also omit query parameters like:
    // @Get("/movie/ticket/{movieId}
    @Get("/movie/ticket/{movieId}{?minPrice,maxPrice}")
    HttpStatus list(@Valid @RequestBean MovieTicketBean bean) {
        return HttpStatus.OK
    }
}

@Controller("/api")
open class MovieTicketController {

    // You can also omit query parameters like:
    // @Get("/movie/ticket/{movieId}
    @Get("/movie/ticket/{movieId}{?minPrice,maxPrice}")
    open fun list(@Valid @RequestBean bean: MovieTicketBean): HttpStatus {
        return HttpStatus.OK
    }

}

@Introspected
public class MovieTicketBean {

    private HttpRequest<?> httpRequest;

    @PathVariable
    private String movieId;

    @Nullable
    @QueryValue
    @PositiveOrZero
    private Double minPrice;

    @Nullable
    @QueryValue
    @PositiveOrZero
    private Double maxPrice;

    public MovieTicketBean(HttpRequest<?> httpRequest, String movieId, Double minPrice, Double maxPrice) {
        this.httpRequest = httpRequest;
        this.movieId = movieId;
        this.minPrice = minPrice;
        this.maxPrice = maxPrice;
    }

    public HttpRequest<?> getHttpRequest() {
        return httpRequest;
    }

    public String getMovieId() {
        return movieId;
    }

    @Nullable
    public Double getMaxPrice() {
        return maxPrice;
    }

    @Nullable
    public Double getMinPrice() {
        return minPrice;
    }
}

@Introspected
class MovieTicketBean {

    private HttpRequest<?> httpRequest

    @PathVariable
    String movieId

    @Nullable
    @QueryValue
    @PositiveOrZero
    Double minPrice

    @Nullable
    @QueryValue
    @PositiveOrZero
    Double maxPrice
}

@Introspected
data class MovieTicketBean(val httpRequest: HttpRequest<Any>,
                           @field:PathVariable val movieId: String,
                           @field:QueryValue @field:PositiveOrZero @field:Nullable val minPrice: Double,
                           @field:QueryValue @field:PositiveOrZero @field:Nullable val maxPrice: Double)

Bindable Types

@Get("/headerInferred")
    public String headerInferred(@Header String contentType) {
        // ...
    }

@Get("/headerInferred")
    String headerInferred(@Header String contentType) {
        // ...
    }

@Get("/headerInferred")
    fun headerInferred(@Header contentType: String): String {
        // ...
    }

@Get("/headerNullable")
    public String headerNullable(@Nullable @Header String contentType) {
        // ...
    }

@Get("/headerNullable")
    String headerNullable(@Nullable @Header String contentType) {
        // ...
    }

@Get("/headerNullable")
    fun headerNullable(@Header contentType: String?): String? {
        // ...
    }

@Get("/date")
    public String date(@Header ZonedDateTime date) {
        // ...
    }

    @Get("/dateFormat")
    public String dateFormat(@Format("dd/MM/yyyy hh:mm:ss a z") @Header ZonedDateTime date) {
        // ...
    }

@Get("/date")
    String date(@Header ZonedDateTime date) {
        // ...
    }

    @Get("/dateFormat")
    String dateFormat(@Format("dd/MM/yyyy hh:mm:ss a z") @Header ZonedDateTime date) {
        // ...
    }

@Get("/date")
    fun date(@Header date: ZonedDateTime): String {
        // ...
    }

    @Get("/dateFormat")
    fun dateFormat(@Format("dd/MM/yyyy hh:mm:ss a z") @Header date: ZonedDateTime): String {
        // ...
    }

Type Based Binding Parameters

Variables resolution

Request and Response Example

import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

@Controller("/request")
public class MessageController {

    @Get("/hello") <b>(1)</b>
    public HttpResponse<String> hello(HttpRequest<?> request) {
        String name = request.getParameters()
                             .getFirst("name")
                             .orElse("Nobody"); <b>(2)</b>

        return HttpResponse.ok("Hello " + name + "!!")
                 .header("X-My-Header", "Foo"); <b>(3)</b>
    }
}

Request and Response Example

import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller("/request")
class MessageController {

    @Get("/hello") <b>(1)</b>
    HttpResponse<String> hello(HttpRequest<?> request) {
        String name = request.getParameters()
                             .getFirst("name")
                             .orElse("Nobody") <b>(2)</b>

        HttpResponse.ok("Hello " + name + "!!")
                 .header("X-My-Header", "Foo") <b>(3)</b>
    }
}

Request and Response Example

import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller("/request")
class MessageController {

    @Get("/hello") <b>(1)</b>
    fun hello(request: HttpRequest<*>): HttpResponse<String> {
        val name = request.parameters
                .getFirst("name")
                .orElse("Nobody") <b>(2)</b>

        return HttpResponse.ok("Hello $name!!")
                .header("X-My-Header", "Foo") <b>(3)</b>
    }
}

Customizing Processed Content Types

Normally the JSON parsing only happens if the content type is application/json . The otherMediaTypeCodec classes behave in a similar manner that they have pre-defined content types they can process. To extend the list of media types that a given codec should process, you can provide configuration that will be stored inCodecConfiguration:

micronaut:
    codec:
        json:
            additionalTypes:
              - text/javascript
              - ...

Currently supported configuration prefixes are json , json-stream , text , and text-stream .

Configuring the IO thread pool

micronaut:
    executors:
        io:
            type: fixed
            nThreads: 75

Using @ExecuteOn

import io.micronaut.http.annotation.*;
import io.micronaut.scheduling.TaskExecutors;
import io.micronaut.scheduling.annotation.ExecuteOn;

@Controller("/executeOn/people")
public class PersonController {

    private final PersonService personService;

    PersonController(
            PersonService personService) {
        this.personService = personService;
    }

    @Get("/{name}")
    @ExecuteOn(TaskExecutors.IO) <b>(1)</b>
    Person byName(String name) {
        return personService.findByName(name);
    }
}

Using @ExecuteOn

import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@Controller("/executeOn/people")
class PersonController {

    private final PersonService personService

    PersonController(
            PersonService personService) {
        this.personService = personService
    }

    @Get("/{name}")
    @ExecuteOn(TaskExecutors.IO) <b>(1)</b>
    Person byName(String name) {
        return personService.findByName(name)
    }
}

Using @ExecuteOn

import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@Controller("/executeOn/people")
class PersonController (private val personService: PersonService) {
    @Get("/{name}")
    @ExecuteOn(TaskExecutors.IO) <b>(1)</b>
    fun byName(name: String): Person {
        return personService.findByName(name)
    }
}

RxJava subscribeOn Example

import io.micronaut.http.annotation.*;
import io.micronaut.scheduling.TaskExecutors;
import io.reactivex.*;
import io.reactivex.schedulers.Schedulers;
import javax.inject.Named;
import java.util.concurrent.ExecutorService;

@Controller("/subscribeOn/people")
public class PersonController {

    private final Scheduler scheduler;
    private final PersonService personService;

    PersonController(
            @Named(TaskExecutors.IO) ExecutorService executorService, <b>(1)</b>
            PersonService personService) {
        this.scheduler = Schedulers.from(executorService);
        this.personService = personService;
    }

    @Get("/{name}")
    Single<Person> byName(String name) {
        return Single.fromCallable(() ->
                personService.findByName(name) <b>(2)</b>
        ).subscribeOn(scheduler); <b>(3)</b>
    }
}

RxJava subscribeOn Example

import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.reactivex.*
import io.reactivex.schedulers.Schedulers
import javax.inject.Named
import java.util.concurrent.ExecutorService

@Controller("/subscribeOn/people")
class PersonController {

    private final Scheduler scheduler
    private final PersonService personService

    PersonController(
            @Named(TaskExecutors.IO) ExecutorService executorService, <b>(1)</b>
            PersonService personService) {
        this.scheduler = Schedulers.from(executorService)
        this.personService = personService
    }

    @Get("/{name}")
    Single<Person> byName(String name) {
        return Single.fromCallable({ -> <b>(2)</b>
            personService.findByName(name)
        }).subscribeOn(scheduler) <b>(3)</b>
    }
}

RxJava subscribeOn Example

import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.reactivex.*
import io.reactivex.schedulers.Schedulers
import java.util.concurrent.ExecutorService
import javax.inject.Named

@Controller("/subscribeOn/people")
class PersonController internal constructor(
        @Named(TaskExecutors.IO) executorService: ExecutorService, <b>(1)</b>
        val personService: PersonService) {
    private val scheduler: Scheduler

    init {
        scheduler = Schedulers.from(executorService)
    }

    @Get("/{name}")
    fun byName(name: String): Single<Person> {
        return Single.fromCallable { personService.findByName(name) } <b>(2)</b>
                .subscribeOn(scheduler) <b>(3)</b>
    }
}

Using the @Body annotation

import io.micronaut.http.HttpResponse;
import io.micronaut.http.MediaType;
import io.micronaut.http.MutableHttpResponse;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.reactivex.Flowable;
import io.reactivex.Single;

import javax.validation.constraints.Size;

    @Post(value = "/echo", consumes = MediaType.TEXT_PLAIN) <b>(1)</b>
    String echo(@Size(max = 1024) @Body String text) { <b>(2)</b>
        return text; <b>(3)</b>
    }

Using the @Body annotation

import io.micronaut.http.MediaType
import io.micronaut.http.MutableHttpResponse
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.reactivex.Flowable
import io.reactivex.Single

import javax.validation.constraints.Size

    @Post(value = "/echo", consumes = MediaType.TEXT_PLAIN) <b>(1)</b>
    String echo(@Size(max = 1024) @Body String text) { <b>(2)</b>
        text <b>(3)</b>
    }

Using the @Body annotation

import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.MutableHttpResponse
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.reactivex.Flowable
import io.reactivex.Single

import javax.validation.constraints.Size


@Controller("/receive")
open class MessageController {

    @Post(value = "/echo", consumes = [MediaType.TEXT_PLAIN]) <b>(1)</b>
    open fun echo(@Size(max = 1024) @Body text: String): String { <b>(2)</b>
        return text <b>(3)</b>
    }
}

Using RxJava 2 to Read the request body

@Post(value = "/echo-flow", consumes = MediaType.TEXT_PLAIN) <b>(1)</b>
    Single<MutableHttpResponse<String>> echoFlow(@Body Flowable<String> text) { <b>(2)</b>
        return text.collect(StringBuffer::new, StringBuffer::append) <b>(3)</b>
                   .map(buffer ->
                        HttpResponse.ok(buffer.toString())
                   );
    }

Using RxJava 2 to Read the request body

@Post(value = "/echo-flow", consumes = MediaType.TEXT_PLAIN) <b>(1)</b>
    Single<MutableHttpResponse<String>> echoFlow(@Body Flowable<String> text) { <b>(2)</b>
        return text.collect({ x -> new StringBuffer()}, { StringBuffer sb, String s -> sb.append(s)}) <b>(3)</b>
                   .map({ buffer ->
                       HttpResponse.ok(buffer.toString())
                   });
    }

Using RxJava 2 to Read the request body

@Post(value = "/echo-flow", consumes = [MediaType.TEXT_PLAIN]) <b>(1)</b>
    open fun echoFlow(@Body text: Flowable<String>): Single<MutableHttpResponse<String>> { <b>(2)</b>
        return text.collect({ StringBuffer() }, { obj, str -> obj.append(str) }) <b>(3)</b>
                .map { buffer -> HttpResponse.ok(buffer.toString()) }
    }

Binding using Reactive Frameworks

@Controller("/people")
public class PersonController {

    Map<String, Person> inMemoryDatastore = new ConcurrentHashMap<>();

    @Post("/saveReactive")
    public Single<HttpResponse<Person>> save(@Body Single<Person> person) { <b>(1)</b>
        return person.map(p -> {
                    inMemoryDatastore.put(p.getFirstName(), p); <b>(2)</b>
                    return HttpResponse.created(p); <b>(3)</b>
                }
        );
    }

}

@Controller("/people")
class PersonController {

    ConcurrentHashMap<String, Person> inMemoryDatastore = [:]

    @Post("/saveReactive")
    Single<HttpResponse<Person>> save(@Body Single<Person> person) { <b>(1)</b>
        person.map({ p ->
            inMemoryDatastore.put(p.getFirstName(), p) <b>(2)</b>
            HttpResponse.created(p) <b>(3)</b>
        })
    }

}

@Controller("/people")
class PersonController {

    internal var inMemoryDatastore: MutableMap<String, Person> = ConcurrentHashMap()

    @Post("/saveReactive")
    fun save(@Body person: Single<Person>): Single<HttpResponse<Person>> { <b>(1)</b>
        return person.map { p ->
            inMemoryDatastore[p.firstName] = p <b>(2)</b>
            HttpResponse.created(p) <b>(3)</b>
        }
    }

}

$ curl -X POST localhost:8080/people -d '{"firstName":"Fred","lastName":"Flintstone","age":45}'

Binding Using CompletableFuture

@Controller("/people")
public class PersonController {

    Map<String, Person> inMemoryDatastore = new ConcurrentHashMap<>();

    @Post("/saveFuture")
    public CompletableFuture<HttpResponse<Person>> save(@Body CompletableFuture<Person> person) {
        return person.thenApply(p -> {
                    inMemoryDatastore.put(p.getFirstName(), p);
                    return HttpResponse.created(p);
                }
        );
    }

}

@Controller("/people")
class PersonController {

    ConcurrentHashMap<String, Person> inMemoryDatastore = [:]

    @Post("/saveFuture")
    CompletableFuture<HttpResponse<Person>> save(@Body CompletableFuture<Person> person) {
        person.thenApply({ p ->
            inMemoryDatastore.put(p.getFirstName(), p)
            HttpResponse.created(p)
        })
    }

}

@Controller("/people")
class PersonController {

    internal var inMemoryDatastore: MutableMap<String, Person> = ConcurrentHashMap()

    @Post("/saveFuture")
    fun save(@Body person: CompletableFuture<Person>): CompletableFuture<HttpResponse<Person>> {
        return person.thenApply { p ->
            inMemoryDatastore[p.firstName] = p
            HttpResponse.created(p)
        }
    }

}

Binding using POJOs

@Controller("/people")
public class PersonController {

    Map<String, Person> inMemoryDatastore = new ConcurrentHashMap<>();

    @Post
    public HttpResponse<Person> save(@Body Person person) {
        inMemoryDatastore.put(person.getFirstName(), person);
        return HttpResponse.created(person);
    }

}

@Controller("/people")
class PersonController {

    ConcurrentHashMap<String, Person> inMemoryDatastore = [:]

    @Post
    HttpResponse<Person> save(@Body Person person) {
        inMemoryDatastore.put(person.getFirstName(), person)
        HttpResponse.created(person)
    }

}

@Controller("/people")
class PersonController {

    internal var inMemoryDatastore: MutableMap<String, Person> = ConcurrentHashMap()

    @Post
    fun save(@Body person: Person): HttpResponse<Person> {
        inMemoryDatastore[person.firstName] = person
        return HttpResponse.created(person)
    }

}

Jackson Configuration

jackson:
    serializationInclusion: ALWAYS

jackson:
    serialization:
        indentOutput: true
        writeDatesAsTimestamps: false
    deserialization:
        useBigIntegerForInts: true
        failOnUnknownProperties: false

implementation("io.micronaut.beanvalidation:micronaut-hibernate-validator")

<dependency>
    <groupId>io.micronaut.beanvalidation</groupId>
    <artifactId>micronaut-hibernate-validator</artifactId>
</dependency>

Example

import io.micronaut.context.annotation.Requires;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.validation.Validated;

import javax.validation.constraints.NotBlank;
import java.util.Collections;

@Validated <b>(1)</b>
@Controller("/email")
public class EmailController {

    @Get("/send")
    public HttpResponse send(@NotBlank String recipient, <b>(2)</b>
                             @NotBlank String subject) { <b>(2)</b>
        return HttpResponse.ok(Collections.singletonMap("msg", "OK"));
    }
}

Example

import io.micronaut.context.annotation.Requires;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.validation.Validated;

import javax.validation.constraints.NotBlank;
import java.util.Collections;

@Validated <b>(1)</b>
@Controller("/email")
class EmailController {

    @Get("/send")
    HttpResponse send(@NotBlank String recipient, <b>(2)</b>
                             @NotBlank String subject) { <b>(2)</b>
        HttpResponse.ok(Collections.singletonMap("msg", "OK"))
    }
}

Example

import io.micronaut.context.annotation.Requires
import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.validation.Validated

import javax.validation.constraints.NotBlank
import java.util.Collections


@Validated <b>(1)</b>
@Controller("/email")
open class EmailController {

    @Get("/send")
    open fun send(@NotBlank recipient: String, <b>(2)</b>
             @NotBlank subject: String): HttpResponse<*> { <b>(2)</b>
        return HttpResponse.ok(Collections.singletonMap("msg", "OK"))
    }
}

Example Test

@Test
    public void testParametersAreValidated() {
        HttpClientResponseException e = Assertions.assertThrows(HttpClientResponseException.class, () ->
            client.toBlocking().exchange("/email/send?subject=Hi&recipient="));
        HttpResponse response = e.getResponse();

        assertEquals(HttpStatus.BAD_REQUEST, response.getStatus());

        response = client.toBlocking().exchange("/email/send?subject=Hi&recipient=me@micronaut.example");

        assertEquals(HttpStatus.OK, response.getStatus());
    }

Example Test

def "test parameter validation"() {
        when:
        client.toBlocking().exchange('/email/send?subject=Hi&recipient=')

        then:
        def e = thrown(HttpClientResponseException)
        def response = e.response
        response.status == HttpStatus.BAD_REQUEST

        when:
        response = client.toBlocking().exchange('/email/send?subject=Hi&recipient=me@micronaut.example')

        then:
        response.status == HttpStatus.OK
    }

Example Test

"test params are validated"() {
            val e = shouldThrow<HttpClientResponseException> {
                client.toBlocking().exchange<Any>("/email/send?subject=Hi&recipient=")
            }
            var response = e.response

            response.status shouldBe HttpStatus.BAD_REQUEST

            response = client.toBlocking().exchange<Any>("/email/send?subject=Hi&recipient=me@micronaut.example")

            response.status shouldBe HttpStatus.OK
        }

Example

import io.micronaut.context.annotation.Requires;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.validation.Validated;

import javax.validation.Valid;
import java.util.Collections;

@Validated <b>(1)</b>
@Controller("/email")
public class EmailController {

    @Post("/send")
    public HttpResponse send(@Body @Valid Email email) { <b>(2)</b>
        return HttpResponse.ok(Collections.singletonMap("msg", "OK"));    }
}

Example

import io.micronaut.context.annotation.Requires;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.validation.Validated;

import javax.validation.Valid;
import java.util.Collections;

@Validated <b>(1)</b>
@Controller("/email")
class EmailController {

    @Post("/send")
    HttpResponse send(@Body @Valid Email email) { <b>(2)</b>
        HttpResponse.ok(Collections.singletonMap("msg", "OK"))
    }
}

Example

import io.micronaut.context.annotation.Requires
import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.validation.Validated

import javax.validation.Valid
import java.util.Collections


@Validated <b>(1)</b>
@Controller("/email")
open class EmailController {

    @Post("/send")
    open fun send(@Body @Valid email: Email): HttpResponse<*> { <b>(2)</b>
        return HttpResponse.ok(Collections.singletonMap("msg", "OK"))
    }
}

Status Handlers

Local Error Handling

@Error
    public HttpResponse<JsonError> jsonError(HttpRequest request, JsonParseException jsonParseException) { <b>(1)</b>
        JsonError error = new JsonError("Invalid JSON: " + jsonParseException.getMessage()) <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()));

        return HttpResponse.<JsonError>status(HttpStatus.BAD_REQUEST, "Fix Your JSON")
                .body(error); <b>(3)</b>
    }

@Error
    HttpResponse<JsonError> jsonError(HttpRequest request, JsonParseException jsonParseException) { <b>(1)</b>
        JsonError error = new JsonError("Invalid JSON: " + jsonParseException.getMessage()) <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()))

        HttpResponse.<JsonError>status(HttpStatus.BAD_REQUEST, "Fix Your JSON")
                .body(error) <b>(3)</b>
    }

@Error
    fun jsonError(request: HttpRequest<*>, jsonParseException: JsonParseException): HttpResponse<JsonError> { <b>(1)</b>
        val error = JsonError("Invalid JSON: " + jsonParseException.message) <b>(2)</b>
                .link(Link.SELF, Link.of(request.uri))

        return HttpResponse.status<JsonError>(HttpStatus.BAD_REQUEST, "Fix Your JSON")
                .body(error) <b>(3)</b>
    }

@Error(status = HttpStatus.NOT_FOUND)
    public HttpResponse<JsonError> notFound(HttpRequest request) { <b>(1)</b>
        JsonError error = new JsonError("Person Not Found") <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()));

        return HttpResponse.<JsonError>notFound()
                .body(error); <b>(3)</b>
    }

@Error(status = HttpStatus.NOT_FOUND)
    HttpResponse<JsonError> notFound(HttpRequest request) { <b>(1)</b>
        JsonError error = new JsonError("Person Not Found") <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()))

        HttpResponse.<JsonError>notFound()
                .body(error) <b>(3)</b>
    }

@Error(status = HttpStatus.NOT_FOUND)
    fun notFound(request: HttpRequest<*>): HttpResponse<JsonError> { <b>(1)</b>
        val error = JsonError("Person Not Found") <b>(2)</b>
                .link(Link.SELF, Link.of(request.uri))

        return HttpResponse.notFound<JsonError>()
                .body(error) <b>(3)</b>
    }

Global Error Handling

@Error(global = true) <b>(1)</b>
    public HttpResponse<JsonError> error(HttpRequest request, Throwable e) {
        JsonError error = new JsonError("Bad Things Happened: " + e.getMessage()) <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()));

        return HttpResponse.<JsonError>serverError()
                .body(error); <b>(3)</b>
    }

@Error(global = true) <b>(1)</b>
    HttpResponse<JsonError> error(HttpRequest request, Throwable e) {
        JsonError error = new JsonError("Bad Things Happened: " + e.getMessage()) <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()))

        HttpResponse.<JsonError>serverError()
                .body(error) <b>(3)</b>
    }

@Error(global = true) <b>(1)</b>
    fun error(request: HttpRequest<*>, e: Throwable): HttpResponse<JsonError> {
        val error = JsonError("Bad Things Happened: " + e.message) <b>(2)</b>
                .link(Link.SELF, Link.of(request.uri))

        return HttpResponse.serverError<JsonError>()
                .body(error) <b>(3)</b>
    }

@Error(status = HttpStatus.NOT_FOUND)
    public HttpResponse<JsonError> notFound(HttpRequest request) { <b>(1)</b>
        JsonError error = new JsonError("Person Not Found") <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()));

        return HttpResponse.<JsonError>notFound()
                .body(error); <b>(3)</b>
    }

@Error(status = HttpStatus.NOT_FOUND)
    HttpResponse<JsonError> notFound(HttpRequest request) { <b>(1)</b>
        JsonError error = new JsonError("Person Not Found") <b>(2)</b>
                .link(Link.SELF, Link.of(request.getUri()))

        HttpResponse.<JsonError>notFound()
                .body(error) <b>(3)</b>
    }

@Error(status = HttpStatus.NOT_FOUND)
    fun notFound(request: HttpRequest<*>): HttpResponse<JsonError> { <b>(1)</b>
        val error = JsonError("Person Not Found") <b>(2)</b>
                .link(Link.SELF, Link.of(request.uri))

        return HttpResponse.notFound<JsonError>()
                .body(error) <b>(3)</b>
    }

ExceptionHandler

public class OutOfStockException extends RuntimeException {
}

class OutOfStockException extends RuntimeException {
}

class OutOfStockException : RuntimeException()

@Controller("/books")
public class BookController {

    @Produces(MediaType.TEXT_PLAIN)
    @Get("/stock/{isbn}")
    Integer stock(String isbn) {
        throw new OutOfStockException();
    }
}

@Controller("/books")
class BookController {

    @Produces(MediaType.TEXT_PLAIN)
    @Get("/stock/{isbn}")
    Integer stock(String isbn) {
        throw new OutOfStockException()
    }
}

@Controller("/books")
class BookController {

    @Produces(MediaType.TEXT_PLAIN)
    @Get("/stock/{isbn}")
    internal fun stock(isbn: String): Int? {
        throw OutOfStockException()
    }
}

@Produces
@Singleton
@Requires(classes = {OutOfStockException.class, ExceptionHandler.class})
public class OutOfStockExceptionHandler implements ExceptionHandler<OutOfStockException, HttpResponse> {

    @Override
    public HttpResponse handle(HttpRequest request, OutOfStockException exception) {
        return HttpResponse.ok(0);
    }
}

@Produces
@Singleton
@Requires(classes = [OutOfStockException.class, ExceptionHandler.class])
class OutOfStockExceptionHandler implements ExceptionHandler<OutOfStockException, HttpResponse> {

    @Override
    HttpResponse handle(HttpRequest request, OutOfStockException exception) {
        HttpResponse.ok(0)
    }
}

@Produces
@Singleton
@Requirements(
        Requires(classes = [OutOfStockException::class, ExceptionHandler::class])
)
class OutOfStockExceptionHandler : ExceptionHandler<OutOfStockException, HttpResponse<*>> {

    override fun handle(request: HttpRequest<*>, exception: OutOfStockException): HttpResponse<*> {
        return HttpResponse.ok(0)
    }
}

Versioning an API

import io.micronaut.core.version.annotation.Version;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

@Controller("/versioned")
class VersionedController {

    @Version("1") <b>(1)</b>
    @Get("/hello")
    String helloV1() {
        return "helloV1";
    }

    @Version("2") <b>(2)</b>
    @Get("/hello")
    String helloV2() {
        return "helloV2";
    }

Versioning an API

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller("/versioned")
class VersionedController {

    @Version("1") <b>(1)</b>
    @Get("/hello")
    String helloV1() {
        "helloV1"
    }

    @Version("2") <b>(2)</b>
    @Get("/hello")
    String helloV2() {
        "helloV2"
    }

Versioning an API

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get


@Controller("/versioned")
internal class VersionedController {

    @Version("1") <b>(1)</b>
    @Get("/hello")
    fun helloV1(): String {
        return "helloV1"
    }

    @Version("2") <b>(2)</b>
    @Get("/hello")
    fun helloV2(): String {
        return "helloV2"
    }

Enabling Versioning

micronaut:
    router:
        versioning:
            enabled: true

Configuring Versioning

micronaut:
    router:
        versioning:
            enabled: true <i data-value="1"></i><b>(1)</b>
            parameter:
                enabled: false <i data-value="2"></i><b>(2)</b>
                names: 'v,api-version' <i data-value="3"></i><b>(3)</b>
            header:
                enabled: true <i data-value="4"></i><b>(4)</b>
                names: <i data-value="5"></i><b>(5)</b>
                    - 'X-API-VERSION'
                    - 'Accept-Version'

Default Version

It is possible to supply a default version through configuration.

micronaut:
    router:
        versioning:
            enabled: true
            default-version: 3 <i data-value="1"></i><b>(1)</b>

A route will not be matched if the following conditions are met:

• The default version is configured

• No version is found in the request

• The route defines a version

• The route version does not match the default version

If the incoming request specifies a version then the default version has no effect.

Versioning Client Requests

Micronaut’sDeclarative HTTP clientalso supports automatic versioning of outgoing requests via the@Version annotation.

By default if you annotate a client interface with@Version the value supplied to the annotation will be included using the X-API-VERSION header.

For example:

import io.micronaut.core.version.annotation.Version;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.client.annotation.Client;
import io.reactivex.Single;

@Client("/hello")
@Version("1") <b>(1)</b>
public interface HelloClient {

    @Get("/greeting/{name}")
    String sayHello(String name);

    @Version("2")
    @Get("/greeting/{name}")
    Single<String> sayHelloTwo(String name); <b>(2)</b>
}

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import io.reactivex.Single


@Client("/hello")
@Version("1") <b>(1)</b>
interface HelloClient {

    @Get("/greeting/{name}")
    String sayHello(String name)

    @Version("2")
    @Get("/greeting/{name}")
    Single<String> sayHelloTwo(String name) <b>(2)</b>
}

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import io.reactivex.Single

@Client("/hello")
@Version("1") <b>(1)</b>
interface HelloClient {

    @Get("/greeting/{name}")
    fun sayHello(name : String) : String

    @Version("2")
    @Get("/greeting/{name}")
    fun sayHelloTwo(name : String) : Single<String>  <b>(2)</b>
}

The default behaviour for how the version is sent for each call can be configured with DefaultClientVersioningConfiguration :

For example to use Accept-Version as the header name:

micronaut:
    http:
        client:
            versioning:
                default:
                    headers:
                        - 'Accept-Version'
                        - 'X-API-VERSION'

The default key is used to refer to the default configuration. You can specify client specific configuration by using the value passed to @Client (typically the service ID). For example:

micronaut:
    http:
        client:
            versioning:
                greeting-service:
                    headers:
                        - 'Accept-Version'
                        - 'X-API-VERSION'

The above uses a key called greeting-service which can be used to configure a client annotated with @Client('greeting-service') .

Binding Form Data to POJOs

@Controller("/people")
public class PersonController {

    Map<String, Person> inMemoryDatastore = new ConcurrentHashMap<>();

    @Post
    public HttpResponse<Person> save(@Body Person person) {
        inMemoryDatastore.put(person.getFirstName(), person);
        return HttpResponse.created(person);
    }

}

Binding Form Data to POJOs

@Controller("/people")
class PersonController {

    ConcurrentHashMap<String, Person> inMemoryDatastore = [:]

    @Post
    HttpResponse<Person> save(@Body Person person) {
        inMemoryDatastore.put(person.getFirstName(), person)
        HttpResponse.created(person)
    }

}

Binding Form Data to POJOs

@Controller("/people")
class PersonController {

    internal var inMemoryDatastore: MutableMap<String, Person> = ConcurrentHashMap()

    @Post
    fun save(@Body person: Person): HttpResponse<Person> {
        inMemoryDatastore[person.firstName] = person
        return HttpResponse.created(person)
    }

}

Binding Form Data to Parameters

@Controller("/people")
public class PersonController {

    Map<String, Person> inMemoryDatastore = new ConcurrentHashMap<>();

    @Post("/saveWithArgs")
    public HttpResponse<Person> save(String firstName, String lastName, Optional<Integer> age) {
        Person p = new Person(firstName, lastName);
        age.ifPresent(p::setAge);
        inMemoryDatastore.put(p.getFirstName(), p);
        return HttpResponse.created(p);
    }

}

Binding Form Data to Parameters

@Controller("/people")
class PersonController {

    ConcurrentHashMap<String, Person> inMemoryDatastore = [:]

    @Post("/saveWithArgs")
    HttpResponse<Person> save(String firstName, String lastName, Optional<Integer> age) {
        Person p = new Person(firstName, lastName)
        age.ifPresent({ a -> p.setAge(a)})
        inMemoryDatastore.put(p.getFirstName(), p)
        HttpResponse.created(p)
    }

}

Binding Form Data to Parameters

@Controller("/people")
class PersonController {

    internal var inMemoryDatastore: MutableMap<String, Person> = ConcurrentHashMap()

    @Post("/saveWithArgs")
    fun save(firstName: String, lastName: String, age: Optional<Int>): HttpResponse<Person> {
        val p = Person(firstName, lastName)
        age.ifPresent { p.age = it }
        inMemoryDatastore[p.firstName] = p
        return HttpResponse.created(p)
    }

}

Reactively Writing Response Data

Micronaut’s HTTP server supports writing chunks of response data by returning a Publisher the emits objects that can be encoded to the HTTP response.

The following table summarizes example return type signatures and the behaviour the server exhibits to handle each of them:

When returning reactive type the server will use a Transfer-Encoding of chunked and keep writing data until the Publisher 's onComplete method is called.

The server will request a single item from the Publisher , write the item and then request the next item, controlling back pressure.

Performing Blocking I/O

In some cases you may wish to integrate with a library that does not support non-blocking I/O.

In this case you can return aWritable object from any controller method. TheWritable has various signatures that allowing writing to traditional blocking streams like Writer or OutputStream .

When returning aWritable object the blocking I/O operation will be shifted to the I/O thread pool so that the Netty event loop is not blocked.

The following example demonstrates how to use this API with Groovy’s SimpleTemplateEngine to write a server side template:

import groovy.text.SimpleTemplateEngine;
import groovy.text.Template;
import io.micronaut.core.io.Writable;
import io.micronaut.core.util.CollectionUtils;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.server.exceptions.HttpServerException;

@Controller("/template")
public class TemplateController {

    private final SimpleTemplateEngine templateEngine = new SimpleTemplateEngine();
    private final Template template;

    public TemplateController() {
        template = initTemplate(); <b>(1)</b>
    }

    @Get(value = "/welcome", produces = MediaType.TEXT_PLAIN)
    Writable render() { <b>(2)</b>
        return writer -> template.make( <b>(3)</b>
            CollectionUtils.mapOf(
                    "firstName", "Fred",
                    "lastName", "Flintstone"
            )
        ).writeTo(writer);
    }

    private Template initTemplate() {
        Template template;
        try {
            template = templateEngine.createTemplate(
                    "Dear $firstName $lastName. Nice to meet you."
            );
        } catch (Exception e) {
            throw new HttpServerException("Cannot create template");
        }
        return template;
    }
}

import groovy.text.SimpleTemplateEngine;
import groovy.text.Template;
import io.micronaut.core.io.Writable;
import io.micronaut.core.util.CollectionUtils;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.server.exceptions.HttpServerException;

@Controller("/template")
class TemplateController {

    private final SimpleTemplateEngine templateEngine = new SimpleTemplateEngine()
    private final Template template

    TemplateController() {
        template = initTemplate() <b>(1)</b>
    }

    @Get(value = "/welcome", produces = MediaType.TEXT_PLAIN)
    Writable render() { <b>(2)</b>
        { writer ->
            template.make( <b>(3)</b>
                    CollectionUtils.mapOf(
                            "firstName", "Fred",
                            "lastName", "Flintstone"
                    )
            ).writeTo(writer)
        }
    }

    private Template initTemplate() {
        Template template
        try {
            template = templateEngine.createTemplate(
                    'Dear $firstName $lastName. Nice to meet you.'
            )
        } catch (Exception e) {
            throw new HttpServerException("Cannot create template")
        }
        template
    }
}

import groovy.text.SimpleTemplateEngine
import groovy.text.Template
import io.micronaut.core.io.Writable
import io.micronaut.core.util.CollectionUtils
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.server.exceptions.HttpServerException
import java.io.Writer


@Controller("/template")
class TemplateController {

    private val templateEngine = SimpleTemplateEngine()
    private val template: Template

    init {
        template = initTemplate() <b>(1)</b>
    }

    @Get(value = "/welcome", produces = [MediaType.TEXT_PLAIN])
    internal fun render(): Writable { <b>(2)</b>
        return { writer: Writer ->
            val writable = template.make( <b>(3)</b>
                    CollectionUtils.mapOf(
                            "firstName", "Fred",
                            "lastName", "Flintstone"
                    )
            )
            writable.writeTo(writer)
        } as Writable
    }

    private fun initTemplate(): Template {
        val template: Template
        try {
            template = templateEngine.createTemplate(
                    "Dear \$firstName \$lastName. Nice to meet you."
            )
        } catch (e: Exception) {
            throw HttpServerException("Cannot create template")
        }

        return template
    }
}

404 Responses

Often, you want to respond 404 (Not Found) when you don’t find an item in your persistence layer or in similar scenarios.

See the following example:

@Controller("/books")
public class BooksController {

    @Get("/stock/{isbn}")
    public Map stock(String isbn) {
        return null; <b>(1)</b>
    }

    @Get("/maybestock/{isbn}")
    public Maybe<Map> maybestock(String isbn) {
        return Maybe.empty(); <b>(2)</b>
    }
}

@Controller("/books")
class BooksController {

    @Get("/stock/{isbn}")
    Map stock(String isbn) {
        null <b>(1)</b>
    }

    @Get("/maybestock/{isbn}")
    Maybe<Map> maybestock(String isbn) {
        Maybe.empty() <b>(2)</b>
    }
}

@Controller("/books")
class BooksController {

    @Get("/stock/{isbn}")
    fun stock(isbn: String): Map<*, *>? {
        return null <b>(1)</b>
    }

    @Get("/maybestock/{isbn}")
    fun maybestock(isbn: String): Maybe<Map<*, *>> {
        return Maybe.empty() <b>(2)</b>
    }
}

Route Arguments

import io.micronaut.http.HttpResponse;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.multipart.StreamingFileUpload;
import io.reactivex.Single;
import java.io.File;
import org.reactivestreams.Publisher;
import java.io.IOException;

@Controller("/upload")
public class UploadController {

    @Post(value = "/", consumes = MediaType.MULTIPART_FORM_DATA, produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    public Single<HttpResponse<String>> upload(StreamingFileUpload file) { <b>(2)</b>
        File tempFile;
        try {
            tempFile = File.createTempFile(file.getFilename(), "temp");
        } catch (IOException e) {
            return Single.error(e);
        }
        Publisher<Boolean> uploadPublisher = file.transferTo(tempFile); <b>(3)</b>
        return Single.fromPublisher(uploadPublisher)  <b>(4)</b>
            .map(success -> {
                if (success) {
                    return HttpResponse.ok("Uploaded");
                } else {
                    return HttpResponse.<String>status(HttpStatus.CONFLICT)
                                       .body("Upload Failed");
                }
            });
    }
}

import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.StreamingFileUpload
import io.reactivex.Single
import org.reactivestreams.Publisher

@Controller("/upload")
class UploadController {

    @Post(value = "/", consumes = MediaType.MULTIPART_FORM_DATA, produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    Single<HttpResponse<String>> upload(StreamingFileUpload file) { <b>(2)</b>
        File tempFile = File.createTempFile(file.filename, "temp")
        Publisher<Boolean> uploadPublisher = file.transferTo(tempFile) <b>(3)</b>
        Single.fromPublisher(uploadPublisher)  <b>(4)</b>
            .map({ success ->
                if (success) {
                    HttpResponse.ok("Uploaded")
                } else {
                    HttpResponse.<String>status(HttpStatus.CONFLICT)
                            .body("Upload Failed")
                }
            })
    }

}

import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.StreamingFileUpload
import io.reactivex.Single
import java.io.File

@Controller("/upload")
class UploadController {

    @Post(value = "/", consumes = [MediaType.MULTIPART_FORM_DATA], produces = [MediaType.TEXT_PLAIN]) <b>(1)</b>
    fun upload(file: StreamingFileUpload): Single<HttpResponse<String>> { <b>(2)</b>
        val tempFile = File.createTempFile(file.filename, "temp")
        val uploadPublisher = file.transferTo(tempFile) <b>(3)</b>
        return Single.fromPublisher(uploadPublisher)  <b>(4)</b>
                .map { success ->
                    if (success) {
                        HttpResponse.ok("Uploaded")
                    } else {
                        HttpResponse.status<String>(HttpStatus.CONFLICT)
                                .body("Upload Failed")
                    }
                }
    }

}

import io.micronaut.http.HttpResponse;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;

import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

@Controller("/upload")
public class BytesUploadController {

    @Post(value = "/bytes",
            consumes = MediaType.MULTIPART_FORM_DATA,
            produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    public HttpResponse<String> uploadBytes(byte[] file, String fileName) { <b>(2)</b>
        try {
            File tempFile = File.createTempFile(fileName, "temp");
            Path path = Paths.get(tempFile.getAbsolutePath());
            Files.write(path, file); <b>(3)</b>
            return HttpResponse.ok("Uploaded");
        } catch (IOException exception) {
            return HttpResponse.badRequest("Upload Failed");
        }
    }
}

import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post

import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths

@Controller("/upload")
class BytesUploadController {

    @Post(value = "/bytes",
            consumes = MediaType.MULTIPART_FORM_DATA,
            produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    HttpResponse<String> uploadBytes(byte[] file, String fileName) { <b>(2)</b>
        try {
            File tempFile = File.createTempFile(fileName, "temp")
            Path path = Paths.get(tempFile.absolutePath)
            Files.write(path, file) <b>(3)</b>
            HttpResponse.ok("Uploaded")
        } catch (IOException exception) {
            HttpResponse.badRequest("Upload Failed")
        }
    }
}

import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post

import java.io.File
import java.io.IOException
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths

@Controller("/upload")
class BytesUploadController {

    @Post(value = "/bytes",
            consumes = [MediaType.MULTIPART_FORM_DATA],
            produces = [MediaType.TEXT_PLAIN]) <b>(1)</b>
    fun uploadBytes(file: ByteArray, fileName: String): HttpResponse<String> { <b>(2)</b>
        return try {
            val tempFile = File.createTempFile(fileName, "temp")
            val path = Paths.get(tempFile.absolutePath)
            Files.write(path, file) <b>(3)</b>
            HttpResponse.ok("Uploaded")
        } catch (exception: IOException) {
            HttpResponse.badRequest("Upload Failed")
        }

    }
}

import io.micronaut.http.HttpResponse;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.multipart.CompletedFileUpload;

import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

@Controller("/upload")
public class CompletedUploadController {

    @Post(value = "/completed",
            consumes = MediaType.MULTIPART_FORM_DATA,
            produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    public HttpResponse<String> uploadCompleted(CompletedFileUpload file) { <b>(2)</b>
        try {
            File tempFile = File.createTempFile(file.getFilename(), "temp"); <b>(3)</b>
            Path path = Paths.get(tempFile.getAbsolutePath());
            Files.write(path, file.getBytes()); <b>(3)</b>
            return HttpResponse.ok("Uploaded");
        } catch (IOException exception) {
            return HttpResponse.badRequest("Upload Failed");
        }
    }
}

import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.CompletedFileUpload

import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths

@Controller("/upload")
class CompletedUploadController {

    @Post(value = "/completed",
            consumes = MediaType.MULTIPART_FORM_DATA,
            produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    HttpResponse<String> uploadCompleted(CompletedFileUpload file) { <b>(2)</b>
        try {
            File tempFile = File.createTempFile(file.filename, "temp") <b>(3)</b>
            Path path = Paths.get(tempFile.absolutePath)
            Files.write(path, file.bytes) <b>(3)</b>
            HttpResponse.ok("Uploaded")
        } catch (IOException exception) {
            HttpResponse.badRequest("Upload Failed")
        }
    }
}

import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.CompletedFileUpload

import java.io.File
import java.io.IOException
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths

@Controller("/upload")
class CompletedUploadController {

    @Post(value = "/completed",
            consumes = [MediaType.MULTIPART_FORM_DATA],
            produces = [MediaType.TEXT_PLAIN]) <b>(1)</b>
    fun uploadCompleted(file: CompletedFileUpload): HttpResponse<String> { <b>(2)</b>
        return try {
            val tempFile = File.createTempFile(file.filename, "temp") <b>(3)</b>
            val path = Paths.get(tempFile.absolutePath)
            Files.write(path, file.bytes) <b>(3)</b>
            HttpResponse.ok("Uploaded")
        } catch (exception: IOException) {
            HttpResponse.badRequest("Upload Failed")
        }

    }
}

Multiple Uploads

HttpResponse upload(String title, String name)

HttpResponse upload(Publisher<StreamingFileUpload> files)
HttpResponse upload(Publisher<CompletedFileUpload> files)
HttpResponse upload(Publisher<MyObject> files)
HttpResponse upload(Publisher<Publisher<PartData>> files)

Whole Body Binding

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.multipart.CompletedFileUpload;
import io.micronaut.http.multipart.CompletedPart;
import io.micronaut.http.server.multipart.MultipartBody;
import io.reactivex.Single;
import org.reactivestreams.Subscriber;
import org.reactivestreams.Subscription;

@Controller("/upload")
public class WholeBodyUploadController {

    @Post(value = "/whole-body",
            consumes = MediaType.MULTIPART_FORM_DATA,
            produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    public Single<String> uploadBytes(@Body MultipartBody body) { <b>(2)</b>
        return Single.create(emitter -> {
            body.subscribe(new Subscriber<CompletedPart>() {
                private Subscription s;

                @Override
                public void onSubscribe(Subscription s) {
                    this.s = s;
                    s.request(1);
                }

                @Override
                public void onNext(CompletedPart completedPart) {
                    String partName = completedPart.getName();
                    if (completedPart instanceof CompletedFileUpload) {
                        String originalFileName = ((CompletedFileUpload) completedPart).getFilename();
                    }
                }

                @Override
                public void onError(Throwable t) {
                    emitter.onError(t);
                }

                @Override
                public void onComplete() {
                    emitter.onSuccess("Uploaded");
                }
            });
        });
    }
}

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.CompletedFileUpload
import io.micronaut.http.multipart.CompletedPart
import io.micronaut.http.server.multipart.MultipartBody
import io.reactivex.Single
import org.reactivestreams.Subscriber
import org.reactivestreams.Subscription

@Controller("/upload")
class WholeBodyUploadController {

    @Post(value = "/whole-body",
            consumes = MediaType.MULTIPART_FORM_DATA,
            produces = MediaType.TEXT_PLAIN) <b>(1)</b>
    Single<String> uploadBytes(@Body MultipartBody body) { <b>(2)</b>
        Single.<String>create({ emitter ->
            body.subscribe(new Subscriber<CompletedPart>() {
                private Subscription s

                @Override
                void onSubscribe(Subscription s) {
                    this.s = s
                    s.request(1)
                }

                @Override
                void onNext(CompletedPart completedPart) {
                    String partName = completedPart.name
                    if (completedPart instanceof CompletedFileUpload) {
                        String originalFileName = ((CompletedFileUpload) completedPart).filename
                    }
                }

                @Override
                void onError(Throwable t) {
                    emitter.onError(t)
                }

                @Override
                void onComplete() {
                    emitter.onSuccess("Uploaded")
                }
            })
        })
    }
}

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.CompletedFileUpload
import io.micronaut.http.multipart.CompletedPart
import io.micronaut.http.server.multipart.MultipartBody
import io.reactivex.Single
import org.reactivestreams.Subscriber
import org.reactivestreams.Subscription

@Controller("/upload")
class WholeBodyUploadController {

    @Post(value = "/whole-body",
            consumes = [MediaType.MULTIPART_FORM_DATA],
            produces = [MediaType.TEXT_PLAIN]) <b>(1)</b>
    fun uploadBytes(@Body body: MultipartBody): Single<String> { <b>(2)</b>
        return Single.create { emitter ->
            body.subscribe(object : Subscriber<CompletedPart> {
                private var s: Subscription? = null

                override fun onSubscribe(s: Subscription) {
                    this.s = s
                    s.request(1)
                }

                override fun onNext(completedPart: CompletedPart) {
                    val partName = completedPart.name
                    if (completedPart is CompletedFileUpload) {
                        val originalFileName = completedPart.filename
                    }
                }

                override fun onError(t: Throwable) {
                    emitter.onError(t)
                }

                override fun onComplete() {
                    emitter.onSuccess("Uploaded")
                }
            })
        }
    }
}

Sending File Objects

@Get
public SystemFile download() {
    File file = ...
    return new SystemFile(file).attach("myfile.txt");
    // or new SystemFile(file, MediaType.TEXT_HTML_TYPE)
}

Sending an InputStream

@Get
public StreamedFile download() {
    InputStream inputStream = ...
    return new StreamedFile(inputStream, MediaType.TEXT_PLAIN_TYPE)
    // An attach(String filename) method is also available to set the Content-Disposition
}

Cache Configuration

Writing a Filter

import io.micronaut.http.HttpRequest;
import io.reactivex.Flowable;
import io.reactivex.schedulers.Schedulers;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.inject.Singleton;

@Singleton
public class TraceService {

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

    Flowable<Boolean> trace(HttpRequest<?> request) {
        return Flowable.fromCallable(() -> { <b>(1)</b>
            if (LOG.isDebugEnabled()) {
                LOG.debug("Tracing request: " + request.getUri());
            }
            // trace logic here, potentially performing I/O <b>(2)</b>
            return true;
        }).subscribeOn(Schedulers.io()); <b>(3)</b>
    }
}

import io.micronaut.http.HttpRequest
import io.reactivex.Flowable
import io.reactivex.schedulers.Schedulers
import org.slf4j.Logger
import org.slf4j.LoggerFactory

import javax.inject.Singleton

@Singleton
class TraceService {

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

    Flowable<Boolean> trace(HttpRequest<?> request) {
        Flowable.fromCallable({ ->  <b>(1)</b>
            if (LOG.isDebugEnabled()) {
                LOG.debug("Tracing request: " + request.getUri())
            }
            // trace logic here, potentially performing I/O <b>(2)</b>
            return true
        }).subscribeOn(Schedulers.io()) <b>(3)</b>
    }
}

import io.micronaut.http.HttpRequest
import io.reactivex.Flowable
import io.reactivex.schedulers.Schedulers
import org.slf4j.LoggerFactory

import javax.inject.Singleton


@Singleton
class TraceService {

    private val LOG = LoggerFactory.getLogger(TraceService::class.java)

    internal fun trace(request: HttpRequest<*>): Flowable<Boolean> {
        return Flowable.fromCallable {
            <b>(1)</b>
            if (LOG.isDebugEnabled) {
                LOG.debug("Tracing request: " + request.uri)
            }
            // trace logic here, potentially performing I/O <b>(2)</b>
            true
        }.subscribeOn(Schedulers.io()) <b>(3)</b>
    }
}

import io.micronaut.http.*;
import io.micronaut.http.annotation.Filter;
import io.micronaut.http.filter.*;
import org.reactivestreams.Publisher;

@Filter("/hello/**") <b>(1)</b>
public class TraceFilter implements HttpServerFilter { <b>(2)</b>
    private final TraceService traceService;

    public TraceFilter(TraceService traceService) { <b>(3)</b>
        this.traceService = traceService;
    }

}

import io.micronaut.http.HttpRequest
import io.micronaut.http.MutableHttpResponse
import io.micronaut.http.annotation.Filter
import io.micronaut.http.filter.HttpServerFilter
import io.micronaut.http.filter.ServerFilterChain
import org.reactivestreams.Publisher

@Filter("/hello/**") <b>(1)</b>
class TraceFilter implements HttpServerFilter { <b>(2)</b>
    private final TraceService traceService

    TraceFilter(TraceService traceService) { <b>(3)</b>
        this.traceService = traceService
    }

}

import io.micronaut.http.HttpRequest
import io.micronaut.http.MutableHttpResponse
import io.micronaut.http.annotation.Filter
import io.micronaut.http.filter.HttpServerFilter
import io.micronaut.http.filter.ServerFilterChain
import org.reactivestreams.Publisher


@Filter("/hello/**") <b>(1)</b>
class TraceFilter(<b>(2)</b>
        private val traceService: TraceService)<b>(3)</b>
    : HttpServerFilter {

}

@Override
    public Publisher<MutableHttpResponse<?>> doFilter(HttpRequest<?> request, ServerFilterChain chain) {
        return traceService.trace(request) <b>(1)</b>
                           .switchMap(aBoolean -> chain.proceed(request)) <b>(2)</b>
                           .doOnNext(res -> <b>(3)</b>
                                res.getHeaders().add("X-Trace-Enabled", "true")
                           );
    }

@Override
    Publisher<MutableHttpResponse<?>> doFilter(HttpRequest<?> request, ServerFilterChain chain) {
        traceService.trace(request) <b>(1)</b>
                           .switchMap({ aBoolean -> chain.proceed(request) }) <b>(2)</b>
                           .doOnNext({ res -> <b>(3)</b>
                               res.getHeaders().add("X-Trace-Enabled", "true")
                           })
    }

override fun doFilter(request: HttpRequest<*>, chain: ServerFilterChain): Publisher<MutableHttpResponse<*>> {
        return traceService.trace(request) <b>(1)</b>
                .switchMap { aBoolean -> chain.proceed(request) } <b>(2)</b>
                .doOnNext { res ->
                    <b>(3)</b>
                    res.headers.add("X-Trace-Enabled", "true")
                }
    }

Enabling Sessions

implementation("io.micronaut:micronaut-session")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-session</artifactId>
</dependency>

compile "io.micronaut:micronaut-session"
compile "io.micronaut.redis:micronaut-redis-lettuce"

redis:
    uri: redis://localhost:6379
micronaut:
    session:
        http:
            redis:
                enabled: true

Configuring Session Resolution

micronaut:
    session:
        http:
            cookie: false
            header: true

Working with Sessions

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Post;
import io.micronaut.session.Session;
import io.micronaut.session.annotation.SessionValue;

import edu.umd.cs.findbugs.annotations.Nullable;
import javax.validation.constraints.NotBlank;

@Controller("/shopping")
public class ShoppingController {
    private static final String ATTR_CART = "cart"; <b>(1)</b>

    @Post("/cart/{name}")
    Cart addItem(Session session, @NotBlank String name) { <b>(2)</b>
        Cart cart = session.get(ATTR_CART, Cart.class).orElseGet(() -> { <b>(3)</b>
            Cart newCart = new Cart();
            session.put(ATTR_CART, newCart); <b>(4)</b>
            return newCart;
        });
        cart.getItems().add(name);
        return cart;
    }

}

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.session.Session
import io.micronaut.session.annotation.SessionValue

import javax.annotation.Nullable
import javax.validation.constraints.NotBlank

@Controller("/shopping")
class ShoppingController {
    static final String ATTR_CART = "cart" <b>(1)</b>

    @Post("/cart/{name}")
    Cart addItem(Session session, @NotBlank String name) { <b>(2)</b>
        Cart cart = session.get(ATTR_CART, Cart.class).orElseGet({ ->  <b>(3)</b>
            Cart newCart = new Cart()
            session.put(ATTR_CART, newCart) <b>(4)</b>
            newCart
        })
        cart.getItems().add(name)
        cart
    }

}

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.session.Session
import io.micronaut.session.annotation.SessionValue


@Controller("/shopping")
class ShoppingController {

    @Post("/cart/{name}")
    internal fun addItem(session: Session, name: String): Cart { <b>(2)</b>
        require(name.isNotBlank()) { "Name cannot be blank" }
        val cart = session.get(ATTR_CART, Cart::class.java).orElseGet({
            <b>(3)</b>
            val newCart = Cart()
            session.put(ATTR_CART, newCart) <b>(4)</b>
            newCart
        })
        cart.items.add(name)
        return cart
    }

}

@Post("/cart/clear")
    void clearCart(@Nullable Session session) {
        if (session != null) {
            session.remove(ATTR_CART);
        }
    }

@Post("/cart/clear")
    void clearCart(@Nullable Session session) {
        if (session != null) {
            session.remove(ATTR_CART)
        }
    }

@Post("/cart/clear")
    internal fun clearCart(session: Session?) {
        session?.remove(ATTR_CART)
    }

Session Clients

HttpResponse<Cart> response = client.exchange(HttpRequest.GET("/shopping/cart"), Cart.class) <b>(1)</b>
                                                .blockingFirst();
        Cart cart = response.body();

        assertNotNull(response.header(HttpHeaders.AUTHORIZATION_INFO)); <b>(2)</b>
        assertNotNull(cart);
        assertTrue(cart.getItems().isEmpty());

when: "The shopping cart is retrieved"
        HttpResponse<Cart> response = httpClient.exchange(HttpRequest.GET('/shopping/cart'), Cart) <b>(1)</b>
                                                .blockingFirst()
        Cart cart = response.body()

        then: "The shopping cart is present as well as a session id header"
        response.header(HttpHeaders.AUTHORIZATION_INFO) != null <b>(2)</b>
        cart != null
        cart.items.isEmpty()

var response = client.exchange(HttpRequest.GET<Cart>("/shopping/cart"), Cart::class.java) <b>(1)</b>
                    .blockingFirst()
            var cart = response.body()

            assertNotNull(response.header(HttpHeaders.AUTHORIZATION_INFO)) <b>(2)</b>
            assertNotNull(cart)
            cart.items.isEmpty()

String sessionId = response.header(HttpHeaders.AUTHORIZATION_INFO); <b>(1)</b>

        response = client.exchange(
                HttpRequest.POST("/shopping/cart/Apple", "")
                        .header(HttpHeaders.AUTHORIZATION_INFO, sessionId), Cart.class) <b>(2)</b>
                .blockingFirst();
        cart = response.body();

String sessionId = response.header(HttpHeaders.AUTHORIZATION_INFO) <b>(1)</b>

        response = httpClient.exchange(
                HttpRequest.POST('/shopping/cart/Apple', "")
                        .header(HttpHeaders.AUTHORIZATION_INFO, sessionId), Cart) <b>(2)</b>
                .blockingFirst()
        cart = response.body()

val sessionId = response.header(HttpHeaders.AUTHORIZATION_INFO) <b>(1)</b>

            response = client.exchange(
                    HttpRequest.POST("/shopping/cart/Apple", "")
                            .header(HttpHeaders.AUTHORIZATION_INFO, sessionId), Cart::class.java) <b>(2)</b>
                    .blockingFirst()
            cart = response.body()

Using @SessionValue

@Get("/cart")
    @SessionValue(ATTR_CART) <b>(1)</b>
    Cart viewCart(@SessionValue @Nullable Cart cart) { <b>(2)</b>
        if (cart == null) {
            cart = new Cart();
        }
        return cart;
    }

@Get("/cart")
    @SessionValue("cart") <b>(1)</b>
    Cart viewCart(@SessionValue @Nullable Cart cart) { <b>(2)</b>
        if (cart == null) {
            cart = new Cart()
        }
        cart
    }

@Get("/cart")
    @SessionValue(ATTR_CART) <b>(1)</b>
    internal fun viewCart(@SessionValue cart: Cart?): Cart { <b>(2)</b>
        var cart = cart
        if (cart == null) {
            cart = Cart()
        }
        return cart
    }

Session Events

Headline

public class Headline {
    private String title;
    private String description;

    public Headline() { }

    public Headline(String title, String description) {
        this.title = title;
        this.description = description;
    }

    public String getTitle() {
        return title;
    }

    public String getDescription() {
        return description;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public void setDescription(String description) {
        this.description = description;
    }
}

Headline

class Headline {
    String title;
    String description;

    Headline() {}

    Headline(String title, String description) {
        this.title = title;
        this.description = description;
    }
}

Headline

class Headline {
    var title: String? = null
    var description: String? = null

    constructor() {}

    constructor(title: String, description: String) {
        this.title = title
        this.description = description
    }
}

Publishing Server Sent Events from a Controller

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.*;
import io.micronaut.http.sse.Event;
import io.micronaut.scheduling.TaskExecutors;
import io.micronaut.scheduling.annotation.ExecuteOn;
import io.reactivex.Flowable;
import org.reactivestreams.Publisher;

@Controller("/headlines")
public class HeadlineController {

    @ExecuteOn(TaskExecutors.IO)
    @Get(produces = MediaType.TEXT_EVENT_STREAM)
    public Publisher<Event<Headline>> index() { <b>(1)</b>
        String[] versions = new String[]{"1.0", "2.0"}; <b>(2)</b>

        return Flowable.generate(() -> 0, (i, emitter) -> { <b>(3)</b>
            if (i < versions.length) {
                emitter.onNext( <b>(4)</b>
                    Event.of(new Headline("Micronaut " + versions[i] + " Released", "Come and get it"))
                );
            } else {
                emitter.onComplete(); <b>(5)</b>
            }
            return ++i;
        });
    }
}

Publishing Server Sent Events from a Controller

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.sse.Event
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn
import io.reactivex.Emitter
import io.reactivex.Flowable
import io.reactivex.functions.BiFunction
import org.reactivestreams.Publisher


@Controller("/headlines")
class HeadlineController {

    @ExecuteOn(TaskExecutors.IO)
    @Get(produces = MediaType.TEXT_EVENT_STREAM)
    Publisher<Event<Headline>> index() { <b>(1)</b>
        String[] versions = ["1.0", "2.0"] <b>(2)</b>

        def initialState = { -> 0 }
        def emitterFunction = { Integer i, Emitter emitter ->  <b>(3)</b>
            if (i < versions.length) {
                emitter.onNext( <b>(4)</b>
                        Event.of(new Headline("Micronaut " + versions[i] + " Released", "Come and get it"))
                )
            } else {
                emitter.onComplete() <b>(5)</b>
            }
            return ++i
        }

        return Flowable.generate(initialState, emitterFunction as BiFunction<Integer,Emitter<Event<Headline>>,Integer>)
    }
}

Publishing Server Sent Events from a Controller

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.sse.Event
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn
import io.reactivex.Emitter
import io.reactivex.Flowable
import io.reactivex.functions.BiFunction
import org.reactivestreams.Publisher
import java.util.concurrent.Callable


@Controller("/headlines")
class HeadlineController {

    @ExecuteOn(TaskExecutors.IO)
    @Get(produces = [MediaType.TEXT_EVENT_STREAM])
    fun index(): Publisher<Event<Headline>> { <b>(1)</b>
        val versions = arrayOf("1.0", "2.0") <b>(2)</b>

        return Flowable.generate<Event<Headline>, Int>(Callable<Int>{ 0 }, BiFunction { <b>(3)</b>
            i: Int, emitter: Emitter<Event<Headline>> ->
            var nextInt: Int = i
            if (i < versions.size) {
                emitter.onNext( <b>(4)</b>
                        Event.of<Headline>(Headline("Micronaut " + versions[i] + " Released", "Come and get it"))
                )
            } else {
                emitter.onComplete() <b>(5)</b>
            }
            ++nextInt
        })
    }
}

Server Sent Event Response Output

data: {"title":"Micronaut 1.0 Released","description":"Come and get it"}
 data: {"title":"Micronaut 2.0 Released","description":"Come and get it"}

WebSocket Chat Example

import io.micronaut.websocket.WebSocketBroadcaster;
import io.micronaut.websocket.WebSocketSession;
import io.micronaut.websocket.annotation.OnClose;
import io.micronaut.websocket.annotation.OnMessage;
import io.micronaut.websocket.annotation.OnOpen;
import io.micronaut.websocket.annotation.ServerWebSocket;

import java.util.function.Predicate;

@ServerWebSocket("/chat/{topic}/{username}") <b>(1)</b>
public class ChatServerWebSocket {
    private WebSocketBroadcaster broadcaster;

    public ChatServerWebSocket(WebSocketBroadcaster broadcaster) {
        this.broadcaster = broadcaster;
    }

    @OnOpen <b>(2)</b>
    public void onOpen(String topic, String username, WebSocketSession session) {
        String msg = "[" + username + "] Joined!";
        broadcaster.broadcastSync(msg, isValid(topic, session));
    }

    @OnMessage <b>(3)</b>
    public void onMessage(
            String topic,
            String username,
            String message,
            WebSocketSession session) {
        String msg = "[" + username + "] " + message;
        broadcaster.broadcastSync(msg, isValid(topic, session)); <b>(4)</b>
    }

    @OnClose <b>(5)</b>
    public void onClose(
            String topic,
            String username,
            WebSocketSession session) {
        String msg = "[" + username + "] Disconnected!";
        broadcaster.broadcastSync(msg, isValid(topic, session));
    }

    private Predicate<WebSocketSession> isValid(String topic, WebSocketSession session) {
        return s -> s != session && topic.equalsIgnoreCase(s.getUriVariables().get("topic", String.class, null));
    }
}

WebSocket Chat Example

import io.micronaut.websocket.WebSocketBroadcaster
import io.micronaut.websocket.WebSocketSession
import io.micronaut.websocket.annotation.OnClose
import io.micronaut.websocket.annotation.OnMessage
import io.micronaut.websocket.annotation.OnOpen
import io.micronaut.websocket.annotation.ServerWebSocket

import java.util.function.Predicate

@ServerWebSocket("/chat/{topic}/{username}") <b>(1)</b>
class ChatServerWebSocket {
    private WebSocketBroadcaster broadcaster

    ChatServerWebSocket(WebSocketBroadcaster broadcaster) {
        this.broadcaster = broadcaster
    }

    @OnOpen <b>(2)</b>
    void onOpen(String topic, String username, WebSocketSession session) {
        String msg = "[" + username + "] Joined!"
        broadcaster.broadcastSync(msg, isValid(topic, session))
    }

    @OnMessage <b>(3)</b>
     void onMessage(
            String topic,
            String username,
            String message,
            WebSocketSession session) {
        String msg = "[" + username + "] " + message
        broadcaster.broadcastSync(msg, isValid(topic, session)) <b>(4)</b>
    }

    @OnClose <b>(5)</b>
     void onClose(
            String topic,
            String username,
            WebSocketSession session) {
        String msg = "[" + username + "] Disconnected!"
        broadcaster.broadcastSync(msg, isValid(topic, session))
    }

    private Predicate<WebSocketSession> isValid(String topic, WebSocketSession session) {
        return { s -> s != session && topic.equalsIgnoreCase(s.getUriVariables().get("topic", String.class, null)) }
    }
}

WebSocket Chat Example

import io.micronaut.websocket.WebSocketBroadcaster
import io.micronaut.websocket.WebSocketSession
import io.micronaut.websocket.annotation.OnClose
import io.micronaut.websocket.annotation.OnMessage
import io.micronaut.websocket.annotation.OnOpen
import io.micronaut.websocket.annotation.ServerWebSocket

import java.util.function.Predicate

@ServerWebSocket("/chat/{topic}/{username}") <b>(1)</b>
class ChatServerWebSocket(private val broadcaster: WebSocketBroadcaster) {

    @OnOpen <b>(2)</b>
    fun onOpen(topic: String, username: String, session: WebSocketSession) {
        val msg = "[$username] Joined!"
        broadcaster.broadcastSync(msg, isValid(topic, session))
    }

    @OnMessage <b>(3)</b>
    fun onMessage(
            topic: String,
            username: String,
            message: String,
            session: WebSocketSession) {
        val msg = "[$username] $message"
        broadcaster.broadcastSync(msg, isValid(topic, session)) <b>(4)</b>
    }

    @OnClose <b>(5)</b>
    fun onClose(
            topic: String,
            username: String,
            session: WebSocketSession) {
        val msg = "[$username] Disconnected!"
        broadcaster.broadcastSync(msg, isValid(topic, session))
    }

    private fun isValid(topic: String, session: WebSocketSession): Predicate<WebSocketSession> {
        return Predicate<WebSocketSession>{ s -> (s !== session && topic.equals(s.getUriVariables().get("topic", String::class.java, null), ignoreCase = true)) }
    }
}

The @OnClose Method

The@OnClose method can also optionally receive aCloseReason. The @OnClose method is invoked prior to the session closing.

The @OnMessage Method

The@OnMessage method can define a parameter that is the message body. The parameter can be one of the following:

• A Netty WebSocketFrame

• Any Java primitive or simple type (such as String ). In fact any type that can be converted from ByteBuf (you can register additionalTypeConverter beans if you wish to support a custom type).

• A byte[] , a ByteBuf or a Java NIO ByteBuffer .

• A Plain Old Java Object (POJO). In the case of a POJO the POJO will be decoded by default as JSON usingJsonMediaTypeCodec. You can register a custom codec if necessary and define the content type of the handler using the@Consumes annotation.

The @OnError Method

A method annotated with@OnError can be added to implement custom error handling. The @OnError method can optionally define a parameter that receives the exception type that is to be handled. If no @OnError handling is present and a unrecoverable exception occurs the WebSocket is automatically closed.

Non-Blocking Message Handling

The previous example uses the broadcastSync method of theWebSocketBroadcaster interface which blocks until the broadcast is complete. A similar sendSync method exists inWebSocketSession to send a message to a single receiver in a blocking manner. You can however implement non-blocking WebSocket servers by instead returning a Publisher or a Future from each WebSocket handler method. For example:

@OnMessage
    public Publisher<Message> onMessage(
            String topic,
            String username,
            Message message,
            WebSocketSession session) {

        String text = "[" + username + "] " + message.getText();
        Message newMessage = new Message(text);
        return broadcaster.broadcast(newMessage, isValid(topic, session));
    }

@OnMessage
     Publisher<Message> onMessage(
            String topic,
            String username,
            Message message,
            WebSocketSession session) {

        String text = "[" + username + "] " + message.getText()
        Message newMessage = new Message(text)
        broadcaster.broadcast(newMessage, isValid(topic, session))
    }

@OnMessage
    fun onMessage(
            topic: String,
            username: String,
            message: Message,
            session: WebSocketSession): Publisher<Message> {

        val text = "[" + username + "] " + message.text
        val newMessage = Message(text)
        return broadcaster.broadcast(newMessage, isValid(topic, session))
    }

The example above uses broadcast , which creates an instance of Publisher and returns the value to Micronaut. Micronaut will then take care of sending the message asynchronously based on the Publisher interface. The similar send method can be used to send a single message asynchronously via Micronaut return value.

For sending messages asynchronously outside Micronaut annotated handler methods, you can use broadcastAsync and sendAsync methods in their respectiveWebSocketBroadcaster andWebSocketSession interfaces. For blocking sends, the broadcastSync and sendSync methods can be used.

@ServerWebSocket and Scopes

By default a unique @ServerWebSocket instance is created for each WebSocket connection. This allows you to retrieve theWebSocketSession from the @OnOpen handler and assign it to a field of the @ServerWebSocket instance.

If you define the @ServerWebSocket as @Singleton it should be noted that extra care will need to be taken to synchronize local state to avoid thread safety issues.

Sharing Sessions with the HTTP Session

TheWebSocketSession is by default backed by an in-memory map. If you add the the session module you can however sharebetween the HTTP server and the WebSocket server.

$ mn create-websocket-server MyChat
| Rendered template WebsocketServer.java to destination src/main/java/example/MyChatServer.java

Connection Timeouts

By default Micronaut will timeout idle connections that have no activity after 5 minutes. Normally this is not a problem as browsers will automatically reconnect WebSocket sessions, however you can control this behaviour by setting the micronaut.server.idle-timeout setting (a negative value will result no timeout):

micronaut:
    server:
        idle-timeout: 30m # 30 minutes

If you are using Micronaut’s WebSocket client then you may also wish to set the timeout on the client:

micronaut:
    http:
        client:
            read-idle-timeout: 30m # 30 minutes

WebSocket Chat Example

import io.micronaut.http.HttpRequest;
import io.micronaut.websocket.WebSocketSession;
import io.micronaut.websocket.annotation.ClientWebSocket;
import io.micronaut.websocket.annotation.OnMessage;
import io.micronaut.websocket.annotation.OnOpen;
import io.reactivex.Single;

import java.util.Collection;
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.concurrent.Future;


@ClientWebSocket("/chat/{topic}/{username}") <b>(1)</b>
public abstract class ChatClientWebSocket implements AutoCloseable { <b>(2)</b>

    private WebSocketSession session;
    private HttpRequest request;
    private String topic;
    private String username;
    private Collection<String> replies = new ConcurrentLinkedQueue<>();

    @OnOpen
    public void onOpen(String topic, String username, WebSocketSession session, HttpRequest request) { <b>(3)</b>
        this.topic = topic;
        this.username = username;
        this.session = session;
        this.request = request;
    }

    public String getTopic() {
        return topic;
    }

    public String getUsername() {
        return username;
    }

    public Collection<String> getReplies() {
        return replies;
    }

    public WebSocketSession getSession() {
        return session;
    }

    public HttpRequest getRequest() {
        return request;
    }

    @OnMessage
    public void onMessage(
            String message) {
        replies.add(message); <b>(4)</b>
    }

WebSocket Chat Example

import io.micronaut.http.HttpRequest
import io.micronaut.websocket.WebSocketSession
import io.micronaut.websocket.annotation.ClientWebSocket
import io.micronaut.websocket.annotation.OnMessage
import io.micronaut.websocket.annotation.OnOpen
import io.reactivex.Single

import java.util.concurrent.ConcurrentLinkedQueue
import java.util.concurrent.Future


@ClientWebSocket("/chat/{topic}/{username}") <b>(1)</b>
abstract class ChatClientWebSocket implements AutoCloseable { <b>(2)</b>

    private WebSocketSession session
    private HttpRequest request
    private String topic
    private String username
    private Collection<String> replies = new ConcurrentLinkedQueue<>()

    @OnOpen
    void onOpen(String topic, String username, WebSocketSession session, HttpRequest request) { <b>(3)</b>
        this.topic = topic
        this.username = username
        this.session = session
        this.request = request
    }

    String getTopic() {
        topic
    }

    String getUsername() {
        username
    }

    Collection<String> getReplies() {
        replies
    }

    WebSocketSession getSession() {
        session
    }

    HttpRequest getRequest() {
        request
    }

    @OnMessage
    void onMessage(
            String message) {
        replies.add(message) <b>(4)</b>
    }

WebSocket Chat Example

import io.micronaut.http.HttpRequest
import io.micronaut.websocket.WebSocketSession
import io.micronaut.websocket.annotation.ClientWebSocket
import io.micronaut.websocket.annotation.OnMessage
import io.micronaut.websocket.annotation.OnOpen
import io.reactivex.Single
import java.util.concurrent.ConcurrentLinkedQueue
import java.util.concurrent.Future


@ClientWebSocket("/chat/{topic}/{username}") <b>(1)</b>
abstract class ChatClientWebSocket : AutoCloseable { <b>(2)</b>

    var session: WebSocketSession? = null
        private set
    var request: HttpRequest<*>? = null
        private set
    var topic: String? = null
        private set
    var username: String? = null
        private set
    private val replies = ConcurrentLinkedQueue<String>()

    @OnOpen
    fun onOpen(topic: String, username: String, session: WebSocketSession, request: HttpRequest<*>) { <b>(3)</b>
        this.topic = topic
        this.username = username
        this.session = session
        this.request = request
    }

    fun getReplies(): Collection<String> {
        return replies
    }

    @OnMessage
    fun onMessage(
            message: String) {
        replies.add(message) <b>(4)</b>
    }

WebSocket Send Methods

public abstract void send(String message);

WebSocket Send Methods

public abstract io.reactivex.Single<String> send(String message);

WebSocket Send Methods

public abstract java.util.concurrent.Future<String> sendAsync(String message);

Connecting a Client WebSocket

ChatClientWebSocket chatClient = webSocketClient.connect(ChatClientWebSocket.class, "/chat/football/fred").blockingFirst();
chatClient.send("Hello World!");

Configuring the Server for HTTP/2

The first step to doing so is setting the supported HTTP version is the server configuration:

micronaut:
  server:
      http-version: 2.0

With this configuration in place Micronaut will enable support for the h2c protocol (see HTTP/2 over cleartext ) which is fine for development.

Since browsers don’t support h2c and in general HTTP/2 over TLS (the h2 protocol) is recommended for production you should enablesupport. For development this can be done with:

micronaut:
  ssl:
      enabled: true
      buildSelfSigned: true
  server:
      http-version: 2.0

For production, see thesection of the documentation.

Note that if you deployment environment is JDK 8 or if you wish for improved support for OpenSSL you will need to define the following dependencies on Netty Tomcat Native:

runtimeOnly("io.netty:netty-tcnative:2.0.29.Final")

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-tcnative</artifactId>
    <version>2.0.29.Final</version>
    <scope>runtime</scope>
</dependency>

runtimeOnly("io.netty:netty-tcnative-boringssl-static:2.0.29.Final")

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-tcnative-boringssl-static</artifactId>
    <version>2.0.29.Final</version>
    <scope>runtime</scope>
</dependency>

In addition to a dependency on the appropriate native library for your architecture. For example:

runtimeOnly "io.netty:netty-tcnative-boringssl-static:2.0.29.Final:${Os.isFamily(Os.FAMILY_MAC) ? 'osx-x86_64' : 'linux-x86_64'}"

See the documentation on Tomcat Native for more information.

HTTP/2 Clients

By default Micronaut’s HTTP client is configured to support HTTP 1.1. To enable support for HTTP/2 you can do so globally by setting the supported HTTP version if configuration:

micronaut:
    http:
        client:
            http-version: 2.0

Or by specifying the HTTP version to use when injecting the client:

@Inject
@Client(httpVersion=HttpVersion.HTTP_2_0)
RxHttpClient client;

Listening for Server Startup Events

import io.micronaut.context.event.ApplicationEventListener;
...
@Singleton
public class StartupListener implements ApplicationEventListener<ServerStartupEvent> {
    @Override
    public void onApplicationEvent(ServerStartupEvent event) {
        // logic here
        ...
    }
}

import io.micronaut.runtime.server.event.*;
import io.micronaut.runtime.event.annotation.*;
...
@Singleton
public class MyBean {

    @EventListener
    public void onStartup(ServerStartupEvent event) {
        // logic here
        ...
    }
}

Configuring HTTP server settings

micronaut:
    server:
        maxRequestSize: 1MB
        host: localhost <i data-value="1"></i><b>(1)</b>
        netty:
           maxHeaderSize: 500KB <i data-value="2"></i><b>(2)</b>
           worker:
              threads: 8 <i data-value="3"></i><b>(3)</b>
           childOptions:
              autoRead: true <i data-value="4"></i><b>(4)</b>

Using Native Transports

The native Netty transports add features specific to a particular platform, generate less garbage, and generally improve performance when compared to the NIO based transport.

To enable native transports first add a necessarily dependency:

For macOS:

runtime("io.netty:netty-transport-native-kqueue:osx-x86_64")

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-kqueue</artifactId>
    <scope>runtime</scope>
    <classifier>osx-x86_64</classifier>
</dependency>

For Linux:

runtime("io.netty:netty-transport-native-epoll:linux-x86_64")

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-epoll</artifactId>
    <scope>runtime</scope>
    <classifier>linux-x86_64</classifier>
</dependency>

Then configure the default event loop group to prefer native transports:

micronaut:
    netty:
        event-loops:
            default:
                prefer-native-transport: true