import io.micronaut.core.annotation.Creator;
@io.micronaut.core.annotation.Introspected
interface Example {
String getName();
@Creator
static Example create(String name) {
return () -> name;
}
}
Table of Contents
Micronaut
Natively Cloud Native
Version:
1 Introduction
Micronaut is a modern, JVM-based, full stack Java framework designed for building modular, easily testable JVM applications with support for Java, Kotlin and the Groovy language.
Micronaut is developed by the creators of the Grails framework and takes inspiration from lessons learnt over the years building real-world applications from monoliths to microservices using Spring, Spring Boot and Grails.
Micronaut aims to provide all the tools necessary to build JVM applications including:
-
Dependency Injection and Inversion of Control (IoC)
-
Aspect Oriented Programming (AOP)
-
Sensible Defaults and Auto-Configuration
With Micronaut you can build Message-Driven Applications, Command Line Applications, HTTP Servers and more whilst for Microservices in particular Micronaut also provides:
-
Distributed Configuration
-
Service Discovery
-
HTTP Routing
-
Client-Side Load Balancing
At the same time Micronaut aims to avoid the downsides of frameworks like Spring, Spring Boot and Grails by providing:
-
Fast startup time
-
Reduced memory footprint
-
Minimal use of reflection
-
Minimal use of proxies
-
No runtime bytecode generation
-
Easy Unit Testing
Historically, frameworks such as Spring and Grails were not designed to run in scenarios such as server-less functions, Android apps, or low memory-footprint microservices. In contrast, Micronaut is designed to be suitable for all of these scenarios.
This goal is achieved through the use of Java’s annotation processors, which are usable on any JVM language that supports them, as well as an HTTP Server and Client built on Netty. In order to provide a similar programming model to Spring and Grails, these annotation processors precompile the necessary metadata in order to perform DI, define AOP proxies and configure your application to run in a low-memory environment.
Many of the APIs within Micronaut are heavily inspired by Spring and Grails. This is by design, and aids in bringing developers up to speed quickly.
1.1 What's New?
Micronaut 2.0.3 includes the following changes:
Core Features
Support for JDK 14
Micronaut has been updated to support JDK 14.
Groovy 3
Micronaut now supports applications written in Groovy 3.
Startup Performance Improvements
Startup time has been further improved in this release with typical startup time for a new application around 20% faster.
Improvements to Bean Introspections
Bean introspections have been improved to support static creator methods, interfaces and enums. This means you can define a bean introspection on an interface with a private implementation such as:
Support for Analyzing the Injection Point
Micronaut’s Dependency Injection implementation has been improved such that you can now receive an InjectionPoint instance to any @Factory method. This makes it possible to customize how the bean is created based on the annotation metadata at the point at which the bean is injected.
For example consider the following definition:
@Inject @Client("http://foo.com") RxHttpClient client;
A factory method can receive the injection point and create a client based off of the value:
@Bean
protected DefaultHttpClient httpClient(InjectionPoint<?> injectionPoint) {
String url = metadata.stringValue(Client.class).orElse(null);
if (url != null) {
......
URL parsedUrl = new URL(url) //handle exception
return new DefaultHttpClient(parsedUrl);
} else {
return new DefaultHttpClient();
}
}
Support for Eager Initialization of Beans
Eager initialization of beans is useful in certain cases, such as on AWS Lambda where more CPU resources are assigned to Lamdba construction than execution. Therefore as for Micronaut 2.0, you can specify whether you want to eager initialization configuration or all singletons using the ApplicationContextBuilder interface:
public class Application {
public static void main(String[] args) {
Micronaut.build(args)
.eagerInitSingletons(true) (1)
.mainClass(Application.class)
.start();
}
}
1 | Setting eager init to true initializes all singletons |
It is also possible to just eager init configuration using eagerInitConfiguration
which will initialize all @ConfigurationProperties beans.
Spot Bugs Instead of JSR-305 Nullable/NonNull Annotations
In Micronaut 1.x the Google distributed JSR-305 annotations library (com.google.code.findbugs:jsr305
) was used to specify @Nullable
and @NonNull
on interfaces of the Micronaut API using the annotations contained within the javax.annotation
package.
Due to the fact that JSR-305 has been cancelled and that this dependency has potential licensing issues (by using the javax
namespace) as well as problems with the cross packages on Java 9+ with the module system Micronaut 2.x switches to the spotbugs-annotations
module provided by the SpotBugs project.
It is recommended users of Micronaut use this API instead (although the javax.annotation.Nullable
and javax.annotation.NotNull
annotations continue to be supported).
CLI Features
New Native CLI
Micronaut’s mn
command for the CLI has been rewritten in Micronaut itself and is now compiled into a native image available on Linux, MacOS X and Windows.
Micronaut Launch
Create Micronaut 2.0 applications without having the CLI installed using curl
:
$ curl https://launch.micronaut.io/demo.zip -o demo.zip
$ unzip demo.zip -d demo
Or by visiting https://launch.micronaut.io in your browser.
Run curl https://launch.micronaut.io
for more instructions on how to use the API or visit the OpenAPI documentation.
Diff Command
Run mn feature-diff --features=[FEATURE NAME]
from the root of another Micronaut project to create a diff of the changes that need to be applied to enable the feature. For example:
feature-diff
$ 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.
Automatic Static Resource Detection for Native Image
It is not longer necessary to configure static resources for your Native Image builds. The micronaut-graal
annotation processor will automatically do this for you for all resources found in src/main/resources
.
Improved support for JDBC / Hibernate in Native Image
It is no longer necessary to provide additional GraalVM related configuration to connect to databases via JDBC or Hibernate/JPA. Micronaut includes automatic support for the following drivers with GraalVM Native Image:
-
Oracle
-
MariaDB
-
Postgres
-
MS SQL
-
H2
-
MySQL
Support for Flyway Migrations in Native Image
The Micronaut Flyway module has been updated with GraalVM Native Image support so you can now run database migrations in Native Image.
Support for Native Image in AWS SDK v2
Version 2.0 of the Micronaut AWS module includes support for Native Image for the majority of the v2 AWS APIs including S3, Dynamo DB, SES, SNS, and SQS which will be helpful for those developing native AWS Lambda functions with Micronaut + GraalVM.
Support for jOOQ in Native Image
The Micronaut jOOQ module includes support for Native Image and it’s possible to use it with SimpleFlatMapper.
Support for Redis in Native Image
The Micronaut Redis module includes support for Native Image. There are still some pending uses cases that won’t work because of how Lettuce driver works. Make sure you read the documentation.
Support for Elasticsearch in Native Image
The Micronaut Elasticsearch module includes support for Native Image
Build Improvements
New Maven Parent POM
Micronaut now provides a new parent POM that can be used in Maven projects to get setup quickly:
<parent>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-parent</artifactId>
<version>${micronaut.version}</version>
</parent>
New Maven Plugin
The parent POM mentioned above includes a new Micronaut Maven Plugin that enables automatic application restart during development. Just run the following:
$ ./mvnw mn:run
Whenever you make a change to a class file the server will restart automatically.
Gradle 6.5 Update
For Gradle users who create new applications Gradle 6.5 is used which is compatible with JDK 14.
Better Gradle Incremental Annotation Processing Support
Gradle builds with Micronaut 2 for both Java and Kotlin should be significantly faster thanks to improved support for Gradle incremental annotation processing.
HTTP Features
Support for HTTP/2
Micronaut’s Netty-based HTTP client and server have been updated to support HTTP/2.
See the HTTP/2 documentation for more information on how to enable support for HTTP/2.
Threading Model and Event Loop Group Improvements
Micronaut 2.0 uses a new shared default Netty EventLoopGroup
for server worker threads and client request threads. This reduces context switching and improves resource utilization.
See the HTTP Client Configuration section for information on how to configure the default EventLoopGroup
and add additional `EventLoopGroup’s that are configured per client.
In addition, as of Micronaut 2.0 all operations are by default executed on the EventLoop
and users can optionally use the new @ExecuteOn annotation to specify a named executor to execute an operation on if required (for example to offload blocking operations such as interactions with JPA/JDBC to a specific thread pool).
Support for @RequestBean
It is now possible to bind the properties of a POJO argument to a @Controller
to request parameters, headers and so on using the @RequestBean annotation.
Thanks to Github user asodja for this contribution.
Micronaut Servlet
Micronaut now includes support for creating Servlet applications and users can use the command line to create an application that targets popular Servlet containers:
$ 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
Improved Support for Server-Side Content Negotiation
Micronaut will now correctly handle the HTTP Accept
header and pick the most appropriate route for the specified accepted media types using Server-Side Content Negotiation.
This also applies to @Error routes making it possible to send different error responses for different content types
|
To add XML support use the Jackson XML module |
Improved Support for Cloud Foundry
Micronaut will now process the VCAP_APPLICATION
and VCAP_SERVICES
environment variables and treat them as property sources.
Thanks to Fabian Nonnenmacher for this contribution.
HTTP Client Improvements
It is no longer necessary to use @Client(..)
to inject a default RxHttpClient instance. You can now inject the default client simply with:
@Inject RxHttpClient client;
If no host is provided at the time of a request, a NoHostException will be thrown.
API for Proxying Requests
A new API for writing API gateways and proxying requests has been added. See the documentation on the ProxyHttpClient for more information.
Endpoint Sensitivity
It is now possible to control the sensitivity of individual endpoint methods. The @Sensitive annotation can be applied to endpoint methods to allow for some methods to have a different sensitivity than the value supplied to the endpoint annotation.
Improvements to Instrumentation
The Instrumentation mechanism for RxJava 2 has been improved to address issues with MDC and reduce the size of reactive stack traces. Thanks to Denis Stepanov and Lajos Gathy for their contributions in this area.
Kotlin Improvements
Support for KTOR in Micronaut Launch
You can generate a Micronaut + Ktor application from Micronaut Launch or via the command line.
Micronaut Kotlin Extensions
New Kotlin Extension Functions are available that make the Kotlin + Micronaut experience that little bit better.
Serverless Improvements
Support for Google Cloud Function
You can now write Serverless functions that target Google Cloud Function using Micronaut. See the Micronaut GCP documentation and example application for more information.
Support for Microsoft Azure Function
You can now write Serverless functions that target Microsoft Azure using Micronaut. See the Micronaut Azure documentation and example application for more information.
Improvements to Micronaut AWS
Micronaut AWS 2.0.0 includes a number of improvements to support for AWS Lambda and AWS in general including new client modules for AWS SDK 2.0, cold start improvements on Lambda and improvements to the support for Amazon Alexa.
Module Improvements
Micronaut is more modular than ever, with several components now available in separate modules and upgrades to those modules.
Micronaut Cache 2.0.0 Upgrade
Caching has been moved into a separate module and out of micronaut-runtime
. If you need caching (including the annotations within io.micronaut.cache.annotation
) you just need to add the individual module for the cache provider you are interested (for example Caffeine, Redis, Hazelcast etc.).
See the documentation for the Cache module for more information.
Micronaut SQL 2.3.0 Upgrade
Micronaut SQL has been improved to default to Micronaut transaction management (making Spring management optional) and includes support for Jdbi (Thanks to Dan Maas for this contribution).
In addition, support has been added for Oracle Universal Connection Pool. Thanks to Todd Sharp for this contribution.
Micronaut Security 2.0.0 Upgrade
The security module has seen many changes to improve the API and introduce new features to support a wider array of use cases.
See the Security module for more information.
New Reactive Modules
Whilst RxJava 2 remains the default, individual modules for other reactive libraries have been added.
For RxJava 3:
implementation("io.micronaut.rxjava3:micronaut-rxjava3")
<dependency>
<groupId>io.micronaut.rxjava3</groupId>
<artifactId>micronaut-rxjava3</artifactId>
</dependency>
For Reactor:
implementation("io.micronaut.reactor:micronaut-reactor")
<dependency>
<groupId>io.micronaut.reactor</groupId>
<artifactId>micronaut-reactor</artifactId>
</dependency>
And legacy support for RxJava 1:
implementation("io.micronaut.rxjava1:micronaut-rxjava1")
<dependency>
<groupId>io.micronaut.rxjava1</groupId>
<artifactId>micronaut-rxjava1</artifactId>
</dependency>
Included within the new RxJava 3 and Reactor modules are variants of RxHttpClient called Rx3HttpClient
and ReactorHttpClient
respectively.
To use the RxJava 3 HTTP client add the following dependency:
implementation("io.micronaut.rxjava3:micronaut-rxjava3-http-client")
<dependency>
<groupId>io.micronaut.rxjava3</groupId>
<artifactId>micronaut-rxjava3-http-client</artifactId>
</dependency>
To use the Reactor HTTP client add:
implementation("io.micronaut.rxjava3:micronaut-reactor-http-client")
<dependency>
<groupId>io.micronaut.rxjava3</groupId>
<artifactId>micronaut-reactor-http-client</artifactId>
</dependency>
New Micronaut NATS module
A new messaging module for Nats.io has been included in Micronaut core.
See the documentation for Micronaut Nats for more information.
Thanks to Joachim Grimm for this contribution.
Module Upgrades
-
Micronaut AWS -
1.3.9
→2.0.0.RC1
-
Micronaut Cache -
1.2.0
→2.0.0.RC1
-
Micronaut Data -
1.0.2
→1.1.0.RC2
-
Micronaut GCP -
1.1.0
→2.0.0.RC2
-
Micronaut gRPC -
1.1.1
→2.0.0.RC1
-
Micronaut Micrometer -
1.3.1
→2.0.0.RC2
-
Micronaut Mongo -
1.3.0
→2.1.0
-
Micronaut Neo4j -
1.3.0
→3.0.0.RC1
-
Micronaut SQL -
1.3.0
→2.3.0
-
Micronaut Security -
1.4.0
→2.0.0.RC1
-
Micronaut Spring -
1.0.2
→2.0.1
Dependency Upgrades
-
Hibernate
5.4.10.Final
→5.4.16.Final
-
Groovy
2.5.8
→3.0.3
-
Mongo Reactive Streams
1.13.0
→4.0.2
-
Mongo Java Driver
3.12.0
→4.0.2
-
Jaeger
1.0.0
→1.2.0
-
Jackson
2.10.3
→2.11.0
1.2 Upgrading to Micronaut 2.x
This section covers the steps required to upgrade a Micronaut 1.x application to Micronaut 2.x.
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) (1)
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) (1)
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) (1)
fun byName(name: String): Person {
return personService.findByName(name)
}
}
1 | The @ExecuteOn annotation is used to execute the operation on the I/O thread pool |
If you wish to return to the previous behaviour as defined in Micronaut 1.x you can set micronaut.server.thread-selection to AUTO in configuration.
|
Thread Factory instrumentation and context propagation
Prior to 2.0 Micronaut had all java.util.concurrent.ThreadFactory
intercepted to allow propagating context. That didn’t work well in cases where threads are long-running causing the instrumentation to leak the context.
It’s recommended to use @Named(TaskExecutors.IO) ExecutorService executorService
which supports context propagation.
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 your 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:
Previous ID | New ID |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
Package | New Dependency |
---|---|
|
|
|
|
|
|
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.
Some features of Micronaut 2 for Groovy users are currently in preview status including GORM 7.1 and Spock 2 support as these frameworks do not yet have stable releases. |
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 on Breaking Changes for a list of other changes that are regarded as breaking in this release.
2 Quick Start
The following sections will walk you through a Quick start on how to use Micronaut to setup a basic "Hello World" application.
Before getting started ensure you have a Java 8 or above SDK installed and it is recommended having a suitable IDE such as IntelliJ IDEA.
To follow the Quick Start it is also recommended that you have the Micronaut CLI installed.
2.1 Build/Install the CLI
The best way to install Micronaut on Unix systems is with SDKMAN which greatly simplifies installing and managing multiple Micronaut versions.
To see all the available installation methods, check the Micronaut Starter documentation.
2.2 Creating a Server Application
Although not required to use Micronaut, the Micronaut CLI is the quickest way to create a new server application.
Using the CLI you can create a new Micronaut application in either Groovy, Java or Kotlin (the default is Java).
The following command creates a new "Hello World" server application in Java with a Gradle build:
The applications generated via our CLI come with Gradle or Maven wrappers, so its not even necessary to have Gradle or Maven installed on your machine to begin running the applications. Simply use the mvnw or gradlew command, as explained further below.
|
$ mn create-app hello-world
You can supply --build maven if you wish to create a Maven based build instead
|
The previous command will create a new Java application in a directory called hello-world
featuring a Gradle build. The application can be run with ./gradlew run
:
$ ./gradlew run
> Task :run
[main] INFO io.micronaut.runtime.Micronaut - Startup completed in 972ms. Server Running: http://localhost:28933
If you have created a Maven based project, use ./mvnw mn:run
instead.
For Windows the ./ before commands is not needed |
By default the Micronaut HTTP server is configured to run on port 8080. See the section Running Server on a Specific Port in the user guide for more options.
In order to create a service that responds to "Hello World" you first need a controller. The following is an example of a controller:
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
@Controller("/hello") (1)
public class HelloController {
@Get(produces = MediaType.TEXT_PLAIN) (2)
public String index() {
return "Hello World"; (3)
}
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
@Controller('/hello') (1)
class HelloController {
@Get(produces = MediaType.TEXT_PLAIN) (2)
String index() {
'Hello World' (3)
}
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
@Controller("/hello") (1)
class HelloController {
@Get(produces = [MediaType.TEXT_PLAIN]) (2)
fun index(): String {
return "Hello World" (3)
}
}
1 | The class is defined as a controller with the @Controller annotation mapped to the path /hello |
2 | The @Get annotation is used to map the index method to all requests that use an HTTP GET |
3 | A String "Hello World" is returned as the result |
If you are using Java, place the previous file in src/main/java/hello/world
.
If you are using Groovy, place the previous file in src/main/groovy/hello/world
.
If you are using Kotlin, place the previous file in src/main/kotlin/hello/world
.
If you start the application and send a request to the /hello
URI then the text "Hello World" is returned:
$ curl http://localhost:8080/hello
Hello World
2.3 Setting up an IDE
The application created in the previous section contains a "main class" located in src/main/java
that looks like the following:
import io.micronaut.runtime.Micronaut;
public class Application {
public static void main(String[] args) {
Micronaut.run(Application.class);
}
}
import io.micronaut.runtime.Micronaut
class Application {
static void main(String... args) {
Micronaut.run Application.class
}
}
import io.micronaut.runtime.Micronaut
object Application {
@JvmStatic
fun main(args: Array<String>) {
Micronaut.run(Application.javaClass)
}
}
This is the class that is run when running the application via Gradle or via deployment. You can also run the main class directly within your IDE if it is configured correctly.
2.3.1 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.
2.3.2 Eclipse
If you wish to use Eclipse IDE, it is recommended you import your Micronaut project into Eclipse using either Gradle BuildShip for Gradle or M2Eclipse for Maven.
Micronaut requires Eclipse IDE 4.9 or above |
Eclipse and Gradle
Once you have setup Eclipse 4.9 or above with Gradle BuildShip first run the gradle eclipse
task from the root of your project then import the project by selecting File → Import
then choosing Gradle → Existing Gradle Project
and navigating to the root directory of your project (where the build.gradle
is located).
Eclipse and Maven
For Eclipse 4.9 and above with Maven you need the following Eclipse plugins:
Once installed you need to import the project by selecting File → Import
then choosing Maven → Existing Maven Project
and navigating to the root directory of your project (where the pom.xml
is located).
You should then enable annotation processing by opening Eclipse → Preferences
and navigating to Maven → Annotation Processing
and selecting the option Automatically configure JDT APT
.
2.3.3 Visual Studio Code
Micronaut can be setup within Visual Studio Code. You will need to first install the The Java Extension Pack.
You can also optionally install STS to enable code completion for application.yml .
|
If you are using Gradle prior to opening the project in VSC you should run the following command from a terminal window:
./gradlew eclipse
Once the extension pack is installed and if you have setup terminal integration just type code .
in any project directory and the project will be automatically setup.
2.4 Creating a Client
As mentioned previously, Micronaut includes both an HTTP server and an HTTP client. A low-level HTTP client is provided out of the box which you can use to test the HelloController
created in the previous section.
import io.micronaut.context.annotation.Property;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.runtime.server.EmbeddedServer;
import io.micronaut.test.annotation.MicronautTest;
import org.junit.jupiter.api.Test;
import javax.inject.Inject;
import static org.junit.jupiter.api.Assertions.assertEquals;
@MicronautTest
public class HelloControllerSpec {
@Inject
EmbeddedServer server; (1)
@Inject
@Client("/")
HttpClient client; (2)
@Test
void testHelloWorldResponse() {
String response = client.toBlocking() (3)
.retrieve(HttpRequest.GET("/hello"));
assertEquals("Hello World", response); //) (4)
}
}
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.runtime.server.EmbeddedServer
import io.micronaut.test.annotation.MicronautTest
import spock.lang.Specification
import javax.inject.Inject
@MicronautTest
class HelloControllerSpec extends Specification {
@Inject
EmbeddedServer embeddedServer (1)
@Inject
@Client("/")
HttpClient client (2)
void "test hello world response"() {
expect:
client.toBlocking() (3)
.retrieve(HttpRequest.GET('/hello')) == "Hello World" (4)
}
}
import io.micronaut.context.annotation.Property
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.runtime.server.EmbeddedServer
import io.micronaut.test.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Test
import javax.inject.Inject
@MicronautTest
class HelloControllerSpec {
@Inject
lateinit var server: EmbeddedServer (1)
@Inject
@field:Client("/")
lateinit var client: HttpClient (2)
@Test
fun testHelloWorldResponse() {
val rsp: String = client.toBlocking() (3)
.retrieve("/hello")
assertEquals("Hello World", rsp) (4)
}
}
1 | The EmbeddedServer is configured as a shared test field |
2 | A HttpClient instance shared field is also defined |
3 | The test using the toBlocking() method to make a blocking call |
4 | The retrieve method returns the response of the controller as a String |
In addition to a low-level client, Micronaut features a declarative, compile-time HTTP client, powered by the Client annotation.
To create a client, simply create an interface annotated with @Client
. For example:
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.client.annotation.Client;
import io.reactivex.Single;
@Client("/hello") (1)
public interface HelloClient {
@Get(consumes = MediaType.TEXT_PLAIN) (2)
Single<String> hello(); (3)
}
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import io.reactivex.Single
@Client("/hello") (1)
interface HelloClient {
@Get(consumes = MediaType.TEXT_PLAIN) (2)
Single<String> hello() (3)
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import io.reactivex.Single
@Client("/hello") (1)
interface HelloClient {
@Get(consumes = [MediaType.TEXT_PLAIN]) (2)
fun hello(): Single<String> (3)
}
1 | The @Client annotation is used with value that is a relative path to the current server |
2 | The same @Get annotation used on the server is used to define the client mapping |
3 | A RxJava Single is returned with the value read from the server |
To test the HelloClient
simply retrieve it from the ApplicationContext associated with the server:
import io.micronaut.test.annotation.MicronautTest;
import javax.inject.Inject;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
@MicronautTest (1)
public class HelloClientSpec {
@Inject
HelloClient client; (2)
@Test
public void testHelloWorldResponse(){
assertEquals("Hello World", client.hello().blockingGet());(3)
}
}
import io.micronaut.test.annotation.MicronautTest
import spock.lang.Specification
import javax.inject.Inject
@MicronautTest (1)
class HelloClientSpec extends Specification {
@Inject HelloClient client (2)
void "test hello world response"() {
expect:
client.hello().blockingGet() == "Hello World" (3)
}
}
import io.micronaut.context.annotation.Property
import io.micronaut.test.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Test
import javax.inject.Inject
@MicronautTest (1)
class HelloClientSpec {
@Inject
lateinit var client: HelloClient (2)
@Test
fun testHelloWorldResponse() {
assertEquals("Hello World", client.hello().blockingGet())(3)
}
}
1 | The @MicronautTest annotation is used to define the test |
2 | The HelloClient is injected from the ApplicationContext |
3 | The client is invoked using RxJava’s blockingGet method |
The Client annotation produces an implementation automatically for you at compile time without the need to use proxies or runtime reflection.
The Client annotation is very flexible. See the section on the Micronaut HTTP Client for more information.
2.5 Deploying the Application
To deploy a Micronaut application you create a runnable JAR file by running ./gradlew assemble
or ./mvnw package
.
The constructed JAR file can then be executed with java -jar
. For example:
$ java -jar build/libs/hello-world-all.jar
The runnable JAR can also easily be packaged within a Docker container or deployed to any Cloud infrastructure that supports runnable JAR files.
3 Inversion of Control
When most developers think of Inversion of Control (also known as Dependency Injection and referred to as such from this point onwards) the Spring Framework comes to mind.
Micronaut takes inspiration from Spring, and in fact, the core developers of Micronaut are former SpringSource/Pivotal engineers now working for OCI.
Unlike Spring which relies exclusively on runtime reflection and proxies, Micronaut uses compile time data to implement dependency injection.
This is a similar approach taken by tools such as Google’s Dagger, which is designed primarily with Android in mind. Micronaut, on the other hand, is designed for building server-side microservices and provides many of the same tools and utilities as Spring but without using reflection or caching excessive amounts of reflection metadata.
The goals of the Micronaut IoC container are summarized as:
-
Use reflection as a last resort
-
Avoid proxies
-
Optimize start-up time
-
Reduce memory footprint
-
Provide clear, understandable error handling
Note that the IoC part of Micronaut can be used completely independently of Micronaut itself for whatever application type you may wish to build. To do so all you need to do is configure your build appropriately to include the micronaut-inject-java
dependency as an annotation processor. For example with Gradle:
plugins {
id "com.diffplug.eclipse.apt" version "3.22.0" // <1>
}
...
dependencies {
annotationProcessor("io.micronaut:micronaut-inject-java:2.0.3") // <2>
implementation("io.micronaut:micronaut-inject:2.0.3")
...
testAnnotationProcessor("io.micronaut:micronaut-inject-java:2.0.3") // <3>
...
}
1 | Apply com.diffplug.eclipse.apt Gradle plugin which modifes Eclipse projects to include gradle annotationProcessor dependencies |
2 | Include the minimal dependencies required to perform dependency injection |
3 | This is necessary to create beans in the test directory |
For the Groovy language you should include micronaut-inject-groovy in the compileOnly and testCompileOnly scopes.
|
The entry point for IoC is then the ApplicationContext interface, which includes a run
method. The following example demonstrates using it:
ApplicationContext
try (ApplicationContext context = ApplicationContext.run()) { (1)
MyBean myBean = context.getBean(MyBean.class); (2)
// do something with your bean
}
1 | Run the ApplicationContext |
2 | Retrieve a bean that has been dependency injected |
The example uses Java’s try-with-resources syntax to ensure the ApplicationContext is cleanly shutdown when the application exits. |
3.1 Defining Beans
A bean is an object that has its lifecycle controlled by the Micronaut IoC container. That lifecycle may include creation, execution, and destruction. Micronaut implements the JSR-330 (javax.inject) - Dependency Injection for Java specification hence to use Micronaut you simply use the annotations provided by javax.inject.
The following is a simple example:
public interface Engine { (1)
int getCylinders();
String start();
}
@Singleton(2)
public class V8Engine implements Engine {
@Override
public String start() {
return "Starting V8";
}
@Override
public int getCylinders() {
return cylinders;
}
public void setCylinders(int cylinders) {
this.cylinders = cylinders;
}
private int cylinders = 8;
}
@Singleton
public class Vehicle {
private final Engine engine;
public Vehicle(Engine engine) {(3)
this.engine = engine;
}
public String start() {
return engine.start();
}
}
interface Engine { (1)
int getCylinders()
String start()
}
@Singleton (2)
class V8Engine implements Engine {
int cylinders = 8
@Override
String start() {
"Starting V8"
}
}
@Singleton
class Vehicle {
final Engine engine
Vehicle(Engine engine) { (3)
this.engine = engine
}
String start() {
engine.start()
}
}
interface Engine {
(1)
val cylinders: Int
fun start(): String
}
@Singleton(2)
class V8Engine : Engine {
override var cylinders = 8
override fun start(): String {
return "Starting V8"
}
}
@Singleton
class Vehicle(private val engine: Engine)(3)
{
fun start(): String {
return engine.start()
}
}
1 | A common Engine interface is defined |
2 | A V8Engine implementation is defined and marked with Singleton scope |
3 | The Engine is injected via constructor injection |
To perform dependency injection simply run the BeanContext using the run()
method and lookup a bean using getBean(Class)
, as per the following example:
final BeanContext context = BeanContext.run();
Vehicle vehicle = context.getBean(Vehicle.class);
System.out.println(vehicle.start());
def context = BeanContext.run()
Vehicle vehicle = context.getBean(Vehicle)
println( vehicle.start() )
val context = BeanContext.run()
val vehicle = context.getBean(Vehicle::class.java)
println(vehicle.start())
Micronaut will automatically discover dependency injection metadata on the classpath and wire the beans together according to injection points you define.
Micronaut supports the following types of dependency injection:
-
Constructor injection (must be one public constructor or a single contructor annotated with
@Inject
) -
Field injection
-
JavaBean property injection
-
Method parameter injection
3.2 How Does it Work?
At this point, you may be wondering how Micronaut performs the above dependency injection without requiring reflection.
The key is a set of AST transformations (for Groovy) and annotation processors (for Java) that generate classes that implement the BeanDefinition interface.
The ASM byte-code library is used to generate classes and because Micronaut knows ahead of time the injection points, there is no need to scan all of the methods, fields, constructors, etc. at runtime like other frameworks such as Spring do.
Also since reflection is not used in the construction of the bean, the JVM can inline and optimize the code far better resulting in better runtime performance and reduced memory consumption. This is particularly important for non-singleton scopes where the application performance depends on bean creation performance.
In addition, with Micronaut your application startup time and memory consumption is not bound to the size of your codebase in the same way as a framework that uses reflection. Reflection based IoC frameworks load and cache reflection data for every single field, method, and constructor in your code. Thus as your code grows in size so do your memory requirements, whilst with Micronaut this is not the case.
3.3 The BeanContext
The BeanContext is a container object for all your bean definitions (it also implements BeanDefinitionRegistry).
It is also the point of initialization for Micronaut. Generally speaking however, you don’t have to interact directly with the BeanContext
API and can simply use javax.inject
annotations and the annotations defined within io.micronaut.context.annotation package for your dependency injection needs.
3.4 Injectable Container Types
In addition to being able to inject beans Micronaut natively supports injecting the following types:
Type | Description | Example |
---|---|---|
An |
|
|
An |
|
|
A lazy |
|
|
A native array of beans of a given type |
|
|
A |
|
A prototype bean will have one instance created per place the bean is injected. When a prototype bean is injected as a Provider , each call to get() will create a new instance.
|
3.5 Bean Qualifiers
If you have multiple possible implementations for a given interface that you want to inject, you need to use a qualifier.
Once again Micronaut leverages JSR-330 and the Qualifier and Named annotations to support this use case.
Qualifying By Name
To qualify by name you can use the Named annotation. For example, consider the following classes:
public interface Engine { (1)
int getCylinders();
String start();
}
@Singleton
public class V6Engine implements Engine { (2)
@Override
public String start() {
return "Starting V6";
}
@Override
public int getCylinders() {
return 6;
}
}
@Singleton
public class V8Engine implements Engine {
@Override
public String start() {
return "Starting V8";
}
@Override
public int getCylinders() {
return 8;
}
}
@Singleton
public class Vehicle {
private final Engine engine;
@Inject
public Vehicle(@Named("v8") Engine engine) {(4)
this.engine = engine;
}
public String start() {
return engine.start();(5)
}
}
interface Engine { (1)
int getCylinders()
String start()
}
@Singleton
class V6Engine implements Engine { (2)
int cylinders = 6
@Override
String start() {
"Starting V6"
}
}
@Singleton
class V8Engine implements Engine { (3)
int cylinders = 8
@Override
String start() {
"Starting V8"
}
}
@Singleton
class Vehicle {
final Engine engine
@Inject Vehicle(@Named('v8') Engine engine) { (4)
this.engine = engine
}
String start() {
engine.start() (5)
}
}
interface Engine { (1)
val cylinders: Int
fun start(): String
}
@Singleton
class V6Engine : Engine { (2)
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)(4)
{
fun start(): String {
return engine.start()(5)
}
}
1 | The Engine interface defines the common contract |
2 | The V6Engine class is the first implementation |
3 | The V8Engine class is the second implementation |
4 | The javax.inject.Named annotation is used to indicate the V8Engine implementation is required |
5 | Calling the start method prints: "Starting V8" |
Micronaut is capable of injecting V8Engine
in the previous example, because:
@Named
qualifier value (v8
) + type being injected simple name (Engine
) == (case insensitive) == The simple name of a bean of type Engine
(V8Engine
)
You can also declare @Named at the class level of a bean to explicitly define the name of the bean.
Qualifying By Annotation
In addition to being able to qualify by name, you can build your own qualifiers using the Qualifier annotation. For example, consider the following 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
The above annotation is itself annotated with the @Qualifier
annotation to designate it as a qualifier. You can then use the annotation at any injection point in your code. For example:
@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
Primary is a qualifier that indicates that a bean is the primary bean that should be selected in the case of multiple possible interface implementations.
Consider the following example:
public interface ColorPicker {
String color();
}
interface ColorPicker {
String color()
}
interface ColorPicker {
fun color(): String
}
Given a common interface called ColorPicker
that is implemented by multiple classes.
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"
}
}
The Green
bean is a ColorPicker
, but is annotated with @Primary
.
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"
}
}
The Blue
bean is also a ColorPicker
and hence you have two possible candidates when injecting the ColorPicker
interface. Since Green
is the primary it will always be favoured.
@Controller("/testPrimary")
public class TestController {
protected final ColorPicker colorPicker;
public TestController(ColorPicker colorPicker) { (1)
this.colorPicker = colorPicker;
}
@Get
public String index() {
return colorPicker.color();
}
}
@Controller("/test")
class TestController {
protected final ColorPicker colorPicker
TestController(ColorPicker colorPicker) { (1)
this.colorPicker = colorPicker
}
@Get
String index() {
colorPicker.color()
}
}
@Controller("/test")
class TestController(val colorPicker: ColorPicker) { (1)
@Get
fun index(): String {
return colorPicker.color()
}
}
1 | Although there are two ColorPicker beans, Green gets injected due to the @Primary annotation. |
If multiple possible candidates are present and no @Primary
is defined then a NonUniqueBeanException will be thrown.
In addition to @Primary
, there is also a Secondary annotation which causes the opposite effect and allows de-prioritizing a bean.
3.6 Scopes
Micronaut features an extensible bean scoping mechanism based on JSR-330. The following default scopes are supported:
3.6.1 Built-In Scopes
Type | Description |
---|---|
Singleton scope indicates only one instance of the bean should exist |
|
Context scope indicates that the bean should be created at the same time as the |
|
Prototype scope indicates that a new instance of the bean is created each time it is injected |
|
Infrastructure scope represents a bean that cannot be overridden or replaced using @Replaces because it is critical to the functioning of the system. |
|
|
|
|
|
|
The @Prototype annotation is a synonym for @Bean because the default scope is prototype. |
Additional scopes can be added by defining a @Singleton
bean that implements the CustomScope interface.
Note that with Micronaut when starting an ApplicationContext by default @Singleton
scoped beans are created lazily and on demand. This is by design and to optimize startup time.
If this presents a problem for your use case you have the option of using the @Context annotation which binds the lifecycle of your object to the lifecycle of the ApplicationContext. In other words when the ApplicationContext is started your bean will be created.
Alternatively you can annotate any @Singleton
scoped bean with @Parallel which allows parallel initialization of your bean without impacting overall startup time.
If your bean fails to initialize in parallel then the application will be automatically shutdown. |
3.6.1.1 Eager Initialization of Singletons
Eager initialization of @Singleton
beans maybe desirable in certain scenarios, such as on AWS Lambda where more CPU resources are assigned to Lamdba construction than execution.
You can specify whether you want to initialize eagerly @Singleton
scoped beans using the ApplicationContextBuilder interface:
public class Application {
public static void main(String[] args) {
Micronaut.build(args)
.eagerInitSingletons(true) (1)
.mainClass(Application.class)
.start();
}
}
1 | Setting eager init to true initializes all singletons |
When you use Micronaut in environments such as Serverless Functions, you will not have an Application class and instead you extend a Micronaut provided class. In those cases, Micronaut provides methods which you can override to enhance the ApplicationContextBuilder
public class MyFunctionHandler extends MicronautRequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
...
@Nonnull
@Override
protected ApplicationContextBuilder newApplicationContextBuilder() {
ApplicationContextBuilder builder = super.newApplicationContextBuilder();
builder.eagerInitSingletons(true);
return builder;
}
...
}
@ConfigurationReader beans such as @EachProperty or @ConfigurationProperties are singleton beans. If you want to eager init configuration, but keep other @Singleton
scoped beans creation lazy, use eagerInitConfiguration
:
public class Application {
public static void main(String[] args) {
Micronaut.build(args)
.eagerInitConfiguration(true) (1)
.mainClass(Application.class)
.start();
}
}
1 | Setting eager init to true initializes all configuration reader beans. |
3.6.2 Refreshable Scope
The Refreshable scope is a custom scope that allows a bean’s state to be refreshed via:
-
/refresh
endpoint. -
Publication of a RefreshEvent.
The following example, illustrates the @Refreshable
scope behavior.
@Refreshable (1)
public static class WeatherService {
private String forecast;
@PostConstruct
public void init() {
forecast = "Scattered Clouds " + new SimpleDateFormat("dd/MMM/yy HH:mm:ss.SSS").format(new Date());(2)
}
public String latestForecast() {
return forecast;
}
}
@Refreshable (1)
static class WeatherService {
String forecast
@PostConstruct
void init() {
forecast = "Scattered Clouds ${new SimpleDateFormat("dd/MMM/yy HH:mm:ss.SSS").format(new Date())}" (2)
}
String latestForecast() {
return forecast
}
}
@Refreshable (1)
open class WeatherService {
private var forecast: String? = null
@PostConstruct
fun init() {
forecast = "Scattered Clouds " + SimpleDateFormat("dd/MMM/yy HH:mm:ss.SSS").format(Date())(2)
}
open fun latestForecast(): String? {
return forecast
}
}
1 | The WeatherService is annotated with @Refreshable scope which stores an instance until a refresh event is triggered |
2 | The value of the forecast property is set to a fixed value when the bean is created and won’t change until the bean is refreshed |
If you invoke the latestForecast()
twice, you will see identical responses such as "Scattered Clouds 01/Feb/18 10:29.199"
.
When the /refresh
endpoint is invoked or a RefreshEvent is published then the instance is invalidated and a new instance is created the next time the object is requested. For example:
applicationContext.publishEvent(new RefreshEvent());
applicationContext.publishEvent(new RefreshEvent())
applicationContext.publishEvent(RefreshEvent())
3.6.3 Scopes on Meta Annotations
Scopes can be defined on Meta annotations that you can then apply to your classes. Consider the following example meta annotation:
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import io.micronaut.context.annotation.Requires;
import javax.inject.Singleton;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
@Requires(classes = Car.class ) (1)
@Singleton (2)
@Documented
@Retention(RUNTIME)
public @interface Driver {
}
import io.micronaut.context.annotation.Requires
import javax.inject.Singleton
import java.lang.annotation.Documented
import java.lang.annotation.Retention
import static java.lang.annotation.RetentionPolicy.RUNTIME
@Requires(classes = Car.class ) (1)
@Singleton (2)
@Documented
@Retention(RUNTIME)
@interface Driver {
}
import io.micronaut.context.annotation.Requires
import javax.inject.Singleton
@Requires(classes = [Car::class]) (1)
@Singleton (2)
@MustBeDocumented
@Retention(AnnotationRetention.RUNTIME)
annotation class Driver
1 | The scope declares a requirement on a Car class using Requires |
2 | The annotation is declared as @Singleton |
In the example above the @Singleton
annotation is applied to the @Driver
annotation which results in every class that is annotated with @Driver
being regarded as singleton.
Note that in this case it is not possible to alter the scope when the annotation is applied. For example, the following will not override the scope declared by @Driver
and is invalid:
@Driver
@Prototype
class Foo {}
If you wish for the scope to be overridable you should instead use the DefaultScope annotation on @Driver
which allows a default scope to be specified if none other is present:
@Requires(classes = Car.class )
@DefaultScope(Singleton.class) (1)
@Documented
@Retention(RUNTIME)
public @interface Driver {
}
@Requires(classes = Car.class )
@DefaultScope(Singleton.class) (1)
@Documented
@Retention(RUNTIME)
@interface Driver {
}
@Requires(classes = [Car::class])
@DefaultScope(Singleton::class) (1)
@Documented
@Retention(RUNTIME)
annotation class Driver
1 | DefaultScope is used to declare which scope to be used if none is present |
3.7 Bean Factories
In many cases, you may want to make available as a bean a class that is not part of your codebase such as those provided by third-party libraries. In this case, you cannot annotate the already compiled class. Instead, you should implement a @Factory.
A factory is a class annotated with the Factory annotation that provides 1 or more methods annotated with a bean scope annotation. Which annotation you use depends on what scope you want the bean to be in. See the section on bean scopes for more information.
The return types of methods annotated with a bean scope annotation are the bean types. This is best illustrated by an example:
@Singleton
class CrankShaft {
}
class V8Engine implements Engine {
private final int cylinders = 8;
private final CrankShaft crankShaft;
public V8Engine(CrankShaft crankShaft) {
this.crankShaft = crankShaft;
}
@Override
public String start() {
return "Starting V8";
}
}
@Factory
class EngineFactory {
@Singleton
Engine v8Engine(CrankShaft crankShaft) {
return new V8Engine(crankShaft);
}
}
@Singleton
class CrankShaft {
}
class V8Engine implements Engine {
final int cylinders = 8
final CrankShaft crankShaft
V8Engine(CrankShaft crankShaft) {
this.crankShaft = crankShaft
}
@Override
String start() {
"Starting V8"
}
}
@Factory
class EngineFactory {
@Singleton
Engine v8Engine(CrankShaft crankShaft) {
new V8Engine(crankShaft)
}
}
@Singleton
internal class CrankShaft
internal class V8Engine(private val crankShaft: CrankShaft) : Engine {
private val cylinders = 8
override fun start(): String {
return "Starting V8"
}
}
@Factory
internal class EngineFactory {
@Singleton
fun v8Engine(crankShaft: CrankShaft): Engine {
return V8Engine(crankShaft)
}
}
In this case, the V8Engine
is built by the EngineFactory
class' v8Engine
method. Note that you can inject parameters into the method and these parameters will be resolved as beans. The resulting V8Engine
bean will be a singleton.
A factory can have multiple methods annotated with bean scope annotations, each one returning a distinct bean type.
If you take this approach, then you should not invoke other bean methods internally within the class. Instead, inject the types via parameters. |
To allow the resulting bean to participate in the application context shutdown process, annotate the method with @Bean and set the preDestroy argument to the name of the method that should be called to close the bean.
|
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 the InjectionPoint instance which can be used to analyze the annotation values defined:
@Factory
class EngineFactory {
@Prototype
Engine v8Engine(InjectionPoint<?> injectionPoint, CrankShaft crankShaft) { (1)
final int cylinders = injectionPoint
.getAnnotationMetadata()
.intValue(Cylinders.class).orElse(8); (2)
switch (cylinders) { (3)
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) { (1)
final int cylinders = injectionPoint
.getAnnotationMetadata()
.intValue(Cylinders.class).orElse(8) (2)
switch (cylinders) { (3)
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 { (1)
val cylinders = injectionPoint
.annotationMetadata
.intValue(Cylinders::class.java).orElse(8) (2)
return when (cylinders) { (3)
6 -> V6Engine(crankShaft)
8 -> V8Engine(crankShaft)
else -> throw IllegalArgumentException("Unsupported number of cylinders specified: $cylinders")
}
}
}
1 | The factory method defines a parameter of type InjectionPoint. |
2 | The annotation metadata is used to obtain the value of the @Cylinder annotation |
3 | The value is used to construct an engine, throwing an exception if an engine cannot be constructed. |
It is important to note that the factory is declared as @Prototype scope so that the method is invoked for each injection point. If the V8Engine and V6Engine types are required to be singletons then the factory should use a map to ensure the objects are only constructed once.
|
3.8 Conditional Beans
At times you may want a bean to load conditionally based on various potential factors including the classpath, the configuration, the presence of other beans etc.
The Requires annotation provides the ability to define one or many conditions on a bean.
Consider the following example:
@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
public class JdbcBookService implements BookService {
DataSource dataSource;
public JdbcBookService(DataSource dataSource) {
this.dataSource = dataSource;
}
@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
class JdbcBookService implements BookService {
DataSource dataSource
@Singleton
@Requirements(Requires(beans = [DataSource::class]), Requires(property = "datasource.url"))
class JdbcBookService(internal var dataSource: DataSource) : BookService {
The above bean defines two requirements. The first indicates that a DataSource
bean must be present for the bean to load. The second requirement ensures that the datasource.url
property is set before loading the JdbcBookService
bean.
Kotlin currently does not support repeatable annotations. Use the @Requirements annotation when multiple requires are needed. For example, @Requirements(Requires(…), Requires(…)) . See https://youtrack.jetbrains.com/issue/KT-12794 to track this feature.
|
If you have multiple requirements that you find you may need to repeat on multiple beans then you can define a meta-annotation with the requirements:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PACKAGE, ElementType.TYPE})
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
public @interface RequiresJdbc {
}
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target([ElementType.PACKAGE, ElementType.TYPE])
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
@interface RequiresJdbc {
}
@Documented
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FILE)
@Requirements(Requires(beans = [DataSource::class]), Requires(property = "datasource.url"))
annotation class RequiresJdbc
In the above example an annotation called RequiresJdbc
is defined that can then be used on the JdbcBookService
instead:
@RequiresJdbc
public class JdbcBookService implements BookService {
...
}
If you have multiple beans that need to fulfill a given requirement before loading then you may want to consider a bean configuration group, as explained in the next section.
Configuration Requirements
The @Requires annotation is very flexible and can be used for a variety of use cases. The following table summarizes some of the possibilities:
Requirement | Example |
---|---|
Require the presence of one ore more classes |
|
Require the absence of one ore more classes |
|
Require the presence one or more beans |
|
Require the absence of one or more beans |
|
Require the environment to be applied |
|
Require the environment to not be applied |
|
Require the presence of another configuration package |
|
Require the absence of another configuration package |
|
Require particular SDK version |
|
Requires classes annotated with the given annotations to be available to the application via package scanning |
|
Require a property with an optional value |
|
Require a property to not be part of the configuration |
|
Require the presence of one or more files in the file system |
|
Require the presence of one or more classpath resources |
|
Require the current operating system to be in the list |
|
Require the current operating system to not be in the list |
|
Additional Notes on Property Requirements.
Adding a requirement on a property has some additional functionality. You can require the property to be a certain value, not be a certain value, and use a default in those checks if its not set.
@Requires(property="foo") (1)
@Requires(property="foo", value="John") (2)
@Requires(property="foo", value="John", defaultValue="John") (3)
@Requires(property="foo", notEquals="Sally") (4)
1 | Requires the property to be set |
2 | Requires the property to be "John" |
3 | Requires the property to be "John" or not set |
4 | Requires the property to not be "Sally" or not set |
Debugging Conditional Beans
If you have multiple conditions and complex requirements it may become difficult to understand why a particular bean has not been loaded.
To help resolve issues with conditional beans you can enable debug logging for the io.micronaut.context.condition
package which will log the reasons why beans were not loaded.
<logger name="io.micronaut.context.condition" level="DEBUG"/>
3.9 Bean Replacement
One significant difference between Micronaut’s Dependency Injection system and Spring is the way beans can be replaced.
In a Spring application, beans have names and can effectively be overridden simply by creating a bean with the same name, regardless of the type of the bean. Spring also has the notion of bean registration order, hence in Spring Boot you have @AutoConfigureBefore
and @AutoConfigureAfter
that control how beans override each other.
This strategy leads to difficult to debug problems, for example:
-
Bean loading order changes, leading to unexpected results
-
A bean with the same name overrides another bean with a different type
To avoid these problems, Micronaut’s DI has no concept of bean names or load order. Beans have a type and a Qualifier. You cannot override a bean of a completely different type with another.
A useful benefit of Spring’s approach is that it allows overriding existing beans to customize behaviour. In order to support the same ability, Micronaut’s DI provides an explicit @Replaces annotation, which integrates nicely with support for Conditional Beans and clearly documents and expresses the intention of the developer.
Any existing bean can be replaced by another bean that declares @Replaces. For example, consider the following class:
@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
public class JdbcBookService implements BookService {
DataSource dataSource;
public JdbcBookService(DataSource dataSource) {
this.dataSource = dataSource;
}
@Singleton
@Requires(beans = DataSource.class)
@Requires(property = "datasource.url")
class JdbcBookService implements BookService {
DataSource dataSource
@Singleton
@Requirements(Requires(beans = [DataSource::class]), Requires(property = "datasource.url"))
class JdbcBookService(internal var dataSource: DataSource) : BookService {
You can define a class in src/test/java
that replaces this class just for your tests:
@Replaces(JdbcBookService.class) (1)
@Singleton
public class MockBookService implements BookService {
Map<String, Book> bookMap = new LinkedHashMap<>();
@Override
public Book findBook(String title) {
return bookMap.get(title);
}
}
@Replaces(JdbcBookService.class) (1)
@Singleton
class MockBookService implements BookService {
Map<String, Book> bookMap = [:]
@Override
Book findBook(String title) {
bookMap.get(title)
}
}
@Replaces(JdbcBookService::class) (1)
@Singleton
class MockBookService : BookService {
var bookMap: Map<String, Book> = LinkedHashMap()
override fun findBook(title: String): Book? {
return bookMap[title]
}
}
1 | The MockBookService declares that it replaces JdbcBookService |
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")
}
}
To replace a factory in its entirety, it is necessary that your factory methods match the return types of all of the methods in the replaced factory. |
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
.
3.10 Bean Configurations
A bean @Configuration is a grouping of multiple bean definitions within a package.
The @Configuration
annotation is applied at the package level and informs Micronaut that the beans defined with the package form a logical grouping.
The @Configuration
annotation is typically applied to package-info
class. For example:
@Configuration
package my.package
import io.micronaut.context.annotation.Configuration
Where this grouping becomes useful is when the bean configuration is made conditional via the @Requires
annotation. For example:
@Configuration
@Requires(beans = javax.sql.DataSource)
package my.package
In the above example, all bean definitions within the annotated package will only be loaded and made available if a javax.sql.DataSource
bean is present. This allows you to implement conditional auto-configuration of bean definitions.
Java and Kotlin also support this functionality via package-info.java . Kotlin does not support a package-info.kt as of version 1.3.
|
3.11 Life-Cycle Methods
When The Context Starts
If you wish for a particular method to be invoked when a bean is constructed then you can use the javax.annotation.PostConstruct
annotation:
import javax.annotation.PostConstruct; (1)
import javax.inject.Singleton;
@Singleton
public class V8Engine implements Engine {
private int cylinders = 8;
private boolean initialized = false; (2)
@Override
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 (3)
public void initialize() {
this.initialized = true;
}
}
import javax.annotation.PostConstruct (1)
import javax.inject.Singleton
@Singleton
class V8Engine implements Engine {
int cylinders = 8
boolean initialized = false (2)
@Override
String start() {
if(!initialized) throw new IllegalStateException("Engine not initialized!")
return "Starting V8"
}
@PostConstruct (3)
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 (2)
override fun start(): String {
check(isIntialized) { "Engine not initialized!" }
return "Starting V8"
}
@PostConstruct (3)
fun initialize() {
this.isIntialized = true
}
}
1 | The PostConstruct annotation is imported |
2 | A field is defined that requires initialization |
3 | A method is annotated with @PostConstruct and will be invoked once the object is constructed and fully injected. |
When The Context Closes
If you wish for a particular method to be invoked when the context is closed then you can use the javax.annotation.PreDestroy
annotation:
import javax.annotation.PreDestroy; (1)
import javax.inject.Singleton;
import java.util.concurrent.atomic.AtomicBoolean;
@Singleton
public class PreDestroyBean implements AutoCloseable {
AtomicBoolean stopped = new AtomicBoolean(false);
@PreDestroy (2)
@Override
public void close() throws Exception {
stopped.compareAndSet(false, true);
}
}
import javax.annotation.PreDestroy (1)
import java.util.concurrent.atomic.AtomicBoolean
import javax.inject.Singleton
@Singleton
class PreDestroyBean implements AutoCloseable {
AtomicBoolean stopped = new AtomicBoolean(false)
@PreDestroy (2)
@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 (2)
@Throws(Exception::class)
override fun close() {
stopped.compareAndSet(false, true)
}
}
1 | The PreDestroy annotation is imported |
2 | A method is annotated with @PreDestroy and will be invoked when the context is closed. |
For factory beans, the preDestroy
value in the Bean annotation can be used to tell Micronaut which method to invoke.
import io.micronaut.context.annotation.Bean;
import io.micronaut.context.annotation.Factory;
import javax.inject.Singleton;
@Factory
public class ConnectionFactory {
@Bean(preDestroy = "stop") (1)
@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") (1)
@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") (1)
@Singleton
fun connection(): Connection {
return Connection()
}
}
import java.util.concurrent.atomic.AtomicBoolean;
public class Connection {
AtomicBoolean stopped = new AtomicBoolean(false);
public void stop() { (2)
stopped.compareAndSet(false, true);
}
}
import java.util.concurrent.atomic.AtomicBoolean
class Connection {
AtomicBoolean stopped = new AtomicBoolean(false)
void stop() { (2)
stopped.compareAndSet(false, true)
}
}
import java.util.concurrent.atomic.AtomicBoolean
class Connection {
internal var stopped = AtomicBoolean(false)
fun stop() { (2)
stopped.compareAndSet(false, true)
}
}
1 | The preDestroy value is set on the annotation |
2 | The annotation value matches the method name |
Just simply implementing the Closeable or AutoCloseable interfaces is not enough to get a bean to close with the context. One of the above methods must be used. |
3.12 Context Events
Micronaut supports a general event system through the context. The ApplicationEventPublisher API is used to publish events and the ApplicationEventListener API is used to listen to events. The event system is not limited to the events that Micronaut publishes and can be used for custom events created by the users.
Publishing Events
The ApplicationEventPublisher API supports events of any type, however all events that Micronaut publishes extend ApplicationEvent.
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())
}
}
Publishing an event is synchronous by default! The publishEvent method will not return until all listeners have been executed. Move this work off to a thread pool if it is time intensive.
|
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.
ApplicationEventListener
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());
}
}
}
ApplicationEventListener
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()
}
}
ApplicationEventListener
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()
}
}
The supports method can be overridden to further clarify events that should be processed. |
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 like StartupEvent and ShutdownEvent:
@EventListener
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;
}
}
@EventListener
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
}
}
@EventListener
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:
@EventListener
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));
}
}
}
@EventListener
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()
}
}
@EventListener
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
3.13 Bean Events
You can hook into the creation of beans using one of the following interfaces:
-
BeanInitializedEventListener - allows modifying or replacing of a bean after the properties have been set but prior to
@PostConstruct
event hooks. -
BeanCreatedEventListener - allows modifying or replacing of a bean after the bean is fully initialized and all
@PostConstruct
hooks called.
The BeanInitializedEventListener
interface is commonly used in combination with Factory beans. Consider the following example:
public class V8Engine implements Engine {
private final int cylinders = 8;
private double rodLength; (1)
public V8Engine(double rodLength) {
this.rodLength = rodLength;
}
@Override
public String start() {
return "Starting V" + String.valueOf(getCylinders()) + " [rodLength=" + String.valueOf(getRodLength()) + "]";
}
@Override
public final int getCylinders() {
return cylinders;
}
public double getRodLength() {
return rodLength;
}
public void setRodLength(double rodLength) {
this.rodLength = rodLength;
}
}
@Factory
public class EngineFactory {
private V8Engine engine;
private double rodLength = 5.7;
@PostConstruct
public void initialize() {
engine = new V8Engine(rodLength); (2)
}
@Singleton
public Engine v8Engine() {
return engine;(3)
}
public void setRodLength(double rodLength) {
this.rodLength = rodLength;
}
}
@Singleton
public class EngineInitializer implements BeanInitializedEventListener<EngineFactory> { (4)
@Override
public EngineFactory onInitialized(BeanInitializingEvent<EngineFactory> event) {
EngineFactory engineFactory = event.getBean();
engineFactory.setRodLength(6.6);(5)
return engineFactory;
}
}
class V8Engine implements Engine {
final int cylinders = 8
double rodLength (1)
@Override
String start() {
return "Starting V${cylinders} [rodLength=$rodLength]"
}
}
@Factory
class EngineFactory {
private V8Engine engine
double rodLength = 5.7
@PostConstruct
void initialize() {
engine = new V8Engine(rodLength: rodLength) (2)
}
@Singleton
Engine v8Engine() {
return engine (3)
}
}
@Singleton
class EngineInitializer implements BeanInitializedEventListener<EngineFactory> { (4)
@Override
EngineFactory onInitialized(BeanInitializingEvent<EngineFactory> event) {
EngineFactory engineFactory = event.bean
engineFactory.rodLength = 6.6 (5)
return event.bean
}
}
class V8Engine(var rodLength: Double) : Engine { (1)
override val cylinders = 8
override fun start(): String {
return "Starting V$cylinders [rodLength=$rodLength]"
}
}
@Factory
class EngineFactory {
private var engine: V8Engine? = null
private var rodLength = 5.7
@PostConstruct
fun initialize() {
engine = V8Engine(rodLength) (2)
}
@Singleton
fun v8Engine(): Engine? {
return engine(3)
}
fun setRodLength(rodLength: Double) {
this.rodLength = rodLength
}
}
@Singleton
class EngineInitializer : BeanInitializedEventListener<EngineFactory> { (4)
override fun onInitialized(event: BeanInitializingEvent<EngineFactory>): EngineFactory {
val engineFactory = event.bean
engineFactory.setRodLength(6.6)(5)
return event.bean as EngineFactory
}
}
1 | The V8Engine class defines a rodLength property |
2 | The EngineFactory initializes the value of rodLength and creates the instance |
3 | The created instance is returned as a Bean |
4 | The BeanInitializedEventListener interface is implemented to listen for the initialization of the factory |
5 | Within the onInitialized method the rodLength is overridden prior to the engine being created by the factory bean. |
The BeanCreatedEventListener interface is more typically used to decorate or enhance a fully initialized bean by creating a proxy for example.
Bean event listeners are initialized before type converters. If your event listener relies on type conversion either by relying on a configuration properties bean or by any other mechanism, you may see errors related to type conversion. |
3.14 Bean Introspection
Since Micronaut 1.1, a compilation time replacement for the JDK’s Introspector class has been included.
The BeanIntrospector and BeanIntrospection interfaces allow looking up bean introspections that allow you to instantiate and read/write bean properties without using reflection or caching reflective metadata which consumes excessive memory for large beans.
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.3")
<annotationProcessorPaths>
<path>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-inject-java</artifactId>
<version>2.0.3</version>
</path>
</annotationProcessorPaths>
For Kotlin the micronaut-inject-java dependency should be in kapt scope and for Groovy you should have micronaut-inject-groovy in compileOnly scope.
|
runtime("io.micronaut:micronaut-core:2.0.3")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-core</artifactId>
<version>2.0.3</version>
<scope>runtime</scope>
</dependency>
Once your build is configured you have a few ways to generate introspection data.
Use the @Introspected
Annotation
The @Introspected annotation can be used on any class which you want to make available for introspection, simply annotate the class with @Introspected:
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
}
Once introspection data has been produced at compilation time you can then retrieve it via the BeanIntrospection API:
final BeanIntrospection<Person> introspection = BeanIntrospection.getIntrospection(Person.class); (1)
Person person = introspection.instantiate("John"); (2)
System.out.println("Hello " + person.getName());
final BeanProperty<Person, String> property = introspection.getRequiredProperty("name", String.class); (3)
property.set(person, "Fred"); (4)
String name = property.get(person); (5)
System.out.println("Hello " + person.getName());
def introspection = BeanIntrospection.getIntrospection(Person) (1)
Person person = introspection.instantiate("John") (2)
println("Hello ${person.name}")
BeanProperty<Person, String> property = introspection.getRequiredProperty("name", String) (3)
property.set(person, "Fred") (4)
String name = property.get(person) (5)
println("Hello ${person.name}")
val introspection = BeanIntrospection.getIntrospection(Person::class.java) (1)
val person : Person = introspection.instantiate("John") (2)
print("Hello ${person.name}")
val property : BeanProperty<Person, String> = introspection.getRequiredProperty("name", String::class.java) (3)
property.set(person, "Fred") (4)
val name = property.get(person) (5)
print("Hello ${person.name}")
1 | You can retrieve a BeanIntrospection with the getIntrospection static method |
2 | Once you have a BeanIntrospection you can instantiate a bean with the instantiate method. |
3 | A BeanProperty can be retreived from the introspection |
4 | .. and the set method used to set the property value |
5 | .. and the get method used to retrieve the property value |
Constructor Methods
For classes with multiple constructors, it is possible to inform Micronaut which constructor should be used to instantiate the class. Apply the @Creator annotation to which constructor to be used.
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 (1)
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 (1)
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) { (1)
constructor(make: String, model: String) : this(make, model, 2) {}
}
1 | The @Creator annotation is used to denote which constructor should be used |
This class has no default constructor so calls to instantiate without arguments will throw an InstantiationException. |
Static Creator Methods
For the use case of static methods being used to instantiate the class, the @Creator annotation can be applied to those methods to allow for the introspection to execute the method.
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 (1)
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 (1)
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 (1)
fun forName(name: String): Business {
return Business(name)
}
}
}
1 | The @Creator annotation is applied to the static method which will be used to instantiate the class |
There can be multiple "creator" methods annotated. If one exists without arguments, that will be used as the default construction method. The first method with arguments will be used as the primary construction method. |
Enums
It is possible to introspect enums as well. Simply add the annotation to the enum and it can be constructed through the standard valueOf
method.
Use the @Introspected
Annotation on a Configuration Class
If the class you wish to introspect is already compiled and not under your control an alternative option is to define a configuration class with the classes
member of the @Introspected annotation set.
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
In the above example the PersonConfiguration
class will generate introspections for the Person
class.
You can also use the packages member of the @Introspected which will package scan at compilation time and generate introspections for all classes within a package. Note however this feature is currently regarded as experimental.
|
Write an AnnotationMapper
to Introspect Existing Annotations
If there is an existing annotation that you wish to introspect by default you can write an AnnotationMapper.
An example of this is EntityIntrospectedAnnotationMapper which ensures all beans annotated with javax.persistence.Entity
are introspectable by default.
The AnnotationMapper should be on the annotation processor classpath.
|
The BeanWrapper API
A BeanProperty 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 the BeanWrapper 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")); (1)
wrapper.setProperty("age", "20"); (2)
int newAge = wrapper.getRequiredProperty("age", int.class); (3)
System.out.println("Person's age now " + newAge);
final BeanWrapper<Person> wrapper = BeanWrapper.getWrapper(new Person("Fred")) (1)
wrapper.setProperty("age", "20") (2)
int newAge = wrapper.getRequiredProperty("age", Integer) (3)
println("Person's age now $newAge")
val wrapper = BeanWrapper.getWrapper(Person("Fred")) (1)
wrapper.setProperty("age", "20") (2)
val newAge = wrapper.getRequiredProperty("age", Int::class.java) (3)
println("Person's age now $newAge")
1 | The getWrapper static method can be used to obtain a BeanWrapper for a bean instance. |
2 | You can set properties and the BeanWrapper will perform type conversion, or throw ConversionErrorException if conversion is not possible. |
3 | You can retrieve a property using getRequiredProperty and request the appropriate type. If the property doesn’t exist a IntrospectionException will be thrown and if it cannot be converted a ConversionErrorException will be thrown. |
Jackson and Bean Introspection
Jackson is configured to use the BeanIntrospection 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.
This feature is enabled by default, you can disable it by setting the jackson.bean-introspection-module
configuration to false
.
Currently only bean properties (private field with public getter/setter) are supported and usage of public fields is not supported. |
This feature is currently regarded as experimental and may be subject to changes in the future. |
3.15 Bean Validation
Since Micronaut 1.2, Micronaut has built-in support for validating beans that are annotated with javax.validation
annotations. As a minimum you should include the micronaut-validation
module as a compile dependency:
implementation("io.micronaut:micronaut-validation")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-validation</artifactId>
</dependency>
Note that Micronaut’s implementation is not currently fully compliant with the Bean Validator specification as the specification heavily relies on reflection-based APIs.
The following features are unsupported at this time:
-
Annotations on generic argument types since only the Java language supports this feature.
-
Any interaction with the constraint metadata API, since Micronaut uses already computed compilation time metadata.
-
XML-based configuration
-
Instead of using
javax.validation.ConstraintValidator
you should use ConstraintValidator (io.micronaut.validation.validator.constraints.ConstraintValidator) to define custom constraints, which supports validating annotations at compilation time.
Micronaut’s implementation includes the following benefits:
-
Reflection and Runtime Proxy free validation resulting in reduced memory consumption
-
Smaller JAR size since Hibernate Validator adds another 1.4MB
-
Faster startup since Hibernate Validator adds 200ms+ startup overhead
-
Configurability via Annotation Metadata
-
Support for Reactive Bean Validation
-
Support for validating the source AST at compilation time
-
Automatic compatibility with GraalVM native without additional configuration
If you require full Bean Validator 2.0 compliance you can add the micronaut-hibernate-validator
module to your classpath, which will replace Micronaut’s implementation.
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 you are using Kotlin the class and method must be declared open so that Micronaut can create a compilation time subclass, alternatively you can annotate the class with @Validated and configure the Kotlin all-open plugin to open classes annotated with this type. See the Compiler plugins section.
|
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("") (1)
);
assertEquals("sayHello.name: must not be blank", exception.getMessage()); (2)
}
}
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("") (1)
then:"A validation error occurs"
def e = thrown(ConstraintViolationException)
e.message == "sayHello.name: must not be blank" // (2)
}
}
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("") } (1)
assertEquals("sayHello.name: must not be blank", exception.message) (2)
}
}
1 | The method is called with a blank string |
2 | An exception occurs |
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 Bean Introspection) 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 @Introspected annotation can be used as a meta-annotation and common annotations like @javax.persistence.Entity are treated as @Introspected
|
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 of Validator:
@Inject
Validator validator;
@Test
void testThatPersonIsValidWithValidator() {
Person person = new Person();
person.setName("");
person.setAge(10);
final Set<ConstraintViolation<Person>> constraintViolations = validator.validate(person); (1)
assertEquals(2, constraintViolations.size()); (2)
}
@Inject Validator validator
void "test person is validated with validator"() {
when:"The person is validated"
def constraintViolations = validator.validate(new Person(name: "", age: 10)) (1)
then:"A validation error occurs"
constraintViolations.size() == 2 // (2)
}
@Inject
lateinit var validator: Validator
@Test
fun testThatPersonIsValidWithValidator() {
val person = Person("", 10)
val constraintViolations = validator.validate(person) (1)
assertEquals(2, constraintViolations.size) (2)
}
1 | The validator is used to validate the person |
2 | The constraint violations are verified |
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) (1)
);
assertEquals(2, exception.getConstraintViolations().size()); (2)
}
@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)) (1)
then:"A validation error occurs"
def e = thrown(ConstraintViolationException)
e.constraintViolations.size() == 2 // (2)
}
@Inject
lateinit var personService: PersonService
@Test
fun testThatPersonIsValid() {
val person = Person("", 10)
val exception = assertThrows(ConstraintViolationException::class.java (1)
) { personService.sayHello(person) }
assertEquals(2, exception.constraintViolations.size) (2)
}
1 | A validated method is invoked |
2 | The constraint violations are verified |
Validating Configuration Properties
You can also validate the properties of classes that are annotated with @ConfigurationProperties to ensure configuration is correct.
It is recommended that you annotate @ConfigurationProperties that features validation with @Context to ensure that the validation occurs at startup time. |
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 = { }) (1)
public @interface DurationPattern {
String message() default "invalid duration ({validatedValue})"; (2)
/**
* Defines several constraints on the same element.
*/
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
@Documented
@interface List {
DurationPattern[] value(); (3)
}
}
import javax.validation.Constraint
import java.lang.annotation.*
import static java.lang.annotation.RetentionPolicy.RUNTIME
@Retention(RUNTIME)
@Constraint(validatedBy = []) (1)
@interface DurationPattern {
String message() default "invalid duration ({validatedValue})" (2)
}
import javax.validation.Constraint
@Retention(AnnotationRetention.RUNTIME)
@Constraint(validatedBy = []) (1)
annotation class DurationPattern(
val message: String = "invalid duration ({validatedValue})" (2)
)
1 | The annotation should be annotated with javax.validation.Constraint |
2 | A message template can be provided in a hard coded manner as above. If none is specified Micronaut will try to find a message using ClassName.message using the MessageSource interface. (optional) |
3 | To support repeated annotations you can define a inner annotation (optional). |
You can add messages and message bundles using the MessageSource and ResourceBundleMessageSource classes. |
Once you have defined the annotation you need to implement a ConstraintValidator 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
.
Generally null is regarded as valid and @NotNull used to constrain a value as not being null . The example above regards null as a valid value.
|
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") (1)
);
assertEquals("startHoliday.duration: invalid duration (junk)", exception.getMessage()); (2)
}
void "test test custom validator"() {
when:"A custom validator is used"
holidayService.startHoliday("Fred", "junk") (1)
then:"A validation error occurs"
def e = thrown(ConstraintViolationException)
e.message == "startHoliday.duration: invalid duration (junk)" // (2)
}
@Inject
lateinit var holidayService: HolidayService
@Test
fun testCustomValidator() {
val exception = assertThrows(ConstraintViolationException::class.java
) { holidayService.startHoliday("Fred", "junk") } (1)
assertEquals("startHoliday.duration: invalid duration (junk)", exception.message) (2)
}
1 | A validated method is invoked |
2 | THe constraint violations are verified |
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.
If duration is a property placeholder such as @TimeOff(duration="${my.value}") then validation handling will be deferred until runtime.
|
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.
3.16 Bean Annotation Metadata
The methods provided by Java’s AnnotatedElement API in general don’t provide the ability to introspect annotations without loading the annotations themselves, nor do they provide any ability to introspect annotation stereotypes (Often called meta-annotations, an annotation stereotype is where an annotation is annotated with another annotation, essentially inheriting its behaviour).
To solve this problem many frameworks produce runtime metadata or perform expensive reflection to analyze the annotations of a class.
Micronaut instead produces this annotation metadata at compile time, avoiding expensive reflection and saving on memory.
The BeanContext API can be used to obtain a reference to a BeanDefinition which implements the AnnotationMetadata interface.
For example the following code will obtain all bean definitions annotated with a particular 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
}
The above example will find all BeanDefinition 's annotated with @Controller
regardless whether @Controller
is used directly or inherited via an annotation stereotype.
Note that the getAnnotation
method and the variations of the method return an AnnotationValue type and not a Java annotation. This is by design, and you should generally try to work with this API when reading annotation values, the reason being that synthesizing a proxy implementation is worse from a performance and memory consumption perspective.
If you absolutely require a reference to an annotation instance you can use the synthesize
method, which will create a runtime proxy that implements the annotation interface:
Controller controllerAnn = definition.synthesize(Controller.class);
This approach is not recommended however, as it requires reflection and increases memory consumption due to the use of runtime created proxies and should be used as a last resort (for example if you need an instance of the annotation to integrate with a third party library).
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") (1)
String value() default "";
/**
* @return The ID of the client
*/
@AliasFor(member = "value") (2)
String id() default "";
}
1 | The value member also sets the id member |
2 | The id member also sets the value member |
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 an AnnotationMapper. To create an AnnotationMapper
you must perform the following steps:
-
Implement the AnnotationMapper 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)
Because AnnotationMapper implementations need to be on the annotation processor classpath they should generally be in a project that includes few external dependencies to avoid polluting the annotation processor classpath.
|
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) { (1)
final AnnotationValueBuilder<Introspected> builder = AnnotationValue.builder(Introspected.class)
// don't bother with transients properties
.member("excludedAnnotations", "javax.persistence.Transient"); (2)
return Collections.singletonList(
builder.build()
);
}
}
1 | The map method receives a AnnotationValue with the values for the annotation. |
2 | One or more annotations can be returned, in this case @Transient . |
The example above implements the NamedAnnotationMapper interface which allows for annotations to be mixed with runtime code. If you want to operate against a concrete annotation type then you should use TypedAnnotationMapper instead, though note it requires the annotation class itself to be on the annotation processor classpath. |
3.17 Micronaut Beans And Spring
Micronaut has integrations with Spring in several forms. See the Micronaut Spring Documentation for more information.
3.18 Android Support
Since Micronaut dependency injection is based on annotation processors and doesn’t rely on reflection, it can be used on Android when using the Android plugin 3.0.0 or above.
This allows you to use the same application framework for both your Android client and server implementation.
Configuring Your Android Build
To get started you must add the Micronaut annotation processors to the processor classpath using the annotationProcessor
dependency configuration.
The Micronaut micronaut-inject-java
dependency should be included in both the annotationProcessor
and compileOnly
scopes of your Android build configuration:
dependencies {
...
annotationProcessor "io.micronaut:micronaut-inject-java:2.0.3"
compileOnly "io.micronaut:micronaut-inject-java:2.0.3"
...
}
If you use lint
as part of your build you may also need to disable the invalid packages check since Android includes a hard coded check that regards the javax.inject
package as invalid unless you are using Dagger:
android {
...
lintOptions {
lintOptions { warning 'InvalidPackage' }
}
}
You can find more information on configuring annotations processors in the Android documentation.
Micronaut inject-java dependency uses Android Java 8 support features.
|
Enabling Dependency Injection
Once you have configured the classpath correctly, the next step is start the ApplicationContext.
The following example demonstrates creating a subclass of android.app.Application for that purpose:
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 { (1)
private ApplicationContext ctx;
public BaseApplication() {
super();
}
@Override
public void onCreate() {
super.onCreate();
ctx = ApplicationContext.run(MainActivity.class, Environment.ANDROID); (2)
registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacks() { (3)
@Override
public void onActivityCreated(Activity activity, Bundle bundle) {
ctx.inject(activity);
}
... // shortened for brevity, it is not necessary to implement other methods
});
}
}
1 | Extend the android.app.Application class |
2 | Run the ApplicationContext with the ANDROID environment |
3 | To allow dependency injection of Android Activity instances register a ActivityLifecycleCallbacks instance |
4 Application Configuration
Configuration in Micronaut takes inspiration from both Spring Boot and Grails, integrating configuration properties from multiple sources directly into the core IoC container.
Configuration can by default be provided in either Java properties, YAML, JSON or Groovy files. The convention is to search for a file called application.yml
, application.properties
, application.json
or application.groovy
.
In addition, just like Spring and Grails, Micronaut allows overriding any property via system properties or environment variables.
Each source of configuration is modeled with the PropertySource interface and the mechanism is extensible allowing the implementation of additional PropertySourceLoader implementations.
4.1 The Environment
The application environment is modelled by the Environment interface, which allows specifying one or many unique environment names when creating an ApplicationContext.
ApplicationContext applicationContext = ApplicationContext.run("test", "android");
Environment environment = applicationContext.getEnvironment();
assertTrue(environment.getActiveNames().contains("test"));
assertTrue(environment.getActiveNames().contains("android"));
when:
ApplicationContext applicationContext = ApplicationContext.run("test", "android")
Environment environment = applicationContext.getEnvironment()
then:
environment.getActiveNames().contains("test")
environment.getActiveNames().contains("android")
val applicationContext = ApplicationContext.run("test", "android")
val environment = applicationContext.getEnvironment()
assertTrue(environment.getActiveNames().contains("test"))
assertTrue(environment.getActiveNames().contains("android"))
The active environment names serve the purpose of allowing loading different configuration files depending on the environment and also using the @Requires annotation to conditionally load beans or bean @Configuration packages.
In addition, Micronaut will attempt to detect the current environments. For example within a Spock or JUnit test the TEST environment will be automatically active.
Additional active environments can be specified using the micronaut.environments
system property or the MICRONAUT_ENVIRONMENTS
environment variable. These can be specified as a comma separated list. For example:
$ java -Dmicronaut.environments=foo,bar -jar myapp.jar
The above activates environments called foo
and bar
.
Finally, the Cloud environment names are also detected. See the section on Cloud Configuration for more information.
Environment Priority
Micronaut will load property sources based off the environments specified, and if the same property key exists in multiple property sources specific to an environment, the environment order determines which value will be used.
Micronaut uses the following hierarchy for environment processing (lowest priority to highest priority):
-
Deduced environments
-
Environments from the
micronaut.environments
system property -
Environments from the
MICRONAUT_ENVIRONMENTS
environment variable -
Environments specified explicitly through the application context builder
This also applies to @MicronautTest(environments = )
Disabling Environment Detection
The automatic detection of environments can be disabled setting the micronaut.env.deduction
system property or the MICRONAUT_ENV_DEDUCTION
environment variable to false
. This will prevent Micronaut from detecting current environments, while still using any environments that are specifically provided as shown above.
$ java -Dmicronaut.env.deduction=false -jar myapp.jar
Alternatively, you can disable environment deduction using the ApplicationContextBuilder's deduceEnvironment
method when setting up your application.
@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()
}
4.2 Externalized Configuration with PropertySources
Additional PropertySource instances can be added to the environment prior to initializing the ApplicationContext.
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")
);
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")
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")
)
The PropertySource.of method can be used to create a ProperySource
from a map of values.
Alternatively one can register a PropertySourceLoader by creating a META-INF/services/io.micronaut.context.env.PropertySourceLoader
containing a reference to the class name of the PropertySourceLoader
.
Included PropertySource Loaders
Micronaut by default contains PropertySourceLoader
implementations that load properties from the given locations and priority:
-
Command line arguments
-
Properties from
SPRING_APPLICATION_JSON
(for Spring compatibility) -
Properties from
MICRONAUT_APPLICATION_JSON
-
Java System Properties
-
OS environment variables
-
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 aclasspath:
prefix. -
Environment-specific properties from
application-{environment}.{extension}
-
Application-specific properties from
application.{extension}
.properties , .json , .yml are supported out of the box. For Groovy users .groovy is supported as well.
|
Supplying Configuration via Command Line
Configuration can be supplied at the command line using Gradle or our Maven plugin. For example:
$ ./gradlew run --args="-endpoints.health.enabled=true -config.property=test"
$ ./mvnw mn:run -Dmn.appArgs="-endpoints.health.enabled=true -config.property=test"
In order for the configuration to be apart of the context, the args from the main method must be passed to the context builder. For example:
import io.micronaut.runtime.Micronaut;
public class Application {
public static void main(String[] args) {
Micronaut.run(Application.class, args); // passing args
}
}
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 on Configuration Injection).
Programmatic usage is also possible via the PropertyPlaceholderResolver interface. |
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:
Configuration Value | Resulting Properties | Property Source |
---|---|---|
|
|
Properties, YAML etc. |
|
|
Properties, YAML etc. |
|
|
Properties, YAML etc. |
|
|
Environment Variable |
|
|
Environment Variable |
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.
Because the number of properties generated is exponential based on the number of _ characters in the environment variable, it is recommended to refine which, if any, environment variables are included in configuration if the number of environment variables with a large number of underscores is high.
|
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()
}
}
The configuration above does not have any impact on property placeholders. It is still possible to reference an environment variable in a placeholder regardless of whether environment configuration is disabled, or even if the specific property is explicitly excluded. |
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}
Property | Value |
---|---|
random.port |
An available random port number |
random.int |
Random int |
random.integer |
Random int |
random.long |
Random long |
random.float |
Random float |
random.shortuuid |
Random UUID of only 10 chars in length (Note: As this isn’t full UUID, collision COULD occur) |
random.uuid |
Random UUID with dashes |
random.uuid2 |
Random UUID without dashes |
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.
To maintain a fast startup time, it is recommended to use this feature as sparingly as possible. |
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 the LoggingSystem 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.
4.3 Configuration Injection
You can inject configuration values into beans with Micronaut using the @Value annotation.
Using the @Value
Annotation
Consider the following example:
import javax.inject.Singleton;
@Singleton
public class EngineImpl implements Engine {
@Value("${my.engine.cylinders:6}") (1)
protected int cylinders;
@Override
public int getCylinders() {
return this.cylinders;
}
@Override
public String start() {(2)
return "Starting V" + getCylinders() + " Engine";
}
}
import javax.inject.Singleton
@Singleton
class EngineImpl implements Engine {
@Value('${my.engine.cylinders:6}') (1)
protected int cylinders
@Override
int getCylinders() {
this.cylinders
}
@Override
String start() { (2)
"Starting V${cylinders} Engine"
}
}
import javax.inject.Singleton
@Singleton
class EngineImpl : Engine {
@Value("\${my.engine.cylinders:6}") (1)
override var cylinders: Int = 0
protected set
override fun start(): String {(2)
return "Starting V$cylinders Engine"
}
}
1 | The @Value annotation accepts a string that can have embedded placeholder values (the default value can be provided by specifying a value after the colon : character). |
2 | The injected value can then be used within code. |
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
@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") (1)
protected int cylinders; (2)
private String manufacturer;
public int getCylinders() {
return cylinders;
}
public String getManufacturer() {
return manufacturer;
}
@Inject
public void setManufacturer(@Property(name = "my.engine.manufacturer") String manufacturer) { (3)
this.manufacturer = manufacturer;
}
}
import io.micronaut.context.annotation.Property
import javax.inject.Singleton
@Singleton
class Engine {
@Property(name = "my.engine.cylinders") (1)
protected int cylinders (2)
@Property(name = "my.engine.manufacturer") (3)
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") (1)
protected var cylinders: Int = 0 (2)
@set:Inject
@setparam:Property(name = "my.engine.manufacturer") (3)
var manufacturer: String? = null
fun cylinders(): Int {
return cylinders
}
}
1 | The my.engine.cylinders property will be resolved from configuration and injected directly into the field. |
2 | Fields subjected to injection should never be private otherwise expensive reflection must be used |
3 | The @Property annotation is used to inject through the setter |
Because it is not possible to define a default value with @Property , if the value doesn’t exist or cannot be converted to the required type, the bean instantiation will fail.
|
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:
application.yml
configurationdatasources:
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
@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.
The @MapFormat annotation can be used to customize the injected map depending whether you want nested keys, flat keys and it allows customization of the key style via the StringConvention enum. |
4.4 Configuration Properties
You can create type safe configuration by creating classes that are annotated with @ConfigurationProperties.
Micronaut will produce a reflection-free @ConfigurationProperties
bean and will also at compile time calculate the property paths to evaluate, greatly improving the speed and efficiency of loading @ConfigurationProperties
.
An example of a configuration class can be seen below:
import io.micronaut.context.annotation.ConfigurationProperties;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
@ConfigurationProperties("my.engine") (1)
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 (2)
private String manufacturer = "Ford"; (3)
@Min(1L)
private int cylinders;
private CrankShaft crankShaft = new CrankShaft();
@ConfigurationProperties("crank-shaft")
public static class CrankShaft { (4)
public Optional<Double> getRodLength() {
return rodLength;
}
public void setRodLength(Optional<Double> rodLength) {
this.rodLength = rodLength;
}
private Optional<Double> rodLength = Optional.empty(); (5)
}
}
import io.micronaut.context.annotation.ConfigurationProperties
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank
@ConfigurationProperties('my.engine') (1)
class EngineConfig {
@NotBlank (2)
String manufacturer = "Ford" (3)
@Min(1L)
int cylinders
CrankShaft crankShaft = new CrankShaft()
@ConfigurationProperties('crank-shaft')
static class CrankShaft { (4)
Optional<Double> rodLength = Optional.empty() (5)
}
}
import io.micronaut.context.annotation.ConfigurationProperties
import java.util.*
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank
@ConfigurationProperties("my.engine") (1)
class EngineConfig {
@NotBlank (2)
var manufacturer = "Ford" (3)
@Min(1L)
var cylinders: Int = 0
var crankShaft = CrankShaft()
@ConfigurationProperties("crank-shaft")
class CrankShaft { (4)
var rodLength: Optional<Double> = Optional.empty() (5)
}
}
1 | The @ConfigurationProperties annotation takes the configuration prefix |
2 | You can use javax.validation to validate the configuration |
3 | Default values can be assigned to the property |
4 | Static inner classes can provided nested configuration |
5 | Optional configuration values can be wrapped in a java.util.Optional |
Once you have prepared a type safe configuration it can simply be injected into your objects like any other bean:
@Singleton
public class EngineImpl implements Engine {
private final EngineConfig config;
public EngineImpl(EngineConfig config) {(1)
this.config = config;
}
@Override
public int getCylinders() {
return config.getCylinders();
}
@Override
public String start() {(2)
return getConfig().getManufacturer() + " Engine Starting V" + getConfig().getCylinders() +
" [rodLength=" + getConfig().getCrankShaft().getRodLength().orElse(6.0d) + "]";
}
public final EngineConfig getConfig() {
return config;
}
}
@Singleton
class EngineImpl implements Engine {
final EngineConfig config
EngineImpl(EngineConfig config) { (1)
this.config = config
}
@Override
int getCylinders() {
config.cylinders
}
@Override
String start() { (2)
"${config.manufacturer} Engine Starting V${config.cylinders} [rodLength=${config.crankShaft.rodLength.orElse(6.0d)}]"
}
}
@Singleton
class EngineImpl(val config: EngineConfig) : Engine {(1)
override val cylinders: Int
get() = config.cylinders
override fun start(): String {(2)
return "${config.manufacturer} Engine Starting V${config.cylinders} [rodLength=${config.crankShaft.rodLength.orElse(6.0)}]"
}
}
1 | Inject the EngineConfig bean |
2 | Use the configuration properties |
Configuration values can then be supplied from one of the PropertySource instances. For example:
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());
ApplicationContext applicationContext = ApplicationContext.run(
['my.engine.cylinders': '8'],
"test"
)
Vehicle vehicle = applicationContext
.getBean(Vehicle)
println(vehicle.start())
val map = mapOf( "my.engine.cylinders" to "8")
val applicationContext = ApplicationContext.run(map, "test")
val vehicle = applicationContext.getBean(Vehicle::class.java)
println(vehicle.start())
The above example prints: "Ford Engine Starting V8 [rodLength=6.0]"
Note for more complex configurations you can structure @ConfigurationProperties beans through inheritance.
For example creating a subclass of EngineConfig
with @ConfigurationProperties('bar')
will resolve all properties under the path my.engine.bar
.
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
When resolving properties Micronaut will use the ConversionService bean to convert properties. You can register additional converters for types not supported by micronaut by defining beans that implement the TypeConverter interface.
Micronaut features some built-in conversions that are useful, which are detailed below.
Duration Conversion
Durations can be specified by appending the unit with a number. Supported units are s
, ms
, m
etc. The following table summarizes examples:
Configuration Value | Resulting Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
Duration of 15 minutes using ISO-8601 format |
For example to configure the default HTTP client read timeout:
micronaut:
http:
client:
read-timeout: 15s
List / Array Conversion
Lists and arrays can be specified in Java properties files as comma-separated values or in YAML using native YAML lists. The generic types are used to convert the values. For example in YAML:
my:
app:
integers:
- 1
- 2
urls:
- http://foo.com
- http://bar.com
Or in Java properties file format:
my.app.integers=1,2
my.app.urls=http://foo.com,http://bar.com
Alternatively you can use an index:
my.app.integers[0]=1
my.app.integers[1]=2
For the above example configurations you can define properties to bind to with the target type supplied via generics:
List<Integer> integers;
List<URL> urls;
Readable Bytes
You can annotate any setter parameter with @ReadableBytes to allow the value to be set using a shorthand syntax for specifying bytes, kilobytes etc. For example the following is taken from HttpClientConfiguration:
@ReadableBytes
public void setMaxContentLength(@ReadableBytes int maxContentLength) {
this.maxContentLength = maxContentLength;
}
With the above in place you can set micronaut.http.client.max-content-length
using the following values:
Configuration Value | Resulting Value |
---|---|
|
10 megabytes |
|
10 kilobytes |
|
10 gigabytes |
|
A raw byte length |
Formatting Dates
The @Format annotation can be used on any setter to allow the date format to be specified when binding java.time
date objects.
@Format
for Datespublic void setMyDate(@Format("yyyy-MM-dd") LocalDate date) {
this.myDate = date;
}
Configuration Builder
Many existing frameworks and tools already use builder-style classes to construct configuration.
To support the ability for a builder style class to be populated with configuration values, the @ConfigurationBuilder annotation can be used. ConfigurationBuilder can be added to a field or method in a class annotated with @ConfigurationProperties.
Since there is no consistent way to define builders in the Java world, one or more method prefixes can be specified in the annotation to support builder methods like withXxx
or setXxx
. If the builder methods have no prefix, assign an empty string to the parameter.
A configuration prefix can also be specified to tell Micronaut where to look for configuration values. By default, the builder methods will use the configuration prefix defined at the class level @ConfigurationProperties annotation.
For example:
import io.micronaut.context.annotation.ConfigurationBuilder;
import io.micronaut.context.annotation.ConfigurationProperties;
@ConfigurationProperties("my.engine") (1)
class EngineConfig {
@ConfigurationBuilder(prefixes = "with") (2)
EngineImpl.Builder builder = EngineImpl.builder();
@ConfigurationBuilder(prefixes = "with", configurationPrefix = "crank-shaft") (3)
CrankShaft.Builder crankShaft = CrankShaft.builder();
private SparkPlug.Builder sparkPlug = SparkPlug.builder();
SparkPlug.Builder getSparkPlug() { return this.sparkPlug; }
@ConfigurationBuilder(prefixes = "with", configurationPrefix = "spark-plug") (4)
void setSparkPlug(SparkPlug.Builder sparkPlug) {
this.sparkPlug = sparkPlug;
}
}
import io.micronaut.context.annotation.ConfigurationBuilder
import io.micronaut.context.annotation.ConfigurationProperties
@ConfigurationProperties('my.engine') (1)
class EngineConfig {
@ConfigurationBuilder(prefixes = "with") (2)
EngineImpl.Builder builder = EngineImpl.builder()
@ConfigurationBuilder(prefixes = "with", configurationPrefix = "crank-shaft") (3)
CrankShaft.Builder crankShaft = CrankShaft.builder()
SparkPlug.Builder sparkPlug = SparkPlug.builder()
@ConfigurationBuilder(prefixes = "with", configurationPrefix = "spark-plug") (4)
void setSparkPlug(SparkPlug.Builder sparkPlug) {
this.sparkPlug = sparkPlug
}
}
import io.micronaut.context.annotation.ConfigurationBuilder
import io.micronaut.context.annotation.ConfigurationProperties
@ConfigurationProperties("my.engine") (1)
internal class EngineConfig {
@ConfigurationBuilder(prefixes = ["with"]) (2)
val builder = EngineImpl.builder()
@ConfigurationBuilder(prefixes = ["with"], configurationPrefix = "crank-shaft") (3)
val crankShaft = CrankShaft.builder()
@set:ConfigurationBuilder(prefixes = ["with"], configurationPrefix = "spark-plug") (4)
var sparkPlug = SparkPlug.builder()
}
1 | The @ConfigurationProperties annotation takes the configuration prefix |
2 | The first builder can be configured without the class configuration prefix; it will inherit from the above. |
3 | The second builder can be configured with the class configuration prefix + the configurationPrefix value. |
4 | The third builder demonstrates that the annotation can be applied to a method as well as a property. |
By default, only builder methods that take a single argument are supported. To support methods with no arguments, set the allowZeroArgs parameter of the annotation to true.
|
Just like in the previous example, we can construct an EngineImpl
. Since we are using a builder, a factory class can be used to build the engine from the 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)
}
}
The engine that was returned can then be injected anywhere an engine is depended on.
Configuration values can be supplied from one of the PropertySource instances. For example:
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())
The above example prints: "Subaru Engine Starting V4 [rodLength=4.0, sparkPlug=Iridium(NGK 6619 LFR6AIX)]"
MapFormat
For some use cases it may be desirable to accept a map of arbitrary configuration properties that can be supplied to a bean, especially if the bean represents a third-party API where not all of the possible configuration properties are known by the developer. For example, a datasource may accept a map of configuration properties specific to a particular database driver, allowing the user to specify any desired options in the map without coding every single property explicitly.
For this purpose, the MapFormat annotation allows you to bind a map to a single configuration property, and specify whether to accept a flat map of keys to values, or a nested map (where the values may be additional maps].
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) (1)
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) (1)
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) (1)
var sensors: Map<Int, String>? = null
}
1 | Note the transformation argument to the annotation; possible values are MapTransformation.FLAT (for flat maps) and MapTransformation.NESTED (for nested maps) |
@Singleton
public class EngineImpl implements Engine {
@Override
public Map getSensors() {
return config.getSensors();
}
@Override
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
}
@Override
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}]"
}
}
Now a map of properties can be supplied to the my.engine.sensors
configuration property.
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())
The above example prints: "Engine Starting V8 [sensors=2]"
4.5 Custom Type Converters
Micronaut features a built in type conversion mechanism that is extensible. To add additional type converters you register beans of type TypeConverter.
The following example shows how to use one of the built-in converters (Map to an Object) or create your own.
Consider the following ConfigurationProperties:
@ConfigurationProperties(MyConfigurationProperties.PREFIX)
public class MyConfigurationProperties {
public LocalDate getUpdatedAt() {
return this.updatedAt;
}
public static final String PREFIX = "myapp";
protected LocalDate updatedAt;
}
@ConfigurationProperties(MyConfigurationProperties.PREFIX)
class MyConfigurationProperties {
public static final String PREFIX = "myapp"
protected LocalDate updatedAt
LocalDate getUpdatedAt() {
return this.updatedAt
}
}
@ConfigurationProperties(MyConfigurationProperties.PREFIX)
class MyConfigurationProperties {
var updatedAt: LocalDate? = null
protected set
companion object {
const val PREFIX = "myapp"
}
}
The type MyConfigurationProperties
features a property called updatedAt
which is of type LocalDate.
Now let’s say you want to allow binding to this property from a map via configuration:
private static ApplicationContext ctx;
@BeforeClass
public static void setupCtx() {
ctx = ApplicationContext.run(
new LinkedHashMap<String, Object>() {{
put("myapp.updatedAt", (1)
new LinkedHashMap<String, Integer>() {{
put("day", 28);
put("month", 10);
put("year", 1982);
}}
);
}}
);
}
@AfterClass
public static void teardownCtx() {
if(ctx != null) {
ctx.stop();
}
}
@AutoCleanup
@Shared
ApplicationContext ctx = ApplicationContext.run(
"myapp.updatedAt": [day: 28, month: 10, year: 1982] (1)
)
lateinit var ctx: ApplicationContext
@BeforeEach
fun setup() {
ctx = ApplicationContext.run(
mapOf(
"myapp.updatedAt" to mapOf( (1)
"day" to 28,
"month" to 10,
"year" to 1982
)
)
)
}
@AfterEach
fun teardown() {
ctx?.close()
}
1 | Note how we match the myapp prefix and updatedAt property name in our MyConfigurationProperties class above |
This won’t work by default, since there is no built in conversion from Map
to LocalDate
. To resolve this you can define a custom TypeConverter:
import io.micronaut.core.convert.ConversionContext;
import io.micronaut.core.convert.ConversionService;
import io.micronaut.core.convert.TypeConverter;
import javax.inject.Singleton;
import java.time.DateTimeException;
import java.time.LocalDate;
import java.util.Map;
import java.util.Optional;
@Singleton
public class MapToLocalDateConverter implements TypeConverter<Map, LocalDate> { (1)
@Override
public Optional<LocalDate> convert(Map propertyMap, Class<LocalDate> targetType, ConversionContext context) {
Optional<Integer> day = ConversionService.SHARED.convert(propertyMap.get("day"), Integer.class);
Optional<Integer> month = ConversionService.SHARED.convert(propertyMap.get("month"), Integer.class);
Optional<Integer> year = ConversionService.SHARED.convert(propertyMap.get("year"), Integer.class);
if (day.isPresent() && month.isPresent() && year.isPresent()) {
try {
return Optional.of(LocalDate.of(year.get(), month.get(), day.get())); (2)
} catch (DateTimeException e) {
context.reject(propertyMap, e); (3)
return Optional.empty();
}
}
return Optional.empty();
}
}
import io.micronaut.core.convert.ConversionContext
import io.micronaut.core.convert.ConversionService
import io.micronaut.core.convert.TypeConverter
import javax.inject.Singleton
import java.time.DateTimeException
import java.time.LocalDate
@Singleton
class MapToLocalDateConverter implements TypeConverter<Map, LocalDate> { (1)
@Override
Optional<LocalDate> convert(Map propertyMap, Class<LocalDate> targetType, ConversionContext context) {
Optional<Integer> day = ConversionService.SHARED.convert(propertyMap.get("day"), Integer.class)
Optional<Integer> month = ConversionService.SHARED.convert(propertyMap.get("month"), Integer.class)
Optional<Integer> year = ConversionService.SHARED.convert(propertyMap.get("year"), Integer.class)
if (day.isPresent() && month.isPresent() && year.isPresent()) {
try {
return Optional.of(LocalDate.of(year.get(), month.get(), day.get())) (2)
} catch (DateTimeException e) {
context.reject(propertyMap, e) (3)
return Optional.empty()
}
}
return Optional.empty()
}
}
import io.micronaut.core.convert.ConversionContext
import io.micronaut.core.convert.ConversionService
import io.micronaut.core.convert.TypeConverter
import javax.inject.Singleton
import java.time.DateTimeException
import java.time.LocalDate
import java.util.Optional
@Singleton
class MapToLocalDateConverter : TypeConverter<Map<*, *>, LocalDate> { (1)
override fun convert(propertyMap: Map<*, *>, targetType: Class<LocalDate>, context: ConversionContext): Optional<LocalDate> {
val day = ConversionService.SHARED.convert(propertyMap["day"], Int::class.java)
val month = ConversionService.SHARED.convert(propertyMap["month"], Int::class.java)
val year = ConversionService.SHARED.convert(propertyMap["year"], Int::class.java)
if (day.isPresent && month.isPresent && year.isPresent) {
try {
return Optional.of(LocalDate.of(year.get(), month.get(), day.get())) (2)
} catch (e: DateTimeException) {
context.reject(propertyMap, e) (3)
return Optional.empty()
}
}
return Optional.empty()
}
}
1 | The class implements TypeConverter which takes two generic arguments. The type you are converting from and the type you are converting to |
2 | The implementation delegate to the default shared conversion service to convert the parts of the map that make the day, month and year into a LocalDate |
3 | If an exception occurs you can call reject(..) which propagates additional information to the container if something goes wrong during binding |
4.6 Using @EachProperty to Drive Configuration
The @ConfigurationProperties annotation is great for a single configuration class, but sometimes you want multiple instances each with their own distinct configuration. That is where EachProperty comes in.
The @EachProperty annotation will create a ConfigurationProperties
bean for each sub-property within the given property. As an example consider the following class:
import io.micronaut.context.annotation.Parameter;
import io.micronaut.context.annotation.EachProperty;
@EachProperty("test.datasource") (1)
public class DataSourceConfiguration {
private final String name;
private URI url = new URI("localhost");
public DataSourceConfiguration(@Parameter String name) (2)
throws URISyntaxException {
this.name = name;
}
public String getName() {
return name;
}
public URI getUrl() { (3)
return url;
}
public void setUrl(URI url) {
this.url = url;
}
}
@EachProperty("test.datasource")
(1)
class DataSourceConfiguration {
final String name
URI url = new URI("localhost")
DataSourceConfiguration(@Parameter String name) (2)
throws URISyntaxException {
this.name = name
}
}
@EachProperty("test.datasource") (1)
class DataSourceConfiguration (2)
@Throws(URISyntaxException::class)
constructor(@param:Parameter val name: String) {
(3)
var url = URI("localhost")
}
1 | The @EachProperty annotation defines the property name that should be handled. |
2 | The @Parameter annotation can be used to inject the name of the sub-property that defines the name of the bean (which is also the bean qualifier) |
3 | Each property of the bean is bound to configuration. |
The above DataSourceConfiguration
defines a url
property to configure one or many hypothetical data sources of some sort. The URLs themselves can be configured using any of the PropertySource instances evaluated to Micronaut:
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")
));
ApplicationContext applicationContext = ApplicationContext.run(PropertySource.of(
"test",
[
"test.datasource.one.url": "jdbc:mysql://localhost/one",
"test.datasource.two.url": "jdbc:mysql://localhost/two"
]
))
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"
)
))
In the above example two data sources (called one
and two
) are defined under the test.datasource
prefix defined earlier in the @EachProperty
annotation. Each of these configuration entries triggers the creation of a new DataSourceConfiguration
bean such that the following test succeeds:
Collection<DataSourceConfiguration> beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration.class);
assertEquals(2, beansOfType.size()); (1)
DataSourceConfiguration firstConfig = applicationContext.getBean(
DataSourceConfiguration.class,
Qualifiers.byName("one") (2)
);
assertEquals(
new URI("jdbc:mysql://localhost/one"),
firstConfig.getUrl()
);
when:
Collection<DataSourceConfiguration> beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration.class)
assertEquals(2, beansOfType.size()) (1)
DataSourceConfiguration firstConfig = applicationContext.getBean(
DataSourceConfiguration.class,
Qualifiers.byName("one") (2)
)
then:
new URI("jdbc:mysql://localhost/one") == firstConfig.getUrl()
val beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration::class.java)
assertEquals(2, beansOfType.size.toLong()) (1)
val firstConfig = applicationContext.getBean(
DataSourceConfiguration::class.java,
Qualifiers.byName("one") (2)
)
assertEquals(
URI("jdbc:mysql://localhost/one"),
firstConfig.url
)
1 | All beans of type DataSourceConfiguration can be retrieved using getBeansOfType |
2 | Individual beans can be achieved by using the byName qualifier. |
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
*
* https://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) (1)
public class RateLimitsConfiguration implements Ordered { (2)
private final Integer index;
private Duration period;
private Integer limit;
RateLimitsConfiguration(@Parameter Integer index) { (3)
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) (1)
class RateLimitsConfiguration implements Ordered { (2)
private final Integer index
Duration period
Integer limit
RateLimitsConfiguration(@Parameter Integer index) { (3)
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) (1)
class RateLimitsConfiguration
constructor(@param:Parameter private val index: Int) (3)
: Ordered { (2)
var period: Duration? = null
var limit: Int? = null
override fun getOrder(): Int {
return index
}
}
1 | The list member of the annotation is set to true |
2 | Implement Ordered if order matters when retrieving the beans |
3 | The index is injected into the constructor |
4.7 Using @EachBean to Drive Configuration
The @EachProperty is a great way to drive dynamic configuration, but typically you want to inject that configuration into another bean that depends on it. Injecting a single instance with a hard coded qualifier is not a great solution, hence @EachProperty
is typically used in combination with @EachBean:
@Factory (1)
public class DataSourceFactory {
@EachBean(DataSourceConfiguration.class) (2)
DataSource dataSource(DataSourceConfiguration configuration) { (3)
URI url = configuration.getUrl();
return new DataSource(url);
}
@Factory (1)
class DataSourceFactory {
@EachBean(DataSourceConfiguration.class) (2)
DataSource dataSource(DataSourceConfiguration configuration) { (3)
URI url = configuration.getUrl()
return new DataSource(url)
}
@Factory (1)
class DataSourceFactory {
@EachBean(DataSourceConfiguration::class) (2)
internal fun dataSource(configuration: DataSourceConfiguration): DataSource { (3)
val url = configuration.url
return DataSource(url)
}
1 | The above example defines a bean Factory that will create instances of javax.sql.DataSource . |
2 | The @EachBean annotation is used to indicate that a new DataSource bean should be created for each DataSourceConfiguration defined in the previous section. |
3 | The DataSourceConfiguration instance is injected as a method argument and used to drive the configuration of each javax.sql.DataSource |
Note that @EachBean
requires that the parent bean has a @Named
qualifier, since the qualifier is inherited by each bean created by @EachBean
.
In other words, to retrieve the DataSource
created by test.datasource.one
you can do:
Collection<DataSource> beansOfType = applicationContext.getBeansOfType(DataSource.class);
assertEquals(2, beansOfType.size()); (1)
DataSource firstConfig = applicationContext.getBean(
DataSource.class,
Qualifiers.byName("one") (2)
);
when:
Collection<DataSource> beansOfType = applicationContext.getBeansOfType(DataSource.class)
assertEquals(2, beansOfType.size()) (1)
DataSource firstConfig = applicationContext.getBean(
DataSource.class,
Qualifiers.byName("one") (2)
)
val beansOfType = applicationContext.getBeansOfType(DataSource::class.java)
assertEquals(2, beansOfType.size.toLong()) (1)
val firstConfig = applicationContext.getBean(
DataSource::class.java,
Qualifiers.byName("one") (2)
)
1 | We demonstrate here that there are indeed two data sources. How can we get one in particular? |
2 | By using Qualifiers.byName("one") , we can select which of the two beans we’d like to reference. |
4.8 Immutable Configuration
Since 1.3, Micronaut supports the definition of immutable configuration.
There are two ways to define immutable configuration. The preferred way is to define an interface that is annotated with @ConfigurationProperties. For 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") (1)
public interface EngineConfig {
@Bindable(defaultValue = "Ford") (2)
@NotBlank (3)
String getManufacturer();
@Min(1L)
int getCylinders();
@NotNull
CrankShaft getCrankShaft(); (4)
@ConfigurationProperties("crank-shaft")
interface CrankShaft { (5)
Optional<Double> getRodLength(); (6)
}
}
import io.micronaut.context.annotation.ConfigurationProperties
import io.micronaut.core.bind.annotation.Bindable
import javax.validation.constraints.*
@ConfigurationProperties("my.engine") (1)
interface EngineConfig {
@Bindable(defaultValue = "Ford") (2)
@NotBlank (3)
String getManufacturer()
@Min(1L)
int getCylinders()
@NotNull
CrankShaft getCrankShaft() (4)
@ConfigurationProperties("crank-shaft")
static interface CrankShaft { (5)
Optional<Double> getRodLength() (6)
}
}
import io.micronaut.context.annotation.ConfigurationProperties
import io.micronaut.core.bind.annotation.Bindable
import javax.validation.constraints.*
import java.util.Optional
@ConfigurationProperties("my.engine") (1)
interface EngineConfig {
@get:Bindable(defaultValue = "Ford") (2)
@get:NotBlank (3)
val manufacturer: String
@get:Min(1L)
val cylinders: Int
@get:NotNull
val crankShaft: CrankShaft (4)
@ConfigurationProperties("crank-shaft")
interface CrankShaft { (5)
val rodLength: Double? (6)
}
}
1 | The @ConfigurationProperties annotation takes the configuration prefix and is declared on an interface |
2 | You can use @Bindable to set a default value if you want |
3 | Validation annotations can be used too |
4 | You can also specify references to other @ConfigurationProperties beans. |
5 | You can nest immutable configuration |
6 | Optional configuration can be indicated by returning an Optional or specifying @Nullable |
In this case what Micronaut does is provide a compilation time implementation that delegates all getters to call the getProperty(..)
method of the Environment interface.
This has the advantage that if the application’s configuration is refreshed (for example by invoking the /refresh
endpoint) then the injected interface will automatically see the new values.
If you try to specify any other abstract method other than a getter a compilation error will occur (default methods are supported). |
An alternative way to implement immutable configuration is to define a class and use the @ConfigurationInject annotation on a constructor of a @ConfigurationProperties or @EachProperty bean.
An example of an immutable configuration class can be seen below:
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") (1)
public class EngineConfig {
private final String manufacturer;
private final int cylinders;
private final CrankShaft crankShaft;
@ConfigurationInject (2)
public EngineConfig(
@Bindable(defaultValue = "Ford") @NotBlank String manufacturer, (3)
@Min(1L) int cylinders, (4)
@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 { (5)
private final Double rodLength; (6)
@ConfigurationInject
public CrankShaft(@Nullable Double rodLength) {
this.rodLength = rodLength;
}
public Optional<Double> getRodLength() {
return Optional.ofNullable(rodLength);
}
}
}
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") (1)
class EngineConfig {
private final String manufacturer
private final int cylinders
private final CrankShaft crankShaft
@ConfigurationInject (2)
EngineConfig(
@Bindable(defaultValue = "Ford") @NotBlank String manufacturer, (3)
@Min(1L) int cylinders, (4)
@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 { (5)
private final Double rodLength (6)
@ConfigurationInject
CrankShaft(@Nullable Double rodLength) {
this.rodLength = rodLength
}
Optional<Double> getRodLength() {
return Optional.ofNullable(rodLength)
}
}
}
import io.micronaut.context.annotation.*
import io.micronaut.core.bind.annotation.Bindable
import javax.validation.constraints.*
import java.util.Optional
@ConfigurationProperties("my.engine") (1)
data class EngineConfig @ConfigurationInject (2)
constructor(
@Bindable(defaultValue = "Ford") @NotBlank (3)
val manufacturer: String,
@Min(1L) (4)
val cylinders: Int,
@NotNull val crankShaft: CrankShaft) {
@ConfigurationProperties("crank-shaft")
data class CrankShaft @ConfigurationInject
constructor((5)
private val rodLength: Double? (6)
) {
fun getRodLength(): Optional<Double> {
return Optional.ofNullable(rodLength)
}
}
}
1 | The @ConfigurationProperties annotation takes the configuration prefix |
2 | The @ConfigurationInject annotation is defined on the constructor |
3 | You can use @Bindable to set a default value if you want |
4 | Validation annotations can be used too |
5 | You can nest immutable configuration |
6 | Optional configuration can be indicated with @Nullable |
The @ConfigurationInject annotation provides a hint to Micronaut to prioritize binding values from configuration instead of injecting beans.
Using this approach if you want the configuration to be refreshable then you must add the @Refreshable annotation to the class as well. This allows the bean to be re-created in the case of a runtime configuration refresh event. |
There are a few exceptions to this rule. Micronaut will not perform configuration binding for a parameter if one of these conditions is met:
-
The parameter is annotated with
@Value
(explicit binding) -
The parameter is annotated with
@Property
(explicit binding) -
The parameter is annotated with
@Parameter
(parameterized bean handling) -
The type of the parameter is annotated with a bean scope (such as
@Singleton
)
Once you have prepared a type safe configuration it can simply be injected into your objects like any other bean:
1 | Inject the EngineConfig bean |
2 | Use the configuration properties |
Configuration values can then be supplied when running the application. For example:
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());
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())
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)
The above example prints: "Ford Engine Starting V8 [rodLength=7B.0]"
4.9 JMX Support
Micronaut provides basic support for JMX.
For more information, see the documentation for the micronaut-jmx project.
5 Aspect Oriented Programming
Aspect-Oriented Programming (AOP) historically has had many incarnations and some very complicated implementations. Generally AOP can be thought of as a way to define cross cutting concerns (logging, transactions, tracing etc.) separate from application code in the form of aspects that define advice.
There are typically two forms of advice:
-
Around Advice - decorates a method or class
-
Introduction Advice - introduces new behaviour to a class.
In modern Java applications declaring advice typically takes the form of an annotation. The most well-known annotation advice in the Java world is probably @Transactional
which is used to demarcate transaction boundaries in Spring and Grails applications.
The disadvantage of traditional approaches to AOP is the heavy reliance on runtime proxy creation and reflection, which slows application performance, makes debugging harder and increases memory consumption.
Micronaut tries to address these concerns by providing a simple compile time AOP API that does not use reflection.
5.1 Around Advice
The most common type of advice you may want to apply is "Around" advice, which essentially allows you to decorate a methods behaviour.
Writing Around Advice
The first step to defining Around advice is to implement a MethodInterceptor. For example the following interceptor disallows parameters with null
values:
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> { (1)
@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(); (2)
if (nullParam.isPresent()) {
throw new IllegalArgumentException("Null parameter [" + nullParam.get().getKey() + "] not allowed"); (3)
} else {
return context.proceed(); (4)
}
}
}
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> { (1)
@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() (2)
if (nullParam.isPresent()) {
throw new IllegalArgumentException("Null parameter [" + nullParam.get().getKey() + "] not allowed") (3)
} else {
return context.proceed() (4)
}
}
}
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> { (1)
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() (2)
return if (nullParam.isPresent) {
throw IllegalArgumentException("Null parameter [" + nullParam.get().key + "] not allowed") (3)
} else {
context.proceed() (4)
}
}
}
1 | An interceptor implements the MethodInterceptor interface |
2 | The passed MethodInvocationContext is used to find the first parameter that is null |
3 | If a null parameter is found an exception is thrown |
4 | Otherwise proceed() is called to proceed with the method invocation. |
Micronaut AOP interceptors use no reflection which improves performance and reducing stack trace sizes, thus improving debugging. |
To put the new MethodInterceptor
to work the next step is to define an annotation that will trigger the MethodInterceptor
:
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) (1)
@Target({ElementType.TYPE, ElementType.METHOD}) (2)
@Around (3)
@Type(NotNullInterceptor.class) (4)
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) (1)
@Target([ElementType.TYPE, ElementType.METHOD]) (2)
@Around (3)
@Type(NotNullInterceptor.class) (4)
@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) (1)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FILE, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER) (2)
@Around (3)
@Type(NotNullInterceptor::class) (4)
annotation class NotNull
1 | The retention policy of the annotation should be RUNTIME |
2 | Generally you want to be able to apply advice at the class or method level so the target types are TYPE and METHOD |
3 | The Around annotation is added to tell Micronaut that the annotation is Around advice |
4 | The @Type annotation is used to configure which type implements the advice (in this case the previously defined NotNullInterceptor ) |
With the interceptor and annotation implemented you can then simply apply the annotation to the target classes:
@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")
}
}
Whenever the type NotNullExample
is injected into any class, a compile time generated proxy will instead be injected that decorates the appropriate method calls with the @NotNull
advice defined earlier. You can verify that the advice works by writing a test. The following test uses a JUnit ExpectedException
rule to verify the appropriate exception is thrown when an argument is null
:
@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()
}
Since Micronaut injection is done at compile time, generally the advice should be packaged in a dependent JAR file that is on the classpath when the above test is compiled and should not be in the same codebase since you don’t want the test to be compiled before the advice itself is compiled. |
Customizing Proxy Generation
The default behaviour of the Around annotation is to generate a proxy at compile time that is a subclass of the class being proxied. In other words, in the previous example a compile time subclass of the NotNullExample
class will be produced where methods that are proxied are decorated with interceptor handling and the original behaviour is invoked via a call to super
.
This behaviour is more efficient as only one instance of the bean is required, however depending on the use case you are trying to implement you may wish to alter this behaviour and the @Around
annotation supports various attributes that allow you to alter this behaviour including:
-
proxyTarget
(defaults tofalse
) - If set totrue
instead of a subclass that callssuper
, the proxy will delegate to the original bean instance -
hotswap
(defaults tofalse
) - Same asproxyTarget=true
, but in addition the proxy will implement HotSwappableInterceptedProxy which wraps each method call in aReentrantReadWriteLock
and allows swapping the target instance at runtime. -
lazy
(defaults tofalse
) - By default Micronaut will eagerly intialize the proxy target when the proxy is created. If set totrue
the proxy target will instead be resolved lazily for each method call.
AOP Advice on @Factory Beans
The semantics of AOP advice when applied to Bean Factories differs to regular beans, with the following rules applying:
Consider the following two examples:
@Factory
@Timed
@Factory
public class MyFactory {
@Prototype
public MyBean myBean() {
return new MyBean();
}
}
@Factory
@Timed
@Factory
class MyFactory {
@Prototype
MyBean myBean() {
return new MyBean()
}
}
@Factory
@Timed
@Factory
open class MyFactory {
@Prototype
open fun myBean(): MyBean {
return MyBean()
}
}
The above example will log the time it takes to create the MyBean
bean.
Now consider this example:
@Factory
@Factory
public class MyFactory {
@Prototype
@Timed
public MyBean myBean() {
return new MyBean();
}
}
@Factory
@Factory
class MyFactory {
@Prototype
@Timed
MyBean myBean() {
return new MyBean()
}
}
@Factory
@Factory
open class MyFactory {
@Prototype
@Timed
open fun myBean(): MyBean {
return MyBean()
}
}
The above example will log the time it takes to execute all of the public methods of the MyBean
bean, but not the bean creation.
The rationale for this behaviour is that you may at times wish to apply advice to a factory and at other times apply advice to the bean produced by the factory.
Note that there is currently no way to apply advice at the method level to a @Factory bean and all advice for factories must be applied at the type level. You can control which methods have advice applied by defining methods as non-public (non-public methods do not have advice applied).
5.2 Introduction Advice
Introduction advice is distinct from Around advice in that it involves providing an implementation instead of decorating.
Examples of introduction advice include things like GORM or Spring Data that will both automatically implement persistence logic for you.
Micronaut’s Client annotation is another example of introduction advice where Micronaut will, at compile time, implement HTTP client interfaces for you.
The way you implement Introduction advice is very similar to how you implement Around advice.
You start off by defining an annotation that will power the introduction advice. As an example, say you want to implement advice that will return a stubbed value for every method in an interface (a common requirement in testing frameworks). Consider the following @Stub
annotation:
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 (1)
@Type(StubIntroduction.class) (2)
@Bean (3)
@Documented
@Retention(RUNTIME)
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE, ElementType.METHOD})
public @interface Stub {
String value() default "";
}
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 (1)
@Type(StubIntroduction.class) (2)
@Bean (3)
@Documented
@Retention(RUNTIME)
@Target([ElementType.TYPE, ElementType.ANNOTATION_TYPE, ElementType.METHOD])
@interface Stub {
String value() default ""
}
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 (1)
@Type(StubIntroduction::class) (2)
@Bean (3)
@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 = "")
1 | The introduction advice is annotated with Introduction |
2 | The Type annotation is used to refer to the implementor of the advice. In this case StubIntroduction |
3 | The Bean annotation is added so that all types annotated with @Stub become beans |
The StubIntroduction
class referred to in the previous example must then implement the MethodInterceptor interface, just like around advice.
The following is an example implementation:
import io.micronaut.aop.*;
import javax.inject.Singleton;
@Singleton
public class StubIntroduction implements MethodInterceptor<Object,Object> { (1)
@Override
public Object intercept(MethodInvocationContext<Object, Object> context) {
return context.getValue( (2)
Stub.class,
context.getReturnType().getType()
).orElse(null); (3)
}
}
import io.micronaut.aop.MethodInterceptor
import io.micronaut.aop.MethodInvocationContext
import javax.inject.Singleton
@Singleton
class StubIntroduction implements MethodInterceptor<Object,Object> { (1)
@Override
Object intercept(MethodInvocationContext<Object, Object> context) {
return context.getValue( (2)
Stub.class,
context.getReturnType().getType()
).orElse(null) (3)
}
}
import io.micronaut.aop.MethodInterceptor
import io.micronaut.aop.MethodInvocationContext
import javax.inject.Singleton
@Singleton
class StubIntroduction : MethodInterceptor<Any, Any> { (1)
override fun intercept(context: MethodInvocationContext<Any, Any>): Any? {
return context.getValue<Any>( (2)
Stub::class.java,
context.returnType.type
).orElse(null) (3)
}
}
1 | The class is annotated with @Singleton and implements the MethodInterceptor interface |
2 | The value of the @Stub annotation is read from the context and an attempt made to convert the value to the return type |
3 | Otherwise null is returned |
To now use this introduction advice in an application you simply annotate your abstract classes or interfaces with @Stub
:
@Stub
public interface StubExample {
@Stub("10")
int getNumber();
LocalDateTime getDate();
}
@Stub
interface StubExample {
@Stub("10")
int getNumber()
LocalDateTime getDate()
}
@Stub
interface StubExample {
@get:Stub("10")
val number: Int
val date: LocalDateTime?
}
All abstract methods will delegate to the StubIntroduction
class to be implemented.
The following test demonstrates the behaviour or StubIntroduction
:
StubExample stubExample = applicationContext.getBean(StubExample.class);
assertEquals(10, stubExample.getNumber());
assertNull(stubExample.getDate());
when:
StubExample stubExample = applicationContext.getBean(StubExample.class)
then:
stubExample.getNumber() == 10
stubExample.getDate() == null
val stubExample = applicationContext.getBean(StubExample::class.java)
stubExample.number.toLong().shouldBe(10)
stubExample.date.shouldBe(null)
Note that if the introduction advice cannot implement the method the proceed
method of the MethodInvocationContext should be called. This gives the opportunity for other introduction advice interceptors to implement the method, otherwise a UnsupportedOperationException
will be thrown if no advice can implement the method.
In addition, if multiple introduction advice are present you may wish to override the getOrder()
method of MethodInterceptor to control the priority of advise.
The following sections cover core advice types that are built into Micronaut and provided by the framework.
5.3 Method Adapter Advice
There are sometimes cases where you want to introduce a new bean based on the presence of an annotation on a method. An example of this case is the @EventListener annotation which for each method annotated with @EventListener produces an implementation of ApplicationEventListener that invokes the annotated method.
For example the following snippet will run the logic contained within the method when the ApplicationContext starts up:
import io.micronaut.context.event.StartupEvent;
import io.micronaut.runtime.event.annotation.EventListener;
...
@EventListener
void onStartup(StartupEvent event) {
// startup logic here
}
The presence of the @EventListener annotation causes Micronaut to create a new class that implements the ApplicationEventListener and invokes the onStartup
method defined in the bean above.
The actual implementation of the @EventListener is trivial, it simply uses the @Adapter annotation to specify which SAM (single abstract method) type it adapts:
import io.micronaut.aop.Adapter;
import io.micronaut.context.event.ApplicationEventListener;
import io.micronaut.core.annotation.Indexed;
import java.lang.annotation.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Documented
@Retention(RUNTIME)
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
@Adapter(ApplicationEventListener.class) (1)
@Indexed(ApplicationEventListener.class)
public @interface EventListener {
}
1 | The @Adapter annotation is used to indicate which SAM type to adapt. In this case ApplicationEventListener. |
Micronaut will also automatically align the generic types for the SAM interface if they are specified. |
Using this mechanism you can define custom annotations that use the @Adapter annotation and a SAM interface to automatically implement beans for you at compile time.
5.4 Validation Advice
Validation advice is one of the most common advice types you are likely to want to incorporate into your application.
Validation advice is built on Bean Validation JSR 380.
JSR 380 is a specification of the Java API for bean validation which ensures that the
properties of a bean meet specific criteria, using javax.validation
annotations such as @NotNull
, @Min
, and @Max
.
Micronaut provides native support for the javax.validation
annotations with the micronaut-validation
dependency:
implementation("io.micronaut:micronaut-validation")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-validation</artifactId>
</dependency>
Or full JSR 380 compliance with the micronaut-hibernate-validator
dependency:
implementation("io.micronaut:micronaut-hibernate-validator")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-hibernate-validator</artifactId>
</dependency>
See the section on Bean Validation for more information on how to apply validation rules to your bean classes.
5.5 Cache Advice
Similar to Spring and Grails, Micronaut provides a set of caching annotations within the io.micronaut.cache package.
The CacheManager interface allows different cache implementations to be plugged in as necessary.
The SyncCache interface provides a synchronous API for caching, whilst the AsyncCache API allows non-blocking operation.
Cache Annotations
The following cache annotations are supported:
-
@Cacheable - Indicates a method is cacheable within the given cache name
-
@CachePut - Indicates that the return value of a method invocation should be cached. Unlike
@Cacheable
the original operation is never skipped. -
@CacheInvalidate - Indicates the invocation of a method should cause the invalidation of one or many caches.
By using one of the annotations the CacheInterceptor is activated which in the case of @Cacheable
will cache the return result of the method.
If the return type of the method is a non-blocking type (either CompletableFuture or an instance of Publisher the emitted result will be cached.
In addition if the underlying Cache implementation supports non-blocking cache operations then cache values will be read from the cache without blocking, resulting in the ability to implement completely non-blocking cache operations.
Configuring Caches
By default Caffeine is used for cache definitions which can be configured via application configuration. For example with application.yml
:
micronaut:
caches:
my-cache:
maximum-size: 20
The above example will configure a cache called "my-cache" with a maximum size of 20.
Naming Caches
Names of caches under |
To configure a weigher to be used with the maximumWeight
configuration, create a bean that implements io.micronaut.caffeine.cache.Weigher
. To associate a given weigher with only a specific cache, annotate the bean with @Named(<cache name>)
. Weighers without a named qualifier will apply to all caches that don’t have a named weigher. If no beans are found, a default implementation will be used.
See the configuration reference for all available configuration options.
Dynamic Cache Creation
For use cases where caches cannot be configured ahead of time, a DynamicCacheManager 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.
5.6 Retry Advice
In distributed systems and Microservice environments, failure is something you have to plan for and it is pretty common to want to attempt to retry an operation if it fails. If first you don’t succeed try again!
With this in mind Micronaut comes with a Retryable annotation out of the box that is integrated into the container.
Simple Retry
The simplest form of retry is just to add the @Retryable
annotation to any type or method. The default behaviour of @Retryable
is to retry 3 times with an exponential delay of 1 second between each retry. (first attempt with 1s delay, second attempt with 2s delay, third attempt with 3s delay)
For example:
@Retryable
public List<Book> listBooks() {
// ...
@Retryable
List<Book> listBooks() {
// ...
@Retryable
open fun listBooks(): List<Book> {
// ...
With the above example if the listBooks()
method throws a RuntimeException it will be retried until the maximum number of attempts is reached.
The multiplier
value of the @Retryable
annotation can be used to configure a multiplier used to calculate the delay between retries, thus allowing exponential retry support.
Note also that the @Retryable
annotation can be applied on interfaces and the behaviour will be inherited through annotation metadata. The implication of this is that @Retryable
can be used in combination with Introduction Advice such as the HTTP Client annotation.
To customize retry behaviour you can set the attempts
and delay
members, For example to configure 5 attempts with a 2 second delay:
@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 {
// ...
Notice how both attempts
and delay
are defined as strings. This is to support configurability through annotation metadata. For example you can allow the retry policy to be configured using property placeholder resolution:
@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 {
// ...
With the above in place if book.retry.attempts
is specified in configuration it wil be bound the value of the attempts
member of the @Retryable
annotation via annotation metadata.
Reactive Retry
@Retryable
advice can also be applied to methods that return reactive types, such as an RxJava Flowable
. For example:
@Retryable
public Flowable<Book> streamBooks() {
// ...
@Retryable
Flowable<Book> streamBooks() {
// ...
@Retryable
open fun streamBooks(): Flowable<Book> {
// ...
In this case @Retryable
advice will apply the retry policy to the reactive type.
Circuit Breaker
In a Microservice environment retry is useful, but in some cases excessive retries can overwhelm the system as clients repeatedly re-attempt failing operations.
The Circuit Breaker pattern is designed to resolve this issue by essentially allowing a certain number of failing requests and then opening a circuit that remains open for a period before allowing any additional retry attempts.
The CircuitBreaker annotation is a variation of the @Retryable
annotation that supports a reset
member that indicates how long the circuit should remain open before it is reset (the default is 20 seconds).
@CircuitBreaker(reset = "30s")
public List<Book> findBooks() {
// ...
@CircuitBreaker(reset = "30s")
List<Book> findBooks() {
// ...
@CircuitBreaker(reset = "30s")
open fun findBooks(): List<Book> {
// ...
The above example will retry to findBooks
method 3 times and then open the circuit for 30 seconds, rethrowing the original exception and preventing potential downstream traffic such as HTTP requests and I/O operations flooding the system.
Bean Creation Retry
As mentioned previously, @Retryable
advice is integrated right at the container level. This is useful as it is common problem in Microservices and environments like Docker where there may be a delay in services becoming available.
The following snippet is taken from the Neo4j driver support and demonstrates how bean creation can be wrapped in retry support:
@Factory (1)
public class Neo4jDriverFactory {
...
@Retryable(ServiceUnavailableException.class) (2)
@Bean(preDestroy = "close")
public Driver buildDriver() {
...
}
}
1 | A factory bean is created that defines methods that create beans |
2 | The @Retryable annotation is used to catch ServiceUnavailableException and retry creating the driver before failing startup. |
Retry Events
You can register RetryEventListener instances as beans in order to listen for RetryEvent events that are published every time an operation is retried.
In addition, you can register event listeners for CircuitOpenEvent, when a circuit breaker circuit is opened, or CircuitClosedEvent for when a circuit is closed.
5.7 Scheduled Tasks
Like Spring and Grails, Micronaut features a Scheduled annotation that can be used for scheduling background tasks.
Using the @Scheduled Annotation
The Scheduled annotation can be added to any method of a bean and you should set either the fixedRate
, fixedDelay
or cron
members.
Remember that the scope of the bean has an impact on behaviour. a @Singleton bean will share state (the fields of the instance) each time the scheduled method is executed, while for a @Prototype bean a new instance is created for each execution.
|
Scheduling at a Fixed Rate
To schedule a task at a fixed rate, use the fixedRate
member. For example:
@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()")
}
The task above will execute every 5 minutes.
Scheduling with a Fixed Delay
To schedule a task so that it runs 5 minutes after the termination of the previous task use the fixedDelay
member. For example:
@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()")
}
Scheduling a Cron Task
To schedule a Cron task use the cron
member:
@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()")
}
The above example will run the task every Monday morning at 10:15AM for the time zone of the server.
Scheduling with only an Initial Delay
To schedule a task so that it runs a single time after the server starts, use the initialDelay
member:
@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()")
}
The above example will only run a single time 1 minute after the server starts.
Programmatically Scheduling Tasks
If you wish to programmatically schedule tasks, then you can use the TaskScheduler bean which can be injected as follows:
@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
If you wish to make your application’s tasks configurable then you can use annotation metadata and property placeholder configuration to do so. For example:
@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()")
}
The above example allows the task execution frequency to be configured with the property my.task.rate
and the initial delay to be configured with the property my.task.delay
.
Configuring the Scheduled Task Thread Pool
Tasks executed by @Scheduled
are by default run on a ScheduledExecutorService that is configured to have twice the number of threads as available processors.
You can configure this thread pool as desired using application.yml
, for example:
micronaut:
executors:
scheduled:
type: scheduled
core-pool-size: 30
Property | Type | Description |
---|---|---|
|
java.lang.Integer |
|
|
Sets the executor type. Default value (SCHEDULED). |
|
|
java.lang.Integer |
Sets the parallelism for WORK_STEALING. Default value (Number of processors available to the Java virtual machine). |
|
java.lang.Integer |
Sets the core pool size for SCHEDULED. Default value (2 * Number of processors available to the Java virtual machine). |
|
java.lang.Class |
Sets the thread factory class. |
|
java.lang.Integer |
Sets the number of threads for FIXED. Default value (2 * Number of processors available to the Java virtual machine). |
Handling Exceptions
By default Micronaut includes a DefaultTaskExceptionHandler bean that implements the TaskExceptionHandler 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 own TaskExceptionHandler and annotate it with @Replaces(DefaultTaskExceptionHandler.class)
.
5.8 Bridging Spring AOP
Although Micronaut’s design is based on a compile time approach and does not rely on Spring dependency injection, there is still a lot of value in the Spring ecosystem that does not depend directly on the Spring container.
You may wish to use existing Spring projects within Micronaut and configure beans to be used within Micronaut.
You may also wish to leverage existing AOP advice from Spring. One example of this is Spring’s support for declarative transactions with @Transactional
.
Micronaut provides support for Spring based transaction management without requiring Spring itself. You simply need to add the spring
module to your application dependencies:
implementation("io.micronaut:micronaut-spring")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-spring</artifactId>
</dependency>
If you use Micronaut’s Hibernate support you already get this dependency and a HibernateTransactionManager is configured for you.
|
This is done by defining a Micronaut @Transactional annotation that uses @AliasFor in a manner that every time you set a value with @Transactional it aliases the value to equivalent value in Spring’s version of @Transactional
.
The benefit here is you can use Micronaut’s compile-time, reflection free AOP to declare programmatic Spring transactions. For example:
import io.micronaut.spring.tx.annotation.*;
...
@Transactional
public Book saveBook(String title) {
...
}
Micronaut’s version of @Transactional is also annotated with @Blocking ensuring that all methods annotated with use the I/O thread pool when executing within the HTTP server |
6 The HTTP Server
Using the CLI
If you are creating your project using the Micronaut CLI’s |
Micronaut includes both non-blocking HTTP server and client APIs based on Netty.
The design of the HTTP server in Micronaut is optimized for interchanging messages between Microservices, typically in JSON, and is not intended as a full server-side MVC framework. For example, there is currently no support for server-side views or features typical of a traditional server-side MVC framework.
The goal of the HTTP server is to make it as easy as possible to expose APIs that can be consumed by HTTP clients, whatever language they may be written in. To use the HTTP server you must have the http-server-netty
dependency on your classpath.
implementation("io.micronaut:micronaut-http-server-netty")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-http-server-netty</artifactId>
</dependency>
A "Hello World" server application can be seen below:
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
@Controller("/hello") (1)
public class HelloController {
@Get(produces = MediaType.TEXT_PLAIN) (2)
public String index() {
return "Hello World"; (3)
}
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
@Controller('/hello') (1)
class HelloController {
@Get(produces = MediaType.TEXT_PLAIN) (2)
String index() {
'Hello World' (3)
}
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
@Controller("/hello") (1)
class HelloController {
@Get(produces = [MediaType.TEXT_PLAIN]) (2)
fun index(): String {
return "Hello World" (3)
}
}
1 | The class is defined as a controller with the @Controller annotation mapped to the path /hello |
2 | The method will respond to a GET request to /hello and returns a response with a text/plain content type |
3 | By defining method called index , by convention the method is exposed via the /hello URI |
6.1 Running the Embedded Server
To run the server simply create an Application
class with a static void main
method. For example:
import io.micronaut.runtime.Micronaut;
public class Application {
public static void main(String[] args) {
Micronaut.run(Application.class);
}
}
import io.micronaut.runtime.Micronaut
class Application {
static void main(String... args) {
Micronaut.run Application.class
}
}
import io.micronaut.runtime.Micronaut
object Application {
@JvmStatic
fun main(args: Array<String>) {
Micronaut.run(Application.javaClass)
}
}
To run the application from a unit test you can use the EmbeddedServer interface:
import io.micronaut.context.annotation.Property;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.runtime.server.EmbeddedServer;
import io.micronaut.test.annotation.MicronautTest;
import org.junit.jupiter.api.Test;
import javax.inject.Inject;
import static org.junit.jupiter.api.Assertions.assertEquals;
@MicronautTest
public class HelloControllerSpec {
@Inject
EmbeddedServer server; (1)
@Inject
@Client("/")
HttpClient client; (2)
@Test
void testHelloWorldResponse() {
String response = client.toBlocking() (3)
.retrieve(HttpRequest.GET("/hello"));
assertEquals("Hello World", response); //) (4)
}
}
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.runtime.server.EmbeddedServer
import io.micronaut.test.annotation.MicronautTest
import spock.lang.Specification
import javax.inject.Inject
@MicronautTest
class HelloControllerSpec extends Specification {
@Inject
EmbeddedServer embeddedServer (1)
@Inject
@Client("/")
HttpClient client (2)
void "test hello world response"() {
expect:
client.toBlocking() (3)
.retrieve(HttpRequest.GET('/hello')) == "Hello World" (4)
}
}
import io.micronaut.context.annotation.Property
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.runtime.server.EmbeddedServer
import io.micronaut.test.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Test
import javax.inject.Inject
@MicronautTest
class HelloControllerSpec {
@Inject
lateinit var server: EmbeddedServer (1)
@Inject
@field:Client("/")
lateinit var client: HttpClient (2)
@Test
fun testHelloWorldResponse() {
val rsp: String = client.toBlocking() (3)
.retrieve("/hello")
assertEquals("Hello World", rsp) (4)
}
}
1 | The EmbeddedServer is run and Spock’s @AutoCleanup annotation ensures the server is stopped after the specification completes. |
2 | The EmbeddedServer interface provides the URL of the server under test which runs on a random port. |
3 | The test uses the Micronaut http client to make the call |
4 | The retrieve method returns the response of the controller as a String |
Without explicit port configuration, the port will be 8080, unless the application is run under the test environment. In that case the port will be random. When the application context is started from the context of a test class, the test environment is added automatically.
|
6.2 Running Server on a Specific Port
By default the server runs on port 8080. However, you can set the server to run on a specific port:
micronaut:
server:
port: 8086
This is also possible to be configured from an environment variable: MICRONAUT_SERVER_PORT=8086
|
To run on a random port:
micronaut:
server:
port: -1
If an explicit port is set, that may cause tests to fail because multiple servers are starting simultaneously on the same port. To prevent that, set the port to be random in the test environment configuration. |
6.3 HTTP Routing
The @Controller annotation used in the previous section is one of several annotations that allow you to control the construction of HTTP routes.
URI Paths
The value of the @Controller
annotation is a RFC-6570 URI template you can therefore embed URI variables within the path using the syntax defined by the URI template specification.
Many other frameworks, including Spring, implement the URI template specification |
The actual implementation is handled by the UriMatchTemplate class, which extends UriTemplate.
You can use this class explicitly within your application to build URIs. For example:
UriMatchTemplate template = UriMatchTemplate.of("/hello/{name}");
assertTrue(template.match("/hello/John").isPresent()); (1)
assertEquals("/hello/John", template.expand( (2)
Collections.singletonMap("name", "John")
));
given:
UriMatchTemplate template = UriMatchTemplate.of("/hello/{name}")
expect:
template.match("/hello/John").isPresent() (1)
template.expand(["name": "John"]) == "/hello/John" (2)
val template = UriMatchTemplate.of("/hello/{name}")
assertTrue(template.match("/hello/John").isPresent) (1)
assertEquals("/hello/John", template.expand(mapOf("name" to "John"))) (2)
1 | The match method can be used to match a path |
2 | The expand method can be used to expand a template into a URI. |
If you have a requirement to build paths to include in your responses you can use UriTemplate to do so.
URI Path Variables
URI variables can be referenced via method arguments. For example:
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;
@Controller("/issues") (1)
public class IssuesController {
@Get("/{number}") (2)
public String issue(@PathVariable Integer number) { (3)
return "Issue # " + number + "!"; (4)
}
}
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.PathVariable
@Controller("/issues") (1)
class IssuesController {
@Get("/{number}") (2)
String issue(@PathVariable Integer number) { (3)
"Issue # " + number + "!" (4)
}
}
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.PathVariable
@Controller("/issues") (1)
class IssuesController {
@Get("/{number}") (2)
fun issue(@PathVariable number: Int): String { (3)
return "Issue # $number!" (4)
}
}
1 | The @Controller annotation is specified with a base URI of /issues |
2 | The Get annotation is used to map the method to an HTTP GET with a URI variable embedded in the URI called number |
3 | The method argument can be optionally annotated with PathVariable |
4 | The value of the URI variable is referenced in the implementation |
Micronaut will map the URI /issues/{number}
for the above controller. We can assert this is the case by writing a set of unit tests:
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 (1)
public static void setupServer() {
server = ApplicationContext.run(EmbeddedServer.class);
client = server
.getApplicationContext()
.createBean(HttpClient.class, server.getURL());
}
@AfterClass (2)
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"); (3)
assertNotNull(body);
assertEquals("Issue # 12!", body); (4)
}
@Test
public void testShowWithInvalidInteger() {
HttpClientResponseException e =Assertions.assertThrows(HttpClientResponseException.class, () ->
client.toBlocking().exchange("/issues/hello"));
assertEquals(400, e.getStatus().getCode()); (5)
}
@Test
public void testIssueWithoutNumber() {
HttpClientResponseException e = Assertions.assertThrows(HttpClientResponseException.class, () ->
client.toBlocking().exchange("/issues/"));
assertEquals(404, e.getStatus().getCode()); (6)
}
}
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 (2)
EmbeddedServer embeddedServer = ApplicationContext.run(EmbeddedServer) (1)
@Shared
@AutoCleanup (2)
HttpClient client = HttpClient.create(embeddedServer.URL) (1)
void "test issue"() {
when:
String body = client.toBlocking().retrieve("/issues/12") (3)
then:
body != null
body == "Issue # 12!" (4)
}
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 (5)
}
void "/issues/{number} without number responds 404"() {
when:
client.toBlocking().exchange("/issues/")
then:
HttpClientResponseException e = thrown(HttpClientResponseException)
e.status.code == 404 (6)
}
}
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( (2)
ApplicationContext.run(EmbeddedServer::class.java) (1)
)
val client = autoClose( (2)
embeddedServer.applicationContext.createBean(RxHttpClient::class.java, embeddedServer.getURL()) (1)
)
init {
"test issue" {
val body = client.toBlocking().retrieve("/issues/12") (3)
body shouldNotBe null
body shouldBe "Issue # 12!" (4)
}
"test issue with invalid integer" {
val e = shouldThrow<HttpClientResponseException> { client.toBlocking().exchange<Any>("/issues/hello") }
e.status.code shouldBe 400 (5)
}
"test issue without number" {
val e = shouldThrow<HttpClientResponseException> { client.toBlocking().exchange<Any>("/issues/") }
e.status.code shouldBe 404 (6)
}
}
}
1 | The embedded server and http client is being started |
2 | The server and client will be cleaned up after all of the tests have finished |
3 | The tests sends a request to the URI /issues/12 |
4 | And then asserts the response is "Issue # 12" |
5 | Another test asserts a 400 response is returned when an invalid number is sent in the URL |
6 | Another test asserts a 404 response is returned when no number is provided in the URL. The variable being present is required in order for the route to be executed. |
Note that the URI template in the previous example requires that the number
variable is specified. You can specify optional URI templates with the syntax: /issues{/number}
and by annotating the number
parameter with @Nullable
.
The following table provides some examples of URI templates and what they match:
Template | Description | Matching URI |
---|---|---|
|
Simple match |
|
|
A variable of 2 characters max |
|
|
An optional URI variable |
|
|
An optional URI variable with regex |
|
|
Optional query parameters |
|
|
Regex path match with extension |
|
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
Each of the routing annotations support multiple URI templates. For each template, a route will be created. This feature is useful for example to change the path of the API and leaving the existing path as is for backwards compatibility. For example:
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
@Controller("/hello")
public class BackwardCompatibleController {
@Get(uris = {"/{name}", "/person/{name}"}) (1)
public String hello(String name) { (2)
return "Hello, " + name;
}
}
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
@Controller("/hello")
class BackwardCompatibleController {
@Get(uris = ["/{name}", "/person/{name}"]) (1)
String hello(String name) { (2)
"Hello, " + name
}
}
@Controller("/hello")
class BackwardCompatibleController {
@Get(uris = ["/{name}", "/person/{name}"]) (1)
fun hello(name: String): String { (2)
return "Hello, $name"
}
}
1 | Specify multiple templates |
2 | Bind to the template arguments as normal |
Route validation is more complicated with multiple templates. If a variable that would normally be required does not exist in all templates, then that variable is considered optional since it may not exist for every execution of the method. |
Building Routes Programmatically
If you prefer to not use annotations and declare all of your routes in code then never fear, Micronaut has a flexible RouteBuilder API that makes it a breeze to define routes programmatically.
To start off with you should subclass DefaultRouteBuilder and then simply inject the controller you wish to route to into the method and define your routes:
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 { (1)
public MyRoutes(ExecutionHandleLocator executionHandleLocator, UriNamingStrategy uriNamingStrategy) {
super(executionHandleLocator, uriNamingStrategy);
}
@Inject
void issuesRoutes(IssuesController issuesController) { (2)
GET("/issues/show/{number}", issuesController, "issue", Integer.class); (3)
}
}
import io.micronaut.web.router.GroovyRouteBuilder
import javax.inject.Inject
import javax.inject.Singleton
@Singleton
class MyRoutes extends GroovyRouteBuilder { (1)
MyRoutes(ExecutionHandleLocator executionHandleLocator, UriNamingStrategy uriNamingStrategy, ConversionService<?> conversionService) {
super(executionHandleLocator, uriNamingStrategy, conversionService)
}
@Inject
void issuesRoutes(IssuesController issuesController) { (2)
GET("/issues/show/{number}", issuesController.&issue) (3)
}
}
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) { (1)
@Inject
fun issuesRoutes(issuesController: IssuesController) { (2)
GET("/issues/show/{number}", issuesController, "issue", Int::class.java) (3)
}
}
1 | Route definitions should subclass DefaultRouteBuilder |
2 | Use @Inject to inject a method with the controller you want to route to |
3 | Use methods such as GET to route to controller methods. Note that even though the issues controller is being used, the route has no knowledge of its @Controller annotation and thus the full path must be specified. |
Unfortunately due to type erasure a Java method lambda reference cannot be used with the API. For Groovy there is a GroovyRouteBuilder class which can be subclassed that allows passing Groovy method references.
|
Route Compile Time Validation
Micronaut supports validating route arguments at compile time with the validation library. To get started simply add the validation
dependency to your build:
annotationProcessor "io.micronaut:micronaut-validation" // Java only
kapt "io.micronaut:micronaut-validation" // Kotlin only
compile "io.micronaut:micronaut-validation"
With the correct dependency on your classpath, route arguments will automatically be checked at compile time. The compilation will fail if any of the following conditions are met:
-
The URI template contains a variable that is optional, but the method parameter is not annotated with
@Nullable
or is anjava.util.Optional
.
An optional variable is one that will allow the route to match a URI even if the value is not present. For example /foo{/bar}
will match requests to /foo
and /foo/abc
. The non optional variant would be /foo/{bar}
. See the URI Path Variables section for more information.
-
The URI template contains a variable that is missing from the method arguments.
To disable route compile time validation, set the system property -Dmicronaut.route.validation=false . For Java and Kotlin users using Gradle, the same effect can be achieved by removing the validation dependency from the annotationProcessor /kapt scope.
|
Routing non-standard HTTP methods
It may be necessary to support a non-standard HTTP method for a client or server. Specifications like RFC-4918 Webdav require additional methods like REPORT or LOCK for example. To support that use case the @CustomHttpMethod annotation can be used.
@CustomHttpMethod(method = "LOCK", value = "/{name}")
String lock(String name)
The annotation can be used anywhere any of the standard method annotations can be used, including controllers and declarative http clients.
6.4 Simple Request Binding
The examples in the previous section demonstrates how Micronaut allows you to bind method parameters from URI path variables. This section will discuss how to bind arguments from other parts of the request.
Binding Annotations
All of the binding annotations support customization of the name of the variable being bound from with their name
member.
The following table summarizes the annotations, their purpose and provides an example:
Annotation | Description | Example |
---|---|---|
Binds from the body of the request |
|
|
Binds a parameter from a cookie |
|
|
Binds a parameter from an HTTP header |
|
|
Binds from a request query parameter |
|
|
Binds from a part of a multipart request |
|
|
Binds from an attribute of the request. Attributes are typically created in filters |
|
|
Binds from the path of the request |
|
|
Binds any Bindable value to single Bean object |
|
When a value is not specified to any binding annotation then the parameter name is used. In other words the following two methods are equivalent and both bind from a cookie called myCookie
:
@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 {
// ...
}
Because hyphens are not allowed in variable names it may be necessary to set the name in the annotation. The following two definitions are equivalent:
@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
Instead of binding from a single section of the request, it may be desirable to bind all query values for example to a POJO. This can be achieved by using the exploded operator (?pojo*
) in the URI template. For example:
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
Instead of binding just Query values, it is also possible to bind any Bindable value to POJO (e.g. when you want to bind HttpRequest
, @PathVariable
, @QueryValue
and @Header
to single POJO).
This can be achieved with @RequestBean
annotation and custom Bean class that has fields with Bindable annotations or fields that can be bound by type (e.g. HttpRequest, BasicAuth, Authentication etc.).
For example:
@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)
Bean class has to be introspected with @Introspected
. It can be one of:
-
Mutable Bean class with setters and getters
-
Immutable Bean class with getters and all argument constructor (or
@Creator
annotation on a constructor or static method). Arguments of constructor have to match field names so object can be constructed without reflection.
Since Java does not retain argument names in the byte code, you have to compile code with -parameters in case you want to use Immutable Bean class from another Jar.
Another option is to extend Bean class in your source.
|
Bindable Types
Generally any type that can be converted from a String representation to a Java type via the ConversionService API can be bound to.
This includes most common Java types, however additional TypeConverter instances can be registered simply be creating @Singleton
beans of type TypeConverter
.
The handling of nullability deserves special mention. Consider for example the following example:
@Get("/headerInferred")
public String headerInferred(@Header String contentType) {
// ...
}
@Get("/headerInferred")
String headerInferred(@Header String contentType) {
// ...
}
@Get("/headerInferred")
fun headerInferred(@Header contentType: String): String {
// ...
}
In this case if the HTTP header Content-Type
is not present in the request the route is considered invalid, since it cannot be satisfied and a HTTP 400 BAD REQUEST
is returned.
If you wish for the Content-Type
header to be optional, you can instead write:
@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? {
// ...
}
An null string will be passed if the header is absent from the request.
java.util.Optional can also be used, however that is discouraged for method parameters.
|
Additionally, any DateTime
that conforms to RFC-1123 can be bound to a parameter, alternatively the format can be customized with the Format annotation:
@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
Some parameters are recognized by their type instead of their annotation. The following table summarizes the parameter types, their purpose, and provides an example:
Type | Description | Example |
---|---|---|
Allows binding of basic authorization credentials |
|
Variables resolution
Micronaut will try to populate method arguments in the following order:
-
URI variables like
/{id}
. -
If the request is a
GET
request from query parameters (ie.?foo=bar
). -
If there is a
@Body
and request allows the body, bind the body to it. -
if the request can have a body and no
@Body
is defined then try parse the body (either JSON or form data) and bind the method arguments from the body. -
Finally, if the method arguments cannot be populated return
400 BAD REQUEST
.
6.5 Host Resolution
You may need to resolve the host name of the current server. Micronaut ships with an implementation of the HttpHostResolver interface.
The default implementation will look for host information in the following places in order:
-
The supplied configuration
-
The
Forwarded
header -
The
X-Forwarded-
headers -
The
Host
header -
The properties on the request URI
-
The properties on the embedded server URI
The behavior of which headers to pull the relevant data can be changed with the following configuration:
Property | Type | Description |
---|---|---|
|
java.lang.String |
The header name that stores the host |
|
java.lang.String |
The header name that stores the protocol |
|
java.lang.String |
The header name that stores the port |
|
boolean |
True if the host header supports a port |
6.6 Client IP Address
You may need to resolve the originating IP address of an HTTP Request. Micronaut ships with an implementation of HttpClientAddressResolver.
The default implementation will resolve the client address in the following places in order:
-
The configured header
-
The
Forwarded
header -
The
X-Forwarded-For
header -
The remote address on the request
The first priority header name can be configured with micronaut.server.client-address-header
.
6.7 The HttpRequest and HttpResponse
If you need more control over request processing then you can instead write a method that receives the complete HttpRequest.
In fact, there are several higher level interfaces that can be bound to method parameters of controllers. These include:
Interface | Description | Example |
---|---|---|
The full |
|
|
All HTTP headers present in the request |
|
|
All HTTP parameters (either from URI variables or request parameters) present in the request |
|
|
All the Cookies present in the request |
|
The HttpRequest should be declared parametrized with a concrete generic type if the request body is needed, e.g. HttpRequest<MyClass> request . The body may not be available from the request otherwise.
|
In addition, for full control over the emitted HTTP response you can use the static factory methods of the HttpResponse class which return a MutableHttpResponse.
The following example implements the previous MessageController
example using the HttpRequest and HttpResponse objects:
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") (1)
public HttpResponse<String> hello(HttpRequest<?> request) {
String name = request.getParameters()
.getFirst("name")
.orElse("Nobody"); (2)
return HttpResponse.ok("Hello " + name + "!!")
.header("X-My-Header", "Foo"); (3)
}
}
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") (1)
HttpResponse<String> hello(HttpRequest<?> request) {
String name = request.getParameters()
.getFirst("name")
.orElse("Nobody") (2)
HttpResponse.ok("Hello " + name + "!!")
.header("X-My-Header", "Foo") (3)
}
}
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") (1)
fun hello(request: HttpRequest<*>): HttpResponse<String> {
val name = request.parameters
.getFirst("name")
.orElse("Nobody") (2)
return HttpResponse.ok("Hello $name!!")
.header("X-My-Header", "Foo") (3)
}
}
1 | The method is mapped to the URI /hello and accepts a HttpRequest |
2 | The HttpRequest is used to obtain the value of a query parameter called name . |
3 | The HttpResponse.ok(T) method is used to return a MutableHttpResponse with a text body. A header called X-My-Header is also added to the response object. |
HttpRequest is also available from static context via ServerRequestContext.
Generally ServerRequestContext is available within reactive flow, but the recommended approach is to propagate the necessary state through lambdas. |
6.8 Response Status
A Micronaut’s controller action responds with a 200 HTTP status code by default.
If the controller’s action returns a HttpResponse
object, you can configure the status code for the response object with the status
method.
@Get(value = "/http-response", produces = MediaType.TEXT_PLAIN)
public HttpResponse httpResponse() {
return HttpResponse.status(HttpStatus.CREATED).body("success");
}
@Get(value = "/http-response", produces = MediaType.TEXT_PLAIN)
HttpResponse httpResponse() {
HttpResponse.status(HttpStatus.CREATED).body("success")
}
@Get(value = "/http-response", produces = [MediaType.TEXT_PLAIN])
fun httpResponse(): HttpResponse<String> {
return HttpResponse.status<String>(HttpStatus.CREATED).body("success")
}
You can also use the @Status
annotation.
@Status(HttpStatus.CREATED)
@Get(produces = MediaType.TEXT_PLAIN)
public String index() {
return "success";
}
@Status(HttpStatus.CREATED)
@Get(produces = MediaType.TEXT_PLAIN)
String index() {
return "success"
}
@Status(HttpStatus.CREATED)
@Get(produces = [MediaType.TEXT_PLAIN])
fun index(): String {
return "success"
}
or even respond with an HttpStatus
@Get("/http-status")
public HttpStatus httpStatus() {
return HttpStatus.CREATED;
}
@Get("/http-status")
HttpStatus httpStatus() {
HttpStatus.CREATED
}
@Get("/http-status")
fun httpStatus(): HttpStatus {
return HttpStatus.CREATED
}
6.9 Response Content-Type
A Micronaut’s controller action produces application/json
by default.
Nonetheless you can change the Content-Type
of the response with the @Produces
annotation or the produces
member of the HTTP method annotations.
import io.micronaut.context.annotation.Requires;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;
@Controller("/produces")
public class ProducesController {
@Get (1)
public HttpResponse index() {
return HttpResponse.ok().body("{\"msg\":\"This is JSON\"}");
}
@Produces(MediaType.TEXT_HTML)
@Get("/html") (2)
public String html() {
return "<html><title><h1>HTML</h1></title><body></body></html>";
}
@Get(value = "/xml", produces = MediaType.TEXT_XML) (3)
public String xml() {
return "<html><title><h1>XML</h1></title><body></body></html>";
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Produces
@Controller("/produces")
class ProducesController {
@Get (1)
HttpResponse index() {
HttpResponse.ok().body("{\"msg\":\"This is JSON\"}")
}
@Produces(MediaType.TEXT_HTML) (2)
@Get("/html")
String html() {
"<html><title><h1>HTML</h1></title><body></body></html>"
}
@Get(value = "/xml", produces = MediaType.TEXT_XML) (3)
String xml() {
return "<html><title><h1>XML</h1></title><body></body></html>"
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Produces
@Controller("/produces")
class ProducesController {
@Get (1)
fun index(): HttpResponse<*> {
return HttpResponse.ok<Any>().body("{\"msg\":\"This is JSON\"}")
}
@Produces(MediaType.TEXT_HTML)
@Get("/html") (2)
fun html(): String {
return "<html><title><h1>HTML</h1></title><body></body></html>"
}
@Get(value = "/xml", produces = [MediaType.TEXT_XML]) (3)
fun xml(): String {
return "<html><title><h1>XML</h1></title><body></body></html>"
}
}
1 | The default content type is JSON |
2 | Annotate a controller’s action with @Produces to change the response content type. |
3 | Setting the produces member of the method annotation also changes the content type. |
6.10 Accepted Request Content-Type
A Micronaut’s controller action consumes application/json
by default. Consuming other content types is supported with the @Consumes
annotation, or the consumes
member of any HTTP method annotation.
import io.micronaut.context.annotation.Requires;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Consumes;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
@Controller("/consumes")
public class ConsumesController {
@Post (1)
public HttpResponse index() {
return HttpResponse.ok();
}
@Consumes({MediaType.APPLICATION_FORM_URLENCODED, MediaType.APPLICATION_JSON}) (2)
@Post("/multiple")
public HttpResponse multipleConsumes() {
return HttpResponse.ok();
}
@Post(value = "/member", consumes = MediaType.TEXT_PLAIN) (3)
public HttpResponse consumesMember() {
return HttpResponse.ok();
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Consumes
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
@Controller("/consumes")
class ConsumesController {
@Post (1)
HttpResponse index() {
HttpResponse.ok()
}
@Consumes([MediaType.APPLICATION_FORM_URLENCODED, MediaType.APPLICATION_JSON]) (2)
@Post("/multiple")
HttpResponse multipleConsumes() {
HttpResponse.ok()
}
@Post(value = "/member", consumes = MediaType.TEXT_PLAIN) (3)
HttpResponse consumesMember() {
HttpResponse.ok()
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Consumes
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
@Controller("/consumes")
class ConsumesController {
@Post (1)
fun index(): HttpResponse<*> {
return HttpResponse.ok<Any>()
}
@Consumes(MediaType.APPLICATION_FORM_URLENCODED, MediaType.APPLICATION_JSON) (2)
@Post("/multiple")
fun multipleConsumes(): HttpResponse<*> {
return HttpResponse.ok<Any>()
}
@Post(value = "/member", consumes = [MediaType.TEXT_PLAIN]) (3)
fun consumesMember(): HttpResponse<*> {
return HttpResponse.ok<Any>()
}
}
1 | By default, a controller’s action consumes request with Content-Type of type application/json . |
2 | @Consumes annotation takes a String[] of supported media types for an incoming request. |
3 | The consumes can also be specified with the consumes member of the method annotation. |
Customizing Processed Content Types
Normally the JSON parsing only happens if the content type is application/json
. The other MediaTypeCodec 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 in CodecConfiguration:
micronaut:
codec:
json:
additionalTypes:
- text/javascript
- ...
Currently supported configuration prefixes are json
, json-stream
, text
, and text-stream
.
6.11 Reactive HTTP Request Processing
As mentioned previously, Micronaut is built on Netty which is designed around an Event loop model and non-blocking I/O. Micronaut will execute code defined in @Controller beans in the same thread as the request thread (an Event Loop thread).
This makes it critical that if you do any blocking I/O operations (for example interactions with Hibernate/JPA or JDBC) that you offload those tasks to a separate thread pool that does not block the Event loop.
For example the following configuration will configure the I/O thread pool as a fixed thread pool with 75 threads (similar to what a traditional blocking server such as Tomcat uses in the thread per request model):
micronaut:
executors:
io:
type: fixed
nThreads: 75
To use this thread pool in a @Controller bean you have a number of options. The simplest option is to use the @ExecuteOn annotation which can be declared at the type or method level to indicate which configured thread pool you wish to run the method or methods of the controller on:
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) (1)
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) (1)
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) (1)
fun byName(name: String): Person {
return personService.findByName(name)
}
}
1 | The @ExecuteOn annotation is used to execute the operation on the I/O thread pool |
The value of the @ExecuteOn annotation can be any named executor defined under micronaut.executors
.
Generally speaking for database operations you will want a thread pool configured that matches maximum number of connections you have specified in the database connection pool. |
An alternative to the @ExecuteOn annotation is to use the facility provided by the reactive library you have chosen. RxJava for example features a subscribeOn
method which allows you to alter which thread executes user code. For 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, (1)
PersonService personService) {
this.scheduler = Schedulers.from(executorService);
this.personService = personService;
}
@Get("/{name}")
Single<Person> byName(String name) {
return Single.fromCallable(() ->
personService.findByName(name) (2)
).subscribeOn(scheduler); (3)
}
}
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, (1)
PersonService personService) {
this.scheduler = Schedulers.from(executorService)
this.personService = personService
}
@Get("/{name}")
Single<Person> byName(String name) {
return Single.fromCallable({ -> (2)
personService.findByName(name)
}).subscribeOn(scheduler) (3)
}
}
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, (1)
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) } (2)
.subscribeOn(scheduler) (3)
}
}
1 | The configured I/O executor service is injected |
2 | RxJava’s fromCallable method is used to wrap the blocking operation |
3 | RxJava’s subscribeOn method is used to schedule the operation on the I/O thread pool |
6.11.1 Using the @Body Annotation
To parse the request body, you first need to indicate to Micronaut the parameter which will receive the data. This is done with the Body annotation.
The following example implements a simple echo server that echos the body sent in the request:
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) (1)
String echo(@Size(max = 1024) @Body String text) { (2)
return text; (3)
}
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) (1)
String echo(@Size(max = 1024) @Body String text) { (2)
text (3)
}
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]) (1)
open fun echo(@Size(max = 1024) @Body text: String): String { (2)
return text (3)
}
}
1 | The Post annotation is used with a MediaType of text/plain (the default is application/json ). |
2 | The Body annotation is used with a javax.validation.constraints.Size that limits the size of the body to at most 1MB. This constraint does not limit the amount of data read/buffered by the server. |
3 | The body is returned as the result of the method |
Note that reading the request body is done in a non-blocking manner in that the request contents are read as the data becomes available and accumulated into the String passed to the method.
The micronaut.server.maxRequestSize setting in application.yml will limit the size of the data (the default maximum request size is 10MB) read/buffered by the server. @Size is not a replacement for this setting.
|
Regardless of the limit, for a large amount of data accumulating the data into a String in-memory may lead to memory strain on the server. A better approach is to include a Reactive library in your project (such as RxJava 2.x
, Reactor
or Akka
) that supports the Reactive streams implementation and stream the data it becomes available:
@Post(value = "/echo-flow", consumes = MediaType.TEXT_PLAIN) (1)
Single<MutableHttpResponse<String>> echoFlow(@Body Flowable<String> text) { (2)
return text.collect(StringBuffer::new, StringBuffer::append) (3)
.map(buffer ->
HttpResponse.ok(buffer.toString())
);
}
@Post(value = "/echo-flow", consumes = MediaType.TEXT_PLAIN) (1)
Single<MutableHttpResponse<String>> echoFlow(@Body Flowable<String> text) { (2)
return text.collect({ x -> new StringBuffer()}, { StringBuffer sb, String s -> sb.append(s)}) (3)
.map({ buffer ->
HttpResponse.ok(buffer.toString())
});
}
@Post(value = "/echo-flow", consumes = [MediaType.TEXT_PLAIN]) (1)
open fun echoFlow(@Body text: Flowable<String>): Single<MutableHttpResponse<String>> { (2)
return text.collect({ StringBuffer() }, { obj, str -> obj.append(str) }) (3)
.map { buffer -> HttpResponse.ok(buffer.toString()) }
}
1 | In this case the method is altered to receive and return an RxJava 2.x Flowable type |
2 | A Single is returned so that Micronaut will only emit the response once the operation completes without blocking. |
3 | The collect method is used to accumulate the data in this simulated example, but it could for example write the data to logging service, database or whatever chunk by chunk |
Body arguments of types that do not require conversion will cause Micronaut to skip decoding of the request! |
6.11.2 Reactive Responses
The previous section introduced the notion of Reactive programming using RxJava 2.x and Micronaut.
Micronaut supports returning common reactive types such as Single or Observable (or the Mono
type from Reactor 3.x), an instance of Publisher or CompletableFuture from any controller method.
The argument that is designated the body of the request using the Body annotation can also be a reactive type or a CompletableFuture.
When returning a reactive type Micronaut will subscribe to the returned reactive type on the same thread as the request (A Netty Event Loop thread). It is therefore important that if you perform any blocking operations you offload those operations to an appropriately configured thread pool for example, using RxJava’s subscribeOn(..)
facility or @ExecuteOn.
See the section on Configuring Thread Pools for information on the thread pools that Micronaut sets up and how to configure them. |
To summarize, the following table illustrates some common response types and their handling:
Type | Description | Example Signature |
---|---|---|
Any type that implements the Publisher interface |
|
|
A Java |
|
|
An HttpResponse and optional response body |
|
|
Any implementation of |
|
|
T |
Any simple POJO type |
|
When returning a Reactive type, the type of reactive type has an impact on the response returned. For example, when returning a Flowable, Micronaut can not know the size of the response, so Transfer-Encoding type of Chunked is used. Whilst for types that emit a single result such as Single the Content-Length header will be populated.
|
6.12 JSON Binding with Jackson
The most common data interchange format nowadays is JSON.
In fact, the defaults in the Controller annotation specify that the controllers in Micronaut consume and produce JSON by default.
In order to do so in a non-blocking manner Micronaut builds on the Jackson Asynchronous JSON parsing API and Netty such that the reading of incoming JSON is done in a non-blocking manner.
Binding using Reactive Frameworks
From a developer perspective however, you can generally just work with Plain Old Java Objects (POJOs) and can optionally use a Reactive framework such as RxJava or Reactor. The following is an example of a controller that reads and saves an incoming POJO in a non-blocking way from JSON:
@Controller("/people")
public class PersonController {
Map<String, Person> inMemoryDatastore = new ConcurrentHashMap<>();
@Post("/saveReactive")
public Single<HttpResponse<Person>> save(@Body Single<Person> person) { (1)
return person.map(p -> {
inMemoryDatastore.put(p.getFirstName(), p); (2)
return HttpResponse.created(p); (3)
}
);
}
}
@Controller("/people")
class PersonController {
ConcurrentHashMap<String, Person> inMemoryDatastore = [:]
@Post("/saveReactive")
Single<HttpResponse<Person>> save(@Body Single<Person> person) { (1)
person.map({ p ->
inMemoryDatastore.put(p.getFirstName(), p) (2)
HttpResponse.created(p) (3)
})
}
}
@Controller("/people")
class PersonController {
internal var inMemoryDatastore: MutableMap<String, Person> = ConcurrentHashMap()
@Post("/saveReactive")
fun save(@Body person: Single<Person>): Single<HttpResponse<Person>> { (1)
return person.map { p ->
inMemoryDatastore[p.firstName] = p (2)
HttpResponse.created(p) (3)
}
}
}
1 | The method receives a RxJava Single which emits the POJO once the JSON has been read |
2 | The map method is used to store the instance in Map |
3 | An HttpResponse is returned |
Using CURL from the command line you can POST JSON to the /people
URI for the server to receive it:
$ curl -X POST localhost:8080/people -d '{"firstName":"Fred","lastName":"Flintstone","age":45}'
Binding Using CompletableFuture
The same method as the previous example can also be written with the CompletableFuture API instead:
@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)
}
}
}
The above example uses the thenApply
method to achieve the same as the previous example.
Binding using POJOs
Note however you can just as easily write:
@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)
}
}
Micronaut will only execute your method once the data has been read in a non-blocking manner.
The output produced by Jackson can be customized in a variety of manners, from defining Jackson modules to using Jackson’s annotations |
Jackson Configuration
The Jackson ObjectMapper can be configured through normal configuration with the JacksonConfiguration class.
All jackson configuration keys start with jackson
.
dateFormat |
String |
The date format |
locale |
String |
Uses Locale.forLanguageTag. Example: |
timeZone |
String |
Uses TimeZone.getTimeZone. Example: |
serializationInclusion |
String |
One of JsonInclude.Include. Example: |
propertyNamingStrategy |
String |
Name of an instance of PropertyNamingStrategy. Example: |
defaultTyping |
String |
The global defaultTyping for polymorphic type handling from enum ObjectMapper.DefaultTyping. Example: |
Example:
jackson:
serializationInclusion: ALWAYS
Features
All features can be configured with their name as the key and a boolean to indicate enabled or disabled.
serialization |
Map |
|
deserialization |
Map |
|
mapper |
Map |
|
parser |
Map |
|
generator |
Map |
Example:
jackson:
serialization:
indentOutput: true
writeDatesAsTimestamps: false
deserialization:
useBigIntegerForInts: true
failOnUnknownProperties: false
Support for @JsonView
You can use the @JsonView
annotation to controller methods if you set jackson.json-view.enabled
to true
in application.yml
.
Jackson’s @JsonView
annotation allows you to control which properties are exposes on a per response basis. See Jackson JSON Views for more information.
Beans
In addition to configuration, beans can be registered to customize Jackson. All beans that extend any of the following classes will be registered with the object mapper.
Service Loader
Any modules registered via the service loader will also be added to the default object mapper.
6.13 Data Validation
It is easy to validate incoming data with Micronaut’s controllers with the Validation Advice.
First, add the Hibernate Validator configuration to your application:
implementation("io.micronaut.beanvalidation:micronaut-hibernate-validator")
<dependency>
<groupId>io.micronaut.beanvalidation</groupId>
<artifactId>micronaut-hibernate-validator</artifactId>
</dependency>
We can validate parameters using javax.validation
annotations and the Validated annotation at the class level.
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 (1)
@Controller("/email")
public class EmailController {
@Get("/send")
public HttpResponse send(@NotBlank String recipient, (2)
@NotBlank String subject) { (2)
return HttpResponse.ok(Collections.singletonMap("msg", "OK"));
}
}
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 (1)
@Controller("/email")
class EmailController {
@Get("/send")
HttpResponse send(@NotBlank String recipient, (2)
@NotBlank String subject) { (2)
HttpResponse.ok(Collections.singletonMap("msg", "OK"))
}
}
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 (1)
@Controller("/email")
open class EmailController {
@Get("/send")
open fun send(@NotBlank recipient: String, (2)
@NotBlank subject: String): HttpResponse<*> { (2)
return HttpResponse.ok(Collections.singletonMap("msg", "OK"))
}
}
1 | Annotate controller with Validated |
2 | subject and recipient cannot be blank. |
If a validation error occurs a javax.validation.ConstraintViolationException
will be thrown. By default, the integrated io.micronaut.validation.exception.ConstraintExceptionHandler
is used to handle the exception leading to a behaviour as shown in the following 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());
}
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
}
"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
}
If you want your own ExceptionHandler
to handle the constraint exceptions, you need to annotate it with @Replaces(ConstraintExceptionHandler.class)
Often, you may want to use POJOs as controller method parameters.
/*
* 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
*
* https://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.datavalidation.pogo;
import io.micronaut.core.annotation.Introspected;
import javax.validation.constraints.NotBlank;
@Introspected
public class Email {
@NotBlank (1)
String subject;
@NotBlank (1)
String recipient;
public String getSubject() {
return subject;
}
public void setSubject(String subject) {
this.subject = subject;
}
public String getRecipient() {
return recipient;
}
public void setRecipient(String recipient) {
this.recipient = recipient;
}
}
/*
* 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.datavalidation.pogo;
import io.micronaut.core.annotation.Introspected;
import javax.validation.constraints.NotBlank;
@Introspected
class Email {
@NotBlank (1)
String subject;
@NotBlank (1)
String recipient;
}
/*
* 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.datavalidation.pogo
import io.micronaut.core.annotation.Introspected
import javax.validation.constraints.NotBlank
@Introspected
open class Email {
@NotBlank (1)
var subject: String? = null
@NotBlank (1)
var recipient: String? = null
}
1 | You can use javax.validation annotations in your POJOs. |
You need to annotate your controller with Validated. Also, you need to annotate the binding POJO with @Valid
.
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 (1)
@Controller("/email")
public class EmailController {
@Post("/send")
public HttpResponse send(@Body @Valid Email email) { (2)
return HttpResponse.ok(Collections.singletonMap("msg", "OK")); }
}
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 (1)
@Controller("/email")
class EmailController {
@Post("/send")
HttpResponse send(@Body @Valid Email email) { (2)
HttpResponse.ok(Collections.singletonMap("msg", "OK"))
}
}
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 (1)
@Controller("/email")
open class EmailController {
@Post("/send")
open fun send(@Body @Valid email: Email): HttpResponse<*> { (2)
return HttpResponse.ok(Collections.singletonMap("msg", "OK"))
}
}
1 | Annotate controller with Validated |
2 | Annotate the POJO which you wish to validate with @Valid |
The validation of POJOs is shown in the following test:
public void testPoJoValidation() {
HttpClientResponseException e = Assertions.assertThrows(HttpClientResponseException.class, () -> {
Email email = new Email();
email.subject = "Hi";
email.recipient = "";
client.toBlocking().exchange(HttpRequest.POST("/email/send", email));
});
HttpResponse response = e.getResponse();
assertEquals(HttpStatus.BAD_REQUEST, response.getStatus());
Email email = new Email();
email.subject = "Hi";
email.recipient = "me@micronaut.example";
response = client.toBlocking().exchange(HttpRequest.POST("/email/send", email));
assertEquals(HttpStatus.OK, response.getStatus());
}
def "invoking /email/send parse parameters in a POJO and validates"() {
when:
Email email = new Email()
email.subject = 'Hi'
email.recipient = ''
client.toBlocking().exchange(HttpRequest.POST('/email/send', email))
then:
def e = thrown(HttpClientResponseException)
def response = e.response
response.status == HttpStatus.BAD_REQUEST
when:
email = new Email()
email.subject = 'Hi'
email.recipient = 'me@micronaut.example'
response = client.toBlocking().exchange(HttpRequest.POST('/email/send', email))
then:
response.status == HttpStatus.OK
}
"test poko validation"() {
val e = shouldThrow<HttpClientResponseException> {
val email = Email()
email.subject = "Hi"
email.recipient = ""
client.toBlocking().exchange<Email, Any>(HttpRequest.POST("/email/send", email))
}
var response = e.response
response.status shouldBe HttpStatus.BAD_REQUEST
val email = Email()
email.subject = "Hi"
email.recipient = "me@micronaut.example"
response = client.toBlocking().exchange<Email, Any>(HttpRequest.POST("/email/send", email))
response.status shouldBe HttpStatus.OK
}
Bean injection is supported in custom constraints with the hibernate validator configuration. |
6.14 Serving Static Resources
Static resource resolution is disabled by default. Micronaut supports resolving resources from the classpath or the file system.
See the information below for available configuration options:
Property | Type | Description |
---|---|---|
|
boolean |
Sets whether this specific mapping is enabled. Default value (true). |
|
java.util.List |
A list of paths either starting with |
|
java.lang.String |
The path resources should be served from. Uses ant path matching. Default value ("/**"). |
6.15 Error Handling
Sometimes with distributed applications, bad things happen. Having a good way to handle errors is important.
Status Handlers
The Error annotation supports defining either an exception class or an HTTP status. Methods decorated with the annotation will be invoked as the result of other controller methods. The annotation also supports the notion of global and local, local being the default.
Local error handlers will only respond to methods defined in the same controller. Global error handlers can respond to any method in any controller. A local error handler is always searched for first when resolving which handler to execute.
When defining an error handler for an exception, you can specify the exception instance as an argument to the method and omit the exception property of the annotation. |
Local Error Handling
For example the following method will handling JSON parse exceptions from Jackson for the scope of the declaring controller:
@Error
public HttpResponse<JsonError> jsonError(HttpRequest request, JsonParseException jsonParseException) { (1)
JsonError error = new JsonError("Invalid JSON: " + jsonParseException.getMessage()) (2)
.link(Link.SELF, Link.of(request.getUri()));
return HttpResponse.<JsonError>status(HttpStatus.BAD_REQUEST, "Fix Your JSON")
.body(error); (3)
}
@Error
HttpResponse<JsonError> jsonError(HttpRequest request, JsonParseException jsonParseException) { (1)
JsonError error = new JsonError("Invalid JSON: " + jsonParseException.getMessage()) (2)
.link(Link.SELF, Link.of(request.getUri()))
HttpResponse.<JsonError>status(HttpStatus.BAD_REQUEST, "Fix Your JSON")
.body(error) (3)
}
@Error
fun jsonError(request: HttpRequest<*>, jsonParseException: JsonParseException): HttpResponse<JsonError> { (1)
val error = JsonError("Invalid JSON: " + jsonParseException.message) (2)
.link(Link.SELF, Link.of(request.uri))
return HttpResponse.status<JsonError>(HttpStatus.BAD_REQUEST, "Fix Your JSON")
.body(error) (3)
}
1 | A method that explicitly handles JsonParseException is declared |
2 | An instance of JsonError is returned. |
3 | A custom response is returned to handle the error |
@Error(status = HttpStatus.NOT_FOUND)
public HttpResponse<JsonError> notFound(HttpRequest request) { (1)
JsonError error = new JsonError("Person Not Found") (2)
.link(Link.SELF, Link.of(request.getUri()));
return HttpResponse.<JsonError>notFound()
.body(error); (3)
}
@Error(status = HttpStatus.NOT_FOUND)
HttpResponse<JsonError> notFound(HttpRequest request) { (1)
JsonError error = new JsonError("Person Not Found") (2)
.link(Link.SELF, Link.of(request.getUri()))
HttpResponse.<JsonError>notFound()
.body(error) (3)
}
@Error(status = HttpStatus.NOT_FOUND)
fun notFound(request: HttpRequest<*>): HttpResponse<JsonError> { (1)
val error = JsonError("Person Not Found") (2)
.link(Link.SELF, Link.of(request.uri))
return HttpResponse.notFound<JsonError>()
.body(error) (3)
}
1 | The Error declares which HttpStatus error code to handle (in this case 404) |
2 | A JsonError instance is returned for all 404 responses |
3 | An NOT_FOUND response is returned |
Global Error Handling
@Error(global = true) (1)
public HttpResponse<JsonError> error(HttpRequest request, Throwable e) {
JsonError error = new JsonError("Bad Things Happened: " + e.getMessage()) (2)
.link(Link.SELF, Link.of(request.getUri()));
return HttpResponse.<JsonError>serverError()
.body(error); (3)
}
@Error(global = true) (1)
HttpResponse<JsonError> error(HttpRequest request, Throwable e) {
JsonError error = new JsonError("Bad Things Happened: " + e.getMessage()) (2)
.link(Link.SELF, Link.of(request.getUri()))
HttpResponse.<JsonError>serverError()
.body(error) (3)
}
@Error(global = true) (1)
fun error(request: HttpRequest<*>, e: Throwable): HttpResponse<JsonError> {
val error = JsonError("Bad Things Happened: " + e.message) (2)
.link(Link.SELF, Link.of(request.uri))
return HttpResponse.serverError<JsonError>()
.body(error) (3)
}
1 | The Error is used to declare the method a global error handler |
2 | A JsonError instance is returned for all errors |
3 | An INTERNAL_SERVER_ERROR response is returned |
@Error(status = HttpStatus.NOT_FOUND)
public HttpResponse<JsonError> notFound(HttpRequest request) { (1)
JsonError error = new JsonError("Person Not Found") (2)
.link(Link.SELF, Link.of(request.getUri()));
return HttpResponse.<JsonError>notFound()
.body(error); (3)
}
@Error(status = HttpStatus.NOT_FOUND)
HttpResponse<JsonError> notFound(HttpRequest request) { (1)
JsonError error = new JsonError("Person Not Found") (2)
.link(Link.SELF, Link.of(request.getUri()))
HttpResponse.<JsonError>notFound()
.body(error) (3)
}
@Error(status = HttpStatus.NOT_FOUND)
fun notFound(request: HttpRequest<*>): HttpResponse<JsonError> { (1)
val error = JsonError("Person Not Found") (2)
.link(Link.SELF, Link.of(request.uri))
return HttpResponse.notFound<JsonError>()
.body(error) (3)
}
1 | The Error declares which HttpStatus error code to handle (in this case 404) |
2 | A JsonError instance is returned for all 404 responses |
3 | An NOT_FOUND response is returned |
A few things to note about the Error annotation. Two identical @Error annotations that are
global cannot be declared. Two identical @Error annotations that are non-global cannot be declared in the same controller.
If an @Error annotation with the same parameter exists as global and another as a local, the local one will take precedence.
|
ExceptionHandler
Additionally you can implement a ExceptionHandler; a generic hook for handling exceptions that occurs during the execution of an HTTP request.
Imagine your e-commerce app throws an OutOfStockException
when a book is out of stock:
public class OutOfStockException extends RuntimeException {
}
class OutOfStockException extends RuntimeException {
}
class OutOfStockException : RuntimeException()
Along with BookController
:
@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()
}
}
If you don’t handle the exception the server returns a 500 (Internal Server Error) status code.
If you want to respond 200 OK with 0 (stock level) as the response body when the OutOfStockException
is thrown, you could register a ExceptionHandler
:
@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)
}
}
An @Error annotation capturing an exception has precedence over an implementation of ExceptionHandler capturing the same exception.
|
6.16 API Versioning
Since 1.1.x, Micronaut supports API versioning via a dedicated @Version annotation.
The following example demonstrates how to version 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") (1)
@Get("/hello")
String helloV1() {
return "helloV1";
}
@Version("2") (2)
@Get("/hello")
String helloV2() {
return "helloV2";
}
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") (1)
@Get("/hello")
String helloV1() {
"helloV1"
}
@Version("2") (2)
@Get("/hello")
String helloV2() {
"helloV2"
}
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") (1)
@Get("/hello")
fun helloV1(): String {
return "helloV1"
}
@Version("2") (2)
@Get("/hello")
fun helloV2(): String {
return "helloV2"
}
1 | The helloV1 method is declared as version 1 |
2 | The helloV2 method is declared as version 2 |
You should then enabling versioning by setting micronaut.router.versioning.enabled
to true
in application.yml
:
micronaut:
router:
versioning:
enabled: true
By default Micronaut has 2 out-of-the-box strategies for resolving the version that are based on an HTTP header named X-API-VERSION
or a request parameter named api-version
, however this is configurable. A full configuration example can be seen below:
micronaut:
router:
versioning:
enabled: true (1)
parameter:
enabled: false (2)
names: 'v,api-version' (3)
header:
enabled: true (4)
names: (5)
- 'X-API-VERSION'
- 'Accept-Version'
1 | Enables versioning |
2 | Enables or disables parameter based versioning |
3 | Specify the parameter names as a comma separated list |
4 | Enables or disables header based versioning |
5 | Specify the header names as a YAML list |
If this is not enough you can also implement the RequestVersionResolver interface which receives the HttpRequest and can implement any strategy you choose.
Default Version
It is possible to supply a default version through configuration.
micronaut:
router:
versioning:
enabled: true
default-version: 3 (1)
1 | Sets the default version |
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’s Declarative HTTP client also 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") (1)
public interface HelloClient {
@Get("/greeting/{name}")
String sayHello(String name);
@Version("2")
@Get("/greeting/{name}")
Single<String> sayHelloTwo(String name); (2)
}
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") (1)
interface HelloClient {
@Get("/greeting/{name}")
String sayHello(String name)
@Version("2")
@Get("/greeting/{name}")
Single<String> sayHelloTwo(String name) (2)
}
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") (1)
interface HelloClient {
@Get("/greeting/{name}")
fun sayHello(name : String) : String
@Version("2")
@Get("/greeting/{name}")
fun sayHelloTwo(name : String) : Single<String> (2)
}
1 | The @Version can be used as the type level to specify the version to use for all methods |
2 | When defined at the method level it is used only for that method |
The default behaviour for how the version is sent for each call can be configured with DefaultClientVersioningConfiguration:
Property | Type | Description |
---|---|---|
|
java.util.List |
The list of request header names. |
|
java.util.List |
The list of request query parameter names. |
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')
.
6.17 Handling Form Data
In order to make data binding model customizations consistent between form data and JSON, Micronaut uses Jackson to implement binding data from form submissions.
The advantage of this approach is that the same Jackson annotations used for customizing JSON binding can be used for form submissions too.
What this means in practise is that in order to bind regular form data the only change required to the previous JSON binding code is updating the MediaType consumed:
@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)
}
}
To avoid denial of service attacks, collection types and arrays created during binding are limited by the setting jackson.arraySizeThreshold in application.yml
|
Alternatively, instead of using a POJO you can bind form data directly to method parameters (which works with JSON too!):
@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);
}
}
@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)
}
}
@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)
}
}
As you can see from the example above, this approach allows you to use features such as support for Optional types and restrict the parameters to be bound (When using POJOs you must be careful to use Jackson annotations to exclude properties that should not be bound).
6.18 Writing Response Data
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:
Return Type | Description |
---|---|
|
A Flowable that emits each chunk of content as a |
|
A Reactor |
|
A Publisher that emits each chunk of content as a String |
|
When emitting a POJO each emitted object is encoded as JSON by default without blocking |
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.
It is up to the implementation of the Publisher to schedule any blocking I/O work that may be done as a result of subscribing to the publisher. |
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 a Writable object from any controller method. The Writable has various signatures that allowing writing to traditional blocking streams like Writer or OutputStream.
When returning a Writable object the blocking I/O operation will be shifted to the I/O thread pool so that the Netty event loop is not blocked.
See the section on configuring Server Thread Pools for details on how to configure the I/O thread pool to meet the requirements of your application. |
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(); (1)
}
@Get(value = "/welcome", produces = MediaType.TEXT_PLAIN)
Writable render() { (2)
return writer -> template.make( (3)
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() (1)
}
@Get(value = "/welcome", produces = MediaType.TEXT_PLAIN)
Writable render() { (2)
{ writer ->
template.make( (3)
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() (1)
}
@Get(value = "/welcome", produces = [MediaType.TEXT_PLAIN])
internal fun render(): Writable { (2)
return { writer: Writer ->
val writable = template.make( (3)
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; (1)
}
@Get("/maybestock/{isbn}")
public Maybe<Map> maybestock(String isbn) {
return Maybe.empty(); (2)
}
}
@Controller("/books")
class BooksController {
@Get("/stock/{isbn}")
Map stock(String isbn) {
null (1)
}
@Get("/maybestock/{isbn}")
Maybe<Map> maybestock(String isbn) {
Maybe.empty() (2)
}
}
@Controller("/books")
class BooksController {
@Get("/stock/{isbn}")
fun stock(isbn: String): Map<*, *>? {
return null (1)
}
@Get("/maybestock/{isbn}")
fun maybestock(isbn: String): Maybe<Map<*, *>> {
return Maybe.empty() (2)
}
}
1 | Returning null triggers a 404 (Not Found) response. |
2 | Returning an empty Maybe triggers a 404 (Not Found) response. |
Responding with an empty Publisher or Flowable will result in an empty array being returned if the content type is JSON.
|
6.19 File Uploads
Handling of file uploads has special treatment in Micronaut. Support is provided for streaming of uploads in a non-blocking manner through streaming uploads or completed uploads.
To receive data from a multipart request, set the consumes
argument of the method annotation to MULTIPART_FORM_DATA. For example:
@Post(consumes = MediaType.MULTIPART_FORM_DATA)
HttpResponse upload( ... )
Route Arguments
How the files are received by your method is determined by the type of the arguments. Data can be received a chunk at a time or when an upload is completed.
If the route argument name can’t or shouldn’t match the name of the part in the request, simply add the @Part annotation to the argument and specify the name that is expected to be in the request. |
Chunk Data Types
PartData is the data type used to represent a chunk of data received in a multipart request. There are methods on the PartData interface to convert the data to a byte[]
, InputStream, or a ByteBuffer.
Data can only be retrieved from a PartData once. The underlying buffer will be released which causes further attempts to fail. |
Route arguments of type Publisher<PartData> will be treated as only intended to receive a single file and each chunk of the received file will be sent downstream. If the generic type is something other than PartData, conversion will be attempted using Micronaut’s conversion service. Conversions to String
and byte[]
are supported by default.
If requirements dictate you must have knowledge about the metadata of the file being received, a special class called StreamingFileUpload has been created that is a Publisher<PartData>, but also has file information like the content type and file name.
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) (1)
public Single<HttpResponse<String>> upload(StreamingFileUpload file) { (2)
File tempFile;
try {
tempFile = File.createTempFile(file.getFilename(), "temp");
} catch (IOException e) {
return Single.error(e);
}
Publisher<Boolean> uploadPublisher = file.transferTo(tempFile); (3)
return Single.fromPublisher(uploadPublisher) (4)
.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) (1)
Single<HttpResponse<String>> upload(StreamingFileUpload file) { (2)
File tempFile = File.createTempFile(file.filename, "temp")
Publisher<Boolean> uploadPublisher = file.transferTo(tempFile) (3)
Single.fromPublisher(uploadPublisher) (4)
.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]) (1)
fun upload(file: StreamingFileUpload): Single<HttpResponse<String>> { (2)
val tempFile = File.createTempFile(file.filename, "temp")
val uploadPublisher = file.transferTo(tempFile) (3)
return Single.fromPublisher(uploadPublisher) (4)
.map { success ->
if (success) {
HttpResponse.ok("Uploaded")
} else {
HttpResponse.status<String>(HttpStatus.CONFLICT)
.body("Upload Failed")
}
}
}
}
1 | The method is set to consume MULTIPART_FORM_DATA |
2 | The method parameters match form attribute names. In this case the file will match for example an <input type="file" name="file"> |
3 | The StreamingFileUpload.transferTo(java.lang.String) method is used to transfer the file to the server. The method returns a Publisher |
4 | The returned Single subscribes to the Publisher and outputs a response once the upload is complete, without blocking. |
Whole Data Types
Route arguments that are not publishers will cause the route execution to be delayed until the upload has finished. The received data will attempt to be converted to the requested type. Conversions to a String
or byte[]
are supported by default. In addition, the file can be converted to a POJO if a media type codec has been registered that supports the media type of the file. A media type codec is included by default that allows conversion of JSON files to POJOs.
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) (1)
public HttpResponse<String> uploadBytes(byte[] file, String fileName) { (2)
try {
File tempFile = File.createTempFile(fileName, "temp");
Path path = Paths.get(tempFile.getAbsolutePath());
Files.write(path, file); (3)
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) (1)
HttpResponse<String> uploadBytes(byte[] file, String fileName) { (2)
try {
File tempFile = File.createTempFile(fileName, "temp")
Path path = Paths.get(tempFile.absolutePath)
Files.write(path, file) (3)
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]) (1)
fun uploadBytes(file: ByteArray, fileName: String): HttpResponse<String> { (2)
return try {
val tempFile = File.createTempFile(fileName, "temp")
val path = Paths.get(tempFile.absolutePath)
Files.write(path, file) (3)
HttpResponse.ok("Uploaded")
} catch (exception: IOException) {
HttpResponse.badRequest("Upload Failed")
}
}
}
If requirements dictate you must have knowledge about the metadata of the file being received, a special class called CompletedFileUpload has been created that has methods to retrieve the data of the file, but also has file information like the content type and file name.
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) (1)
public HttpResponse<String> uploadCompleted(CompletedFileUpload file) { (2)
try {
File tempFile = File.createTempFile(file.getFilename(), "temp"); (3)
Path path = Paths.get(tempFile.getAbsolutePath());
Files.write(path, file.getBytes()); (3)
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) (1)
HttpResponse<String> uploadCompleted(CompletedFileUpload file) { (2)
try {
File tempFile = File.createTempFile(file.filename, "temp") (3)
Path path = Paths.get(tempFile.absolutePath)
Files.write(path, file.bytes) (3)
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]) (1)
fun uploadCompleted(file: CompletedFileUpload): HttpResponse<String> { (2)
return try {
val tempFile = File.createTempFile(file.filename, "temp") (3)
val path = Paths.get(tempFile.absolutePath)
Files.write(path, file.bytes) (3)
HttpResponse.ok("Uploaded")
} catch (exception: IOException) {
HttpResponse.badRequest("Upload Failed")
}
}
}
1 | The method is set to consume MULTIPART_FORM_DATA |
2 | The method parameters match form attribute names. In this case the file will match for example an <input type="file" name="file"> |
3 | The CompletedFileUpload instance gives access to metadata about the upload as well as access to the file’s contents. |
Multiple Uploads
Different Names
If a multipart request supplies multiple uploads that each have a different part name, simply create an argument to your route that receives each part. For example:
HttpResponse upload(String title, String name)
A route method signature like the above will expect 2 different parts with the names "title" and "name".
Same Name
To handle receiving multiple parts with the same part name, the argument must be a Publisher. When used in one of the following ways, the publisher will emit one item per file found with the specified name. The publisher must accept one of the following types:
-
Any POJO assuming a media codec is found that supports the content type
-
Another Publisher that accepts one of the chunked data types described above
For example:
HttpResponse upload(Publisher<StreamingFileUpload> files)
HttpResponse upload(Publisher<CompletedFileUpload> files)
HttpResponse upload(Publisher<MyObject> files)
HttpResponse upload(Publisher<Publisher<PartData>> files)
Whole Body Binding
For the cases where the names of the parts of the request cannot be known ahead of time, or the entire body should be read, a special type can be used to indicate the entire body is desired.
If a route has an argument of type MultipartBody (not to be confused with the class for the client) annotated with @Body, then each part of the request will be emitted through the argument. A MultipartBody is a publisher of CompletedPart instances.
For example:
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) (1)
public Single<String> uploadBytes(@Body MultipartBody body) { (2)
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) (1)
Single<String> uploadBytes(@Body MultipartBody body) { (2)
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]) (1)
fun uploadBytes(@Body body: MultipartBody): Single<String> { (2)
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")
}
})
}
}
}
6.20 File Transfers
Micronaut supports the sending of files to the client in a couple of easy ways.
Sending File Objects
It is possible to simply return a File object from your controller method and the data will be returned to the client. The Content-Type
header of file responses will be calculated based on the name of the file.
To control either the media type of the file being sent, or to set the file to be downloaded (i.e. using the Content-Disposition
header) you should instead construct an SystemFile with the file object you would like to be used. For example:
@Get
public SystemFile download() {
File file = ...
return new SystemFile(file).attach("myfile.txt");
// or new SystemFile(file, MediaType.TEXT_HTML_TYPE)
}
Sending an InputStream
For cases where a reference to a File
object is not possible (for example resources contained within JAR files), Micronaut supports transferring of input streams. To return a stream of data from the controller method, construct a StreamedFile.
The constructor for StreamedFile also accepts a java.net.URL for your convenience.
|
@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
}
The server supports returning 304
(Not Modified) responses if the files being transferred have not changed and the request contains the appropriate header. In addition, if the client accepts encoded responses, Micronaut will encode the file if it is deemed appropriate. Encoding will happen if the file is text based and greater than 1KB by default. The threshold at which data will be encoded is configurable. See the server configuration reference for details.
To use a custom data source to send data through an input stream, construct a PipedInputStream and PipedOutputStream to allow writing data from the output stream to the input. Make sure to do the work on a separate thread so the file can be returned immediately. |
Cache Configuration
By default file responses will include caching headers. The following options determine how the Cache-Control
header is built.
Property | Type | Description |
---|---|---|
|
int |
Cache Seconds. Default value (60). |
Property | Type | Description |
---|---|---|
|
boolean |
Sets whether the cache control is public. Default value (false) |
6.21 HTTP Filters
The Micronaut HTTP server supports the ability to apply filters to request/response processing in a similar, but reactive, way to Servlet filters in traditional Java applications.
Filters provide the ability to support the following use cases:
-
Decoration of the incoming HttpRequest
-
Modification of the outgoing HttpResponse
-
Implementation of cross cutting concerns such as security, tracing etc.
For a server application, the HttpServerFilter interface’s doFilter
method can be implemented.
The doFilter
method accepts the HttpRequest and an instance of ServerFilterChain.
The ServerFilterChain
interface contains a resolved chain of filters with the final entry in the chain being the matched route. The ServerFilterChain.proceed(io.micronaut.http.HttpRequest) method can be used to resume processing of the request.
The proceed(..)
method returns a Reactive Streams Publisher that emits the response that will be returned to the client. Implementors of filters can subscribe to the Publisher and mutate the emitted MutableHttpResponse object to modify the response prior to returning the response to the client.
To put these concepts into practise lets look at an example.
Filters execute in the event loop therefore blocking operations must be offloaded to another thread pool. |
Writing a Filter
Consider a hypothetical use case whereby you wish to trace each request to the Micronaut "Hello World" example using some external system. The external system could be a database, a distributed tracing service and may require I/O operations.
What you don’t want to do is block the underlying Netty event loop within your filter, instead you want the filter to proceed with execution once any I/O is complete.
As an example, consider the following example TraceService
that uses RxJava to compose an I/O operation:
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(() -> { (1)
if (LOG.isDebugEnabled()) {
LOG.debug("Tracing request: " + request.getUri());
}
// trace logic here, potentially performing I/O (2)
return true;
}).subscribeOn(Schedulers.io()); (3)
}
}
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({ -> (1)
if (LOG.isDebugEnabled()) {
LOG.debug("Tracing request: " + request.getUri())
}
// trace logic here, potentially performing I/O (2)
return true
}).subscribeOn(Schedulers.io()) (3)
}
}
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 {
(1)
if (LOG.isDebugEnabled) {
LOG.debug("Tracing request: " + request.uri)
}
// trace logic here, potentially performing I/O (2)
true
}.subscribeOn(Schedulers.io()) (3)
}
}
1 | The Flowable type is used to create logic that executes potentially blocking operations to write the trace data from the request |
2 | Since this is just an example the logic does nothing and a place holder comment is used |
3 | The RxJava I/O scheduler is used to execute the logic |
You can then inject this implementation into your filter definition:
import io.micronaut.http.*;
import io.micronaut.http.annotation.Filter;
import io.micronaut.http.filter.*;
import org.reactivestreams.Publisher;
@Filter("/hello/**") (1)
public class TraceFilter implements HttpServerFilter { (2)
private final TraceService traceService;
public TraceFilter(TraceService traceService) { (3)
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/**") (1)
class TraceFilter implements HttpServerFilter { (2)
private final TraceService traceService
TraceFilter(TraceService traceService) { (3)
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/**") (1)
class TraceFilter((2)
private val traceService: TraceService)(3)
: HttpServerFilter {
}
1 | The Filter annotation is used to define the URI patterns the filter matches |
2 | The class implements the HttpServerFilter interface |
3 | The previously defined TraceService is injected via a constructor argument |
The final step is write the doFilter
implementation of the HttpServerFilter interface.
@Override
public Publisher<MutableHttpResponse<?>> doFilter(HttpRequest<?> request, ServerFilterChain chain) {
return traceService.trace(request) (1)
.switchMap(aBoolean -> chain.proceed(request)) (2)
.doOnNext(res -> (3)
res.getHeaders().add("X-Trace-Enabled", "true")
);
}
@Override
Publisher<MutableHttpResponse<?>> doFilter(HttpRequest<?> request, ServerFilterChain chain) {
traceService.trace(request) (1)
.switchMap({ aBoolean -> chain.proceed(request) }) (2)
.doOnNext({ res -> (3)
res.getHeaders().add("X-Trace-Enabled", "true")
})
}
override fun doFilter(request: HttpRequest<*>, chain: ServerFilterChain): Publisher<MutableHttpResponse<*>> {
return traceService.trace(request) (1)
.switchMap { aBoolean -> chain.proceed(request) } (2)
.doOnNext { res ->
(3)
res.headers.add("X-Trace-Enabled", "true")
}
}
1 | The previously defined TraceService is called to trace the request |
2 | If the trace call succeeds then the filter switches back to resuming the request processing using RxJava’s switchMap method, which invokes the proceed method of the ServerFilterChain |
3 | Finally, RxJava’s doOnNext method is used to add a header called X-Trace-Enabled to the response. |
The previous example demonstrates some key concepts such as executing logic in a non-blocking matter before proceeding with the request and modifying the outgoing response.
The examples use RxJava, however you can use any reactive framework that supports the Reactive streams specifications |
6.22 HTTP Sessions
By default Micronaut is a stateless HTTP server, however depending on your application requirements you may need the notion of HTTP sessions.
Micronaut comes with a session
module inspired by Spring Session that enables this that currently features two implementations:
-
In-Memory sessions - which you should combine with an a sticky sessions proxy if you plan to run multiple instances.
-
Redis sessions - In this case Redis is used to store sessions and non-blocking I/O is used to read/write sessions to Redis.
Enabling Sessions
To enable support for in-memory sessions you just need the session
dependency:
implementation("io.micronaut:micronaut-session")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-session</artifactId>
</dependency>
Redis Sessions
If you wish to store Session instances in Redis you can do so with the Micronaut Redis module which includes detailed instructions.
To quickly get up and running with Redis sessions you must also have the redis-lettuce
configuration on your classpath:
compile "io.micronaut:micronaut-session"
compile "io.micronaut.redis:micronaut-redis-lettuce"
And enable Redis sessions via configuration in application.yml
:
redis:
uri: redis://localhost:6379
micronaut:
session:
http:
redis:
enabled: true
Configuring Session Resolution
How the Session is resolved can be configured with HttpSessionConfiguration.
By default sessions are resolved using an HttpSessionFilter that looks up session identifiers via either an HTTP header (using the Authorization-Info
or X-Auth-Token
header values) or via a Cookie called SESSION
.
If you wish to disable either header resolution or cookie resolution you can via configuration in application.yml
:
micronaut:
session:
http:
cookie: false
header: true
The above configuration enables header resolution, but disables cookie resolution. You can also configure the header or cookie names as necessary.
Working with Sessions
A Session object can be retrieved simply by declaring the Session in a controller method signature. For example consider the following controller:
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"; (1)
@Post("/cart/{name}")
Cart addItem(Session session, @NotBlank String name) { (2)
Cart cart = session.get(ATTR_CART, Cart.class).orElseGet(() -> { (3)
Cart newCart = new Cart();
session.put(ATTR_CART, newCart); (4)
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" (1)
@Post("/cart/{name}")
Cart addItem(Session session, @NotBlank String name) { (2)
Cart cart = session.get(ATTR_CART, Cart.class).orElseGet({ -> (3)
Cart newCart = new Cart()
session.put(ATTR_CART, newCart) (4)
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 { (2)
require(name.isNotBlank()) { "Name cannot be blank" }
val cart = session.get(ATTR_CART, Cart::class.java).orElseGet({
(3)
val newCart = Cart()
session.put(ATTR_CART, newCart) (4)
newCart
})
cart.items.add(name)
return cart
}
}
1 | The ShoppingController declares a Session attribute called cart |
2 | The Session is declared as a parameter to the method |
3 | The cart attribute is retrieved |
4 | Otherwise a new Cart instance is created and stored in the session |
Note that because the Session is declared as a required parameter to the execute the controller action, the Session will be created and saved to the SessionStore.
If you don’t want to create unnecessary sessions then you can declare the Session as @Nullable
in which case a session will not be created and saved unnecessarily. For example:
@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)
}
The above method will only create and inject a new Session if one already exists.
Session Clients
If the client is a web browser then sessions should just work if you have cookies is enabled. However for programmatic HTTP clients you need to make sure you propagate the session id between HTTP calls.
For example, when invoking the viewCart
method of the StoreController
in the previous example the HTTP client will receive by default a AUTHORIZATION_INFO
header. The following example, using a Spock test, demonstrates this:
HttpResponse<Cart> response = client.exchange(HttpRequest.GET("/shopping/cart"), Cart.class) (1)
.blockingFirst();
Cart cart = response.body();
assertNotNull(response.header(HttpHeaders.AUTHORIZATION_INFO)); (2)
assertNotNull(cart);
assertTrue(cart.getItems().isEmpty());
when: "The shopping cart is retrieved"
HttpResponse<Cart> response = httpClient.exchange(HttpRequest.GET('/shopping/cart'), Cart) (1)
.blockingFirst()
Cart cart = response.body()
then: "The shopping cart is present as well as a session id header"
response.header(HttpHeaders.AUTHORIZATION_INFO) != null (2)
cart != null
cart.items.isEmpty()
var response = client.exchange(HttpRequest.GET<Cart>("/shopping/cart"), Cart::class.java) (1)
.blockingFirst()
var cart = response.body()
assertNotNull(response.header(HttpHeaders.AUTHORIZATION_INFO)) (2)
assertNotNull(cart)
cart.items.isEmpty()
1 | A request is made to /shopping/cart |
2 | The AUTHORIZATION_INFO header is present in the response |
You can then pass this AUTHORIZATION_INFO
in subsequent requests to re-use the existing Session:
String sessionId = response.header(HttpHeaders.AUTHORIZATION_INFO); (1)
response = client.exchange(
HttpRequest.POST("/shopping/cart/Apple", "")
.header(HttpHeaders.AUTHORIZATION_INFO, sessionId), Cart.class) (2)
.blockingFirst();
cart = response.body();
String sessionId = response.header(HttpHeaders.AUTHORIZATION_INFO) (1)
response = httpClient.exchange(
HttpRequest.POST('/shopping/cart/Apple', "")
.header(HttpHeaders.AUTHORIZATION_INFO, sessionId), Cart) (2)
.blockingFirst()
cart = response.body()
val sessionId = response.header(HttpHeaders.AUTHORIZATION_INFO) (1)
response = client.exchange(
HttpRequest.POST("/shopping/cart/Apple", "")
.header(HttpHeaders.AUTHORIZATION_INFO, sessionId), Cart::class.java) (2)
.blockingFirst()
cart = response.body()
1 | The AUTHORIZATION_INFO is retrieved from the response |
2 | And then sent as a header in the subsequent request |
Using @SessionValue
Rather than explicitly injecting the Session into a controller method you can instead use @SessionValue. For example:
@Get("/cart")
@SessionValue(ATTR_CART) (1)
Cart viewCart(@SessionValue @Nullable Cart cart) { (2)
if (cart == null) {
cart = new Cart();
}
return cart;
}
@Get("/cart")
@SessionValue("cart") (1)
Cart viewCart(@SessionValue @Nullable Cart cart) { (2)
if (cart == null) {
cart = new Cart()
}
cart
}
@Get("/cart")
@SessionValue(ATTR_CART) (1)
internal fun viewCart(@SessionValue cart: Cart?): Cart { (2)
var cart = cart
if (cart == null) {
cart = Cart()
}
return cart
}
1 | @SessionValue is declared on the method resulting in the return value being stored in the Session. Note that you must specify the attribute name when used on a return value |
2 | @SessionValue is used on a @Nullable parameter which results in looking up the value from the Session in a non-blocking way and supplying it if present. In the case a value is not specified to @SessionValue resulting in the parameter name being used to lookup the attribute. |
Session Events
You can register ApplicationEventListener beans to listen for Session related events located in the io.micronaut.session.event package.
The following table summarizes the events:
Type | Description |
---|---|
Fired when a Session is created |
|
Fired when a Session is deleted |
|
Fired when a Session expires |
|
Parent of both |
6.23 Server Sent Events
The Micronaut HTTP server supports emitting Server Sent Events (SSE) using the Event API.
To emit events from the server you simply return a Reactive Streams Publisher that emits objects of type Event.
The Publisher itself could publish events from a background task, via an event system or whatever.
Imagine for an example a event stream of news headlines, you may define a data class as follows:
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;
}
}
class Headline {
String title;
String description;
Headline() {}
Headline(String title, String description) {
this.title = title;
this.description = description;
}
}
class Headline {
var title: String? = null
var description: String? = null
constructor() {}
constructor(title: String, description: String) {
this.title = title
this.description = description
}
}
To emit news headline events you can write a controller that returns a Publisher of Event instances using which ever Reactive library you prefer. The example below uses RxJava 2’s Flowable via the generate
method:
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() { (1)
String[] versions = new String[]{"1.0", "2.0"}; (2)
return Flowable.generate(() -> 0, (i, emitter) -> { (3)
if (i < versions.length) {
emitter.onNext( (4)
Event.of(new Headline("Micronaut " + versions[i] + " Released", "Come and get it"))
);
} else {
emitter.onComplete(); (5)
}
return ++i;
});
}
}
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() { (1)
String[] versions = ["1.0", "2.0"] (2)
def initialState = { -> 0 }
def emitterFunction = { Integer i, Emitter emitter -> (3)
if (i < versions.length) {
emitter.onNext( (4)
Event.of(new Headline("Micronaut " + versions[i] + " Released", "Come and get it"))
)
} else {
emitter.onComplete() (5)
}
return ++i
}
return Flowable.generate(initialState, emitterFunction as BiFunction<Integer,Emitter<Event<Headline>>,Integer>)
}
}
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>> { (1)
val versions = arrayOf("1.0", "2.0") (2)
return Flowable.generate<Event<Headline>, Int>(Callable<Int>{ 0 }, BiFunction { (3)
i: Int, emitter: Emitter<Event<Headline>> ->
var nextInt: Int = i
if (i < versions.size) {
emitter.onNext( (4)
Event.of<Headline>(Headline("Micronaut " + versions[i] + " Released", "Come and get it"))
)
} else {
emitter.onComplete() (5)
}
++nextInt
})
}
}
1 | The controller method returns a Publisher of Event |
2 | For each version of Micronaut a headline is emitted |
3 | The Flowable type’s generate method is used to generate a Publisher. The generate method accepts an initial value and a lambda that accepts the value and a Emitter. Note that this example executes on the same thread as the controller action, but you could use subscribeOn or map and existing "hot" Flowable. |
4 | The Emitter interface’s onNext method is used to emit objects of type Event. The Event.of(ET) factory method is used to construct the event. |
5 | The Emitter interface’s onComplete method is used to indicate when to finish sending server sent events. |
You typically want to schedule SSE event streams on a separate executor. The previous example uses @ExecuteOn to execute the stream on the I/O executor. |
The above example will send back a response of type text/event-stream
and for each Event emitted the Headline
type previously will be converted to JSON resulting in responses such as:
data: {"title":"Micronaut 1.0 Released","description":"Come and get it"}
data: {"title":"Micronaut 2.0 Released","description":"Come and get it"}
You can use the methods of the Event interface to customize the Server Sent Event data sent back including associating event ids, comments, retry timeouts etc.
6.24 WebSocket Support
Micronaut features dedicated support for creating WebSocket clients and servers. The io.micronaut.websocket.annotation package includes a set of annotations for defining both clients and servers.
6.24.1 Using @ServerWebSocket
The @ServerWebSocket annotation can be applied to any class that should map to a WebSocket URI. The following example is a simple chat WebSocket implementation:
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}") (1)
public class ChatServerWebSocket {
private WebSocketBroadcaster broadcaster;
public ChatServerWebSocket(WebSocketBroadcaster broadcaster) {
this.broadcaster = broadcaster;
}
@OnOpen (2)
public void onOpen(String topic, String username, WebSocketSession session) {
String msg = "[" + username + "] Joined!";
broadcaster.broadcastSync(msg, isValid(topic, session));
}
@OnMessage (3)
public void onMessage(
String topic,
String username,
String message,
WebSocketSession session) {
String msg = "[" + username + "] " + message;
broadcaster.broadcastSync(msg, isValid(topic, session)); (4)
}
@OnClose (5)
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));
}
}
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}") (1)
class ChatServerWebSocket {
private WebSocketBroadcaster broadcaster
ChatServerWebSocket(WebSocketBroadcaster broadcaster) {
this.broadcaster = broadcaster
}
@OnOpen (2)
void onOpen(String topic, String username, WebSocketSession session) {
String msg = "[" + username + "] Joined!"
broadcaster.broadcastSync(msg, isValid(topic, session))
}
@OnMessage (3)
void onMessage(
String topic,
String username,
String message,
WebSocketSession session) {
String msg = "[" + username + "] " + message
broadcaster.broadcastSync(msg, isValid(topic, session)) (4)
}
@OnClose (5)
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)) }
}
}
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}") (1)
class ChatServerWebSocket(private val broadcaster: WebSocketBroadcaster) {
@OnOpen (2)
fun onOpen(topic: String, username: String, session: WebSocketSession) {
val msg = "[$username] Joined!"
broadcaster.broadcastSync(msg, isValid(topic, session))
}
@OnMessage (3)
fun onMessage(
topic: String,
username: String,
message: String,
session: WebSocketSession) {
val msg = "[$username] $message"
broadcaster.broadcastSync(msg, isValid(topic, session)) (4)
}
@OnClose (5)
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)) }
}
}
1 | The @ServerWebSocket annotation is used to define the path the WebSocket is mapped under. The URI can be a URI template. |
2 | The @OnOpen annotation is used to declare a method that is invoked when the WebSocket is opened. |
3 | The @OnMessage annotation is used to declare a method that is invoked when a message is received. |
4 | You can use a WebSocketBroadcaster to broadcast messages to every WebSocket session. You can filter which sessions to communicate with a Predicate . Also, you could use the passed WebSocketSession instance to send a message to it with WebSocketSession::send . |
5 | The @OnClose annotation is used to declare a method that is invoked when the WebSocket is closed. |
A working example of WebSockets in action can be found in the Micronaut Examples GitHub repository. |
In terms of binding the method arguments to each WebSocket method can be:
-
A variable from the URI template (in the above example
topic
andusername
are variables in the URI template) -
An instance of WebSocketSession
The @OnClose Method
The @OnClose method can also optionally receive a CloseReason. 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 fromByteBuf
(you can register additional TypeConverter beans if you wish to support a custom type). -
A
byte[]
, aByteBuf
or a Java NIOByteBuffer
. -
A Plain Old Java Object (POJO). In the case of a POJO the POJO will be decoded by default as JSON using JsonMediaTypeCodec. 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 the WebSocketBroadcaster interface which blocks until the broadcast is complete. A similar sendSync
method exists in WebSocketSession 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 respective WebSocketBroadcaster and WebSocketSession 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 the WebSocketSession 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
The WebSocketSession is by default backed by an in-memory map. If you add the the session
module you can however share sessions between the HTTP server and the WebSocket server.
When sessions are backed by a persistent store such as Redis then after each message is processed the session is updated to the backing store. |
Using the CLI
If you have created your project using the Micronaut CLI and the default ( $ 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
6.24.2 Using @ClientWebSocket
The @ClientWebSocket annotation can be used in combination with the WebSocketClient interface to define WebSocket clients.
You can inject a reference to the a WebSocketClient instance using the @Client annotation:
@Inject
@Client("http://localhost:8080")
RxWebSocketClient webSocketClient;
This allows you to use the same service discovery and load balancing features for WebSocket clients.
Once you have a reference to the WebSocketClient interface you can use the connect
method to obtain a connected instance of a bean annotated with @ClientWebSocket.
For example consider the following implementation:
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}") (1)
public abstract class ChatClientWebSocket implements AutoCloseable { (2)
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) { (3)
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); (4)
}
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}") (1)
abstract class ChatClientWebSocket implements AutoCloseable { (2)
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) { (3)
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) (4)
}
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}") (1)
abstract class ChatClientWebSocket : AutoCloseable { (2)
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<*>) { (3)
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) (4)
}
1 | The class is abstract (more on that later) and is annotated with @ClientWebSocket |
2 | The client must implement AutoCloseable and you should ensure that the connection is closed at some point. |
3 | You can use the same annotations as on the server, in this case @OnOpen to obtain a reference to the underlying session. |
4 | The @OnMessage annotation can be used to define the method that receives responses from the server. |
You can also define abstract methods that start with either send
or broadcast
and these methods will be implemented for you at compile time. For example:
public abstract void send(String message);
Note by returning void
this tells Micronaut that the method is a blocking send. You can instead define methods that return either futures or a Publisher:
public abstract io.reactivex.Single<String> send(String message);
The above example defines a send method that returns an Single.
public abstract java.util.concurrent.Future<String> sendAsync(String message);
The above example defines a send method that executes asynchronously and returns a Future to access the results.
Once you have defined a client class you can connect to the client socket and start sending messages:
ChatClientWebSocket chatClient = webSocketClient.connect(ChatClientWebSocket.class, "/chat/football/fred").blockingFirst();
chatClient.send("Hello World!");
For illustration purposes we use blockingFirst() to obtain the client, it is however possible to combine connect (which returns an Flowable) to perform non-blocking interaction via WebSocket.
|
Using the CLI
If you have created your project using the Micronaut CLI and the default ( $ mn create-websocket-client MyChat | Rendered template WebsocketClient.java to destination src/main/java/example/MyChatClient.java |
6.25 HTTP/2 Support
Since Micronaut 2.x, Micronaut’s Netty-based HTTP server can be configured to support HTTP/2.
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 enable HTTPS support support. For development this can be done with:
h2
Protocol Supportmicronaut:
ssl:
enabled: true
buildSelfSigned: true
server:
http-version: 2.0
For production, see the configuring HTTPS section 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;
6.26 Server Events
The HTTP server will emit a number of Bean Events, defined in the io.micronaut.runtime.server.event package, that you can write listeners for. The following table summarizes those events:
Event | Description |
---|---|
Emitted when the server completes startup |
|
Emitted when the server shuts down |
|
Emitted after all ServerStartupEvent listeners have been executed and exposes the EmbeddedServerInstance |
|
Emitted after all ServerShutdownEvent listeners have been executed and exposes the EmbeddedServerInstance |
If you do significant work within a listener for a ServerStartupEvent this will slow down you startup time. |
The following example defines a ApplicationEventListener that listens for ServerStartupEvent:
import io.micronaut.context.event.ApplicationEventListener;
...
@Singleton
public class StartupListener implements ApplicationEventListener<ServerStartupEvent> {
@Override
public void onApplicationEvent(ServerStartupEvent event) {
// logic here
...
}
}
Alternatively, you can also use the @EventListener annotation on a method of any existing bean that accepts ServerStartupEvent
:
@EventListener
with ServerStartupEvent
import io.micronaut.runtime.server.event.*;
import io.micronaut.runtime.event.annotation.*;
...
@Singleton
public class MyBean {
@EventListener
public void onStartup(ServerStartupEvent event) {
// logic here
...
}
}
6.27 Configuring the HTTP Server
The HTTP server features a number of configuration options you may wish to tweak. They are defined in the NettyHttpServerConfiguration configuration class, which extends HttpServerConfiguration.
The following example shows how to tweak configuration options for the server via application.yml
:
micronaut:
server:
maxRequestSize: 1MB
host: localhost (1)
netty:
maxHeaderSize: 500KB (2)
worker:
threads: 8 (3)
childOptions:
autoRead: true (4)
1 | By default Micronaut will bind to all the network interfaces. Use localhost to bind only to loopback network interface |
2 | Maximum size for headers |
3 | Number of netty worker threads |
4 | Auto read request body |
Property | Type | Description |
---|---|---|
|
java.util.Map |
Sets the Netty child worker options. |
|
java.util.Map |
Sets the channel options. |
|
int |
Sets the maximum initial line length for the HTTP request. Default value (4096). |
|
int |
Sets the maximum size of any one header. Default value (8192). |
|
int |
Sets the maximum size of any single request chunk. Default value (8192). |
|
boolean |
Sets whether chunked transfer encoding is supported. Default value (true). |
|
boolean |
Sets whether to validate incoming headers. Default value (true). |
|
int |
Sets the initial buffer size. Default value (128). |
|
io.netty.handler.logging.LogLevel |
Sets the Netty log level. |
|
int |
Sets the minimum size of a request body must be in order to be compressed. Default value (1024). |
|
int |
Sets the compression level (0-9). Default value (6). |
|
boolean |
Sets whether to use netty’s native transport (epoll or kqueue) if available . Default value (false). |
|
java.lang.String |
Sets the fallback protocol to use when negotiating via ALPN. |
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
6.27.1 Configuring Server Thread Pools
The HTTP server is built on Netty which is designed as a non-blocking I/O toolkit in an event loop model.
The Netty worker event loop uses the "default" named event loop group. That event loop can be configured through micronaut.server.netty.worker
, or micronaut.netty.event-loops.default
, with the latter having precedence.
Property | Type | Description |
---|---|---|
|
java.lang.String |
Sets the name to use. |
|
int |
Sets the number of threads for the event loop group. |
|
java.lang.Integer |
Sets the I/O ratio. |
|
java.lang.String |
Sets the name of the executor. |
|
boolean |
Set whether to prefer the native transport if available |
The parent event loop can be configured with micronaut.server.netty.parent with the same configuration options.
|
The server can also be configured to use a different named worker event loop:
micronaut:
server:
netty:
worker:
event-loop-group: other
netty:
event-loops:
other:
num-threads: 10
The default value for the number of threads is the value of the system property io.netty.eventLoopThreads , or if not specified, the available processors x 2.
|
See the following table for configuring event loops:
Property | Type | Description |
---|---|---|
|
int |
|
|
java.lang.Integer |
|
|
boolean |
|
|
java.lang.String |
Blocking Operations
When dealing with blocking operations, Micronaut will shift the blocking operations to an unbound, caching I/O thread pool by default. You can configure the I/O thread pool using the ExecutorConfiguration named io
. For example:
micronaut:
executors:
io:
type: fixed
nThreads: 75
The above configuration will create a fixed thread pool with 75 threads.
6.27.2 Configuring the Netty Pipeline
You can customize the Netty pipeline by writing an Bean Event Listener that listens for the creation of ChannelPipelineCustomizer.
Both the Netty HTTP server and client implement this interface and it allows you to customize the Netty ChannelPipeline
and add additional handlers.
The ChannelPipelineCustomizer interface defines constants for the names of the various handlers Micronaut registers.
As an example the following demonstrates registing the Logbook library which includes additional Netty handlers to perform request and response logging:
import io.micronaut.context.annotation.Requires;
import io.micronaut.context.event.*;
import io.micronaut.http.netty.channel.ChannelPipelineCustomizer;
import org.zalando.logbook.Logbook;
import org.zalando.logbook.netty.*;
import javax.inject.Singleton;
@Requires(beans = Logbook.class)
@Singleton
public class LogbookPipelineCustomizer implements BeanCreatedEventListener<ChannelPipelineCustomizer> { (1)
private final Logbook logbook;
public LogbookPipelineCustomizer(Logbook logbook) {
this.logbook = logbook;
}
@Override
public ChannelPipelineCustomizer onCreated(BeanCreatedEvent<ChannelPipelineCustomizer> event) {
ChannelPipelineCustomizer customizer = event.getBean();
if (customizer.isServerChannel()) { (2)
customizer.doOnConnect(pipeline -> {
pipeline.addAfter(
ChannelPipelineCustomizer.HANDLER_HTTP_SERVER_CODEC,
"logbook",
new LogbookServerHandler(logbook)
);
return pipeline;
});
} else { (3)
customizer.doOnConnect(pipeline -> {
pipeline.addAfter(
ChannelPipelineCustomizer.HANDLER_HTTP_CLIENT_CODEC,
"logbook",
new LogbookClientHandler(logbook)
);
return pipeline;
});
}
return customizer;
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.context.event.*
import io.micronaut.http.netty.channel.ChannelPipelineCustomizer
import io.netty.channel.ChannelPipeline
import org.zalando.logbook.Logbook
import org.zalando.logbook.netty.*
import javax.inject.Singleton
@Requires(beans = Logbook.class)
@Singleton
class LogbookPipelineCustomizer implements BeanCreatedEventListener<ChannelPipelineCustomizer> { (1)
private final Logbook logbook
LogbookPipelineCustomizer(Logbook logbook) {
this.logbook = logbook
}
@Override
ChannelPipelineCustomizer onCreated(BeanCreatedEvent<ChannelPipelineCustomizer> event) {
ChannelPipelineCustomizer customizer = event.getBean()
if (customizer.isServerChannel()) { (2)
customizer.doOnConnect( { ChannelPipeline pipeline ->
pipeline.addAfter(
ChannelPipelineCustomizer.HANDLER_HTTP_SERVER_CODEC,
"logbook",
new LogbookServerHandler(logbook)
)
return pipeline
})
} else { (3)
customizer.doOnConnect({ ChannelPipeline pipeline ->
pipeline.addAfter(
ChannelPipelineCustomizer.HANDLER_HTTP_CLIENT_CODEC,
"logbook",
new LogbookClientHandler(logbook)
)
return pipeline
})
}
return customizer
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.context.event.*
import io.micronaut.http.netty.channel.ChannelPipelineCustomizer
import io.netty.channel.ChannelPipeline
import org.zalando.logbook.Logbook
import org.zalando.logbook.netty.*
import javax.inject.Singleton
@Requires(beans = [Logbook::class])
@Singleton
class LogbookPipelineCustomizer(private val logbook: Logbook) : BeanCreatedEventListener<ChannelPipelineCustomizer> { (1)
override fun onCreated(event: BeanCreatedEvent<ChannelPipelineCustomizer>): ChannelPipelineCustomizer {
val customizer = event.bean
if (customizer.isServerChannel) { (2)
customizer.doOnConnect { pipeline: ChannelPipeline ->
pipeline.addAfter(
ChannelPipelineCustomizer.HANDLER_HTTP_SERVER_CODEC,
"logbook",
LogbookServerHandler(logbook)
)
pipeline
}
} else { (3)
customizer.doOnConnect { pipeline: ChannelPipeline ->
pipeline.addAfter(
ChannelPipelineCustomizer.HANDLER_HTTP_CLIENT_CODEC,
"logbook",
LogbookClientHandler(logbook)
)
pipeline
}
}
return customizer
}
}
1 | A bean is created that implements ChannelPipelineCustomizer and requires the definition of a Logbook bean |
2 | If the bean being created is the server then the server handler is registered |
3 | if the bean being created is the client then the client handler is registered |
6.27.3 Configuring CORS
Micronaut supports CORS (Cross Origin Resource Sharing) out of the box. By default, CORS requests will be rejected. To enable processing of CORS requests, modify your configuration. For example with application.yml
:
micronaut:
server:
cors:
enabled: true
By only enabling CORS processing, a "wide open" strategy will be adopted that will allow requests from any origin.
To change the settings for all origins or a specific origin, change the configuration to provide a set of "configurations". By providing any configuration, the default "wide open" configuration is not configured.
micronaut:
server:
cors:
enabled: true
configurations:
all:
...
web:
...
mobile:
...
In the above example, three configurations are being provided. Their names (all
, web
, mobile
) are not important and have no significance inside Micronaut. They are there purely to be able to easily recognize the intended user of the configuration.
The same configuration properties can be applied to each configuration. See CorsOriginConfiguration for the reference of properties that can be defined. Each configuration supplied will have its values default to the default values of the corresponding fields.
When a CORS request is made, configurations are searched for allowed origins that are an exact match or match the request origin through a regular expression.
Allowed Origins
To allow any origin for a given configuration, simply don’t include the allowedOrigins
key in your configuration.
To specify a list of valid origins, set the allowedOrigins
key of the configuration to a list of strings. Each value can either be a static value (http://www.foo.com
) or a regular expression (^http(|s)://www\.google\.com$
).
Any regular expressions are passed to Pattern#compile and compared to the request origin with Matcher#matches.
micronaut:
server:
cors:
enabled: true
configurations:
web:
allowedOrigins:
- http://foo.com
- ^http(|s):\/\/www\.google\.com$
Allowed Methods
To allow any request method for a given configuration, simply don’t include the allowedMethods
key in your configuration.
To specify a list of allowed methods, set the allowedMethods
key of the configuration to a list of strings.
micronaut:
server:
cors:
enabled: true
configurations:
web:
allowedMethods:
- POST
- PUT
Allowed Headers
To allow any request header for a given configuration, simply don’t include the allowedHeaders
key in your configuration.
To specify a list of allowed headers, set the allowedHeaders
key of the configuration to a list of strings.
micronaut:
server:
cors:
enabled: true
configurations:
web:
allowedHeaders:
- Content-Type
- Authorization
Exposed Headers
To configure the list of headers that are sent in the response to a CORS request through the Access-Control-Expose-Headers
header, include a list of strings for the exposedHeaders
key in your configuration. By default no headers are exposed.
micronaut:
server:
cors:
enabled: true
configurations:
web:
exposedHeaders:
- Content-Type
- Authorization
Allow Credentials
Credentials are allowed by default for CORS requests. To disallow credentials, simply set the allowCredentials
option to false
.
micronaut:
server:
cors:
enabled: true
configurations:
web:
allowCredentials: false
Max Age
The default maximum age that preflight requests can be cached is 30 minutes. To change that behavior, specify a value in seconds.
micronaut:
server:
cors:
enabled: true
configurations:
web:
maxAge: 3600 # 1 hour
Multiple Header Values
By default when a header has multiple values, multiple headers will be sent each with a single value. It is possible to change the behavior to send a single header with the list of values comma separated by setting a configuration option.
micronaut:
server:
cors:
single-header: true
6.27.4 Securing the Server with HTTPS
Micronaut supports HTTPS out of the box. By default HTTPS is disabled and all requests are served using HTTP. To enable
HTTPS support, modify your configuration. For example with application.yml
:
micronaut:
ssl:
enabled: true
buildSelfSigned: true (1)
1 | Micronaut will create a self-signed certificate. |
By default Micronaut with HTTPS support starts on port 8443 but you can change the port the property
micronaut.ssl.port .
|
Keep in mind that this configuration will generate a warning on the browser. |
Using a valid x509 certificate
It is also possible to configure Micronaut to use an existing valid x509 certificate, for example one created with
Let’s Encrypt. You will need the server.crt
and server.key
files and convert them to a
PKCS #12 file.
$ openssl pkcs12 -export \
-in server.crt \ (1)
-inkey server.key \ (2)
-out server.p12 \ (3)
-name someAlias \ (4)
-chain -CAfile ca.crt -caname root
1 | The original server.crt file |
2 | The original server.key file |
3 | The server.p12 file that will be created |
4 | The alias for the certificate |
During the creation of the server.p12
file it is necessary to define a password that will be required later when using
the certificate in Micronaut.
Now modify your configuration:
micronaut:
ssl:
enabled: true
keyStore:
path: classpath:server.p12 (1)
password: mypassword (2)
type: PKCS12
1 | The p12 file created. It can also be referenced as file:/path/to/the/file |
2 | The password defined during the export |
With this configuration if we start Micronaut and connect to https://localhost:8443
we still see the warning on the
browser but if we inspect the certificate we can check that it’s the one generated by Let’s Encrypt.
Finally we can test that the certificate is valid for the browser just by adding an alias to the domain in /etc/hosts
file:
$ cat /etc/hosts
...
127.0.0.1 my-domain.org
...
Now we can connect to https://my-domain.org:8443
:
Using Java Keystore (JKS)
It is not recommended using this type of certificate because it is a proprietary format and it’s better to use a PKCS12 format. In any case Micronaut also supports it.
Convert the p12
certificate to a JKS one:
$ keytool -importkeystore \
-deststorepass newPassword -destkeypass newPassword \ (1)
-destkeystore server.keystore \ (2)
-srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass mypassword \ (3)
-alias someAlias (4)
1 | It is necessary to define a the password for the keystore |
2 | The file that will be created |
3 | The PKCS12 file created before and the password defined during the creation |
4 | The alias used before |
If either srcstorepass or alias are not the same as defined in the p12 file, the conversion will fail.
|
Now modify your configuration:
micronaut:
ssl:
enabled: true
keyStore:
path: classpath:server.keystore
password: newPassword
type: JKS
Start Micronaut and the application is running on https://localhost:8443
using the certificate in the keystore.
6.27.5 Enabling HTTP and HTTPS
Micronaut supports binding both HTTP and HTTPS out of the box. To enable
dual protocol support, modify your configuration. For example with application.yml
:
micronaut:
ssl:
enabled: true
buildSelfSigned: true (1)
server:
dualProtocol : true (2)
1 | You will need to configure ssl for https to work. In this example we are just using self signed but see Securing the Server with HTTPS for other configurations |
2 | To enable http & https is an opt-in feature, setting the dualProtocol flag enables that, by default Micronaut will only enable one or the other |
6.27.6 Enabling Access Logger
In the spirit of apache mod_log_config and Tomcat Access Log Valve, it is possible to enabled an access logger for the http server (it works for both http/1 and http/2.)
To enable and configure the access logger, in application.yml
set:
micronaut:
server:
netty:
access-logger:
enabled: true # Enables the access logger
logger-name: my-access-logger # A logger name, optional, default is `HTTP_ACCESS_LOGGER`
log-format: common # A log format, optional, default is Common Log Format
Logback Configuration
In addition to enabling the access logger, you have to add a logger for the specified or default logger name. For instance using the default logger name for logback:
<appender
name="httpAccessLogAppender"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<append>true</append>
<file>log/http-access.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<!-- daily rollover -->
<fileNamePattern>log/http-access-%d{yyyy-MM-dd}.log
</fileNamePattern>
<maxHistory>7</maxHistory>
</rollingPolicy>
<encoder>
<charset>UTF-8</charset>
<pattern>%msg%n</pattern>
</encoder>
<immediateFlush>true</immediateFlush>
</appender>
<logger name="HTTP_ACCESS_LOGGER" additivity="false" level="info">
<appender-ref ref="httpAccessLogAppender" />
</logger>
The pattern should only have the message marker as other elements will be processed by the access logger.
Log Format
The syntax is based on Apache httpd log format.
Here are the supported markers:
-
%a - Remote IP address
-
%A - Local IP address
-
%b - Bytes sent, excluding HTTP headers, or '-' if no bytes were sent
-
%B - Bytes sent, excluding HTTP headers
-
%h - Remote host name
-
%H - Request protocol
-
%{<header>}i - Request header. If the argument is omitted (%i) all headers will be printed
-
%{<header>}o - Response header. If the argument is omitted (%o) all headers will be printed
-
%{<cookie>}C - Request cookie (COOKIE). If the argument is omitted (%C) all cookies will be printed
-
%{<cookie>}c - Response cookie (SET_COOKIE). If the argument is omitted (%c) all cookies will be printed
-
%l - Remote logical username from identd (always returns '-')
-
%m - Request method
-
%p - Local port
-
%q - Query string (excluding the '?' character)
-
%r - First line of the request
-
%s - HTTP status code of the response
-
%{<format>}t - Date and time. If the argument is ommitted the Common Log Format format is used ("'['dd/MMM/yyyy:HH:mm:ss Z']'").
-
If the format starts with begin: (default) the time is taken at the beginning of the request processing. If it starts with end: it is the time when the log entry gets written, close to the end of the request processing.
-
The format should follow the DateTimeFormatter syntax.
-
-
%{property}u - Remote user that was authenticated. When micronaut-session is on the classpath, returns the session id if the argument is omitted or the specified property otherwise prints '-'
-
%U - Requested URI
-
%v - Local server name
-
%D - Time taken to process the request, in millis
-
%T - Time taken to process the request, in seconds
In addition, you can use the following aliases for commonly utilized patterns:
-
common -
%h %l %u %t "%r" %s %b
for Common Log Format (CLF) -
combined -
%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"
for Combined Log Format
6.28 Server Side View Rendering
Micronaut supports Server Side View Rendering.
See the documentation for Micronaut Views for more information.
6.29 OpenAPI / Swagger Support
To configure Micronaut integration with OpenAPI/Swagger, please follow these instructions
6.30 GraphQL Support
GraphQL is a query language for building APIs that provides an intuitive and flexible syntax and a system for describing data requirements and interactions.
See the documentation for Micronaut GraphQL for more information on how to build GraphQL applications with Micronaut.
7 The HTTP Client
Using the CLI
If you are creating your project using the Micronaut CLI, the |
A critical component of any Microservice architecture is the client communication between Microservices. With that in mind Micronaut features a built in HTTP client that has both a low-level API and a higher level AOP-driven API.
Regardless whether you choose to use Micronaut’s HTTP server, you may wish to use the Micronaut HTTP client in your application since it is a feature-rich client implementation. |
To use the HTTP client you must have the http-client
dependency on your classpath.
implementation("io.micronaut:micronaut-http-client")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-http-client</artifactId>
</dependency>
Since the higher level API is built on the low-level HTTP client, we will first introduce the low-level client.
7.1 Using the Low-Level HTTP Client
The HttpClient interface forms the basis for the low-level API. This interfaces declares methods to help ease executing HTTP requests and receive responses.
The majority of the methods in the HttpClient interface returns Reactive Streams Publisher instances, which is not always the most useful interface to work against, hence a sub-interface called RxHttpClient is included that provides a variation of the HttpClient interface that returns RxJava Flowable types.
7.1.1 Sending your first HTTP request
Obtaining a HttpClient
There are a few ways by which you can obtain a reference to a HttpClient. The most common way is using the Client annotation. For example:
@Client("https://api.twitter.com/1.1") @Inject RxHttpClient httpClient;
The above example will inject a client that targets the Twitter API.
@field:Client("\${myapp.api.twitter.url}") @Inject lateinit var httpClient: RxHttpClient
The above Kotlin example will inject a client that targets the Twitter API using a configuration path. Note the required escaping (backslash) on "\${path.to.config}"
which is required due to Kotlin string interpolation.
The Client annotation is also a custom scope that will manage the creation of HttpClient instances and ensure they are shutdown when the application shuts down.
The value you pass to the Client annotation can be one of the following:
-
A absolute URI. Example
https://api.twitter.com/1.1
-
A relative URI, in which case the server targeted will be the current server (useful for testing)
-
A service identifier. See the section on Service Discovery for more information on this topic.
Another way to create an HttpClient
is with the create
static method of the RxHttpClient, however this approach is not recommended as you will have to ensure you manually shutdown the client and of course no dependency injection will occur for the created client.
Performing an HTTP GET
Generally there are two methods of interest when working with the HttpClient
. The first method is called retrieve
, which will execute an HTTP request and return the body in whichever type you request (by default a String
) as an RxJava Flowable.
The retrieve
method accepts an HttpRequest object or a String
URI to the endpoint you wish to request.
The following example shows how to use retrieve
to execute an HTTP GET
and receive the response body as a String
:
String uri = UriBuilder.of("/hello/{name}")
.expand(Collections.singletonMap("name", "John"))
.toString();
assertEquals("/hello/John", uri);
String result = client.toBlocking().retrieve(uri);
assertEquals(
"Hello John",
result
);
when:
String uri = UriBuilder.of("/hello/{name}")
.expand(Collections.singletonMap("name", "John"))
.toString()
then:
"/hello/John" == uri
when:
String result = client.toBlocking().retrieve(uri)
then:
"Hello John" == result
val uri = UriBuilder.of("/hello/{name}")
.expand(Collections.singletonMap("name", "John"))
.toString()
uri shouldBe "/hello/John"
val result = client.toBlocking().retrieve(uri)
result shouldBe "Hello John"
Note that in this example, for illustration purposes we are calling toBlocking()
to return a blocking version of the client. However, in production code you should not do this and instead rely on the non-blocking nature of the Micronaut HTTP server.
For example the following @Controller
method calls another endpoint in a non-blocking manner:
import io.micronaut.http.HttpStatus;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.*;
import io.micronaut.http.client.RxHttpClient;
import io.micronaut.http.client.annotation.Client;
import io.reactivex.Maybe;
import static io.micronaut.http.HttpRequest.GET;
@Get("/hello/{name}")
Maybe<String> hello(String name) { (1)
return httpClient.retrieve( GET("/hello/" + name) )
.firstElement(); (2)
}
import io.micronaut.http.HttpStatus
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.*
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.client.annotation.Client
import io.reactivex.Maybe
import static io.micronaut.http.HttpRequest.GET
@Get("/hello/{name}")
Maybe<String> hello(String name) { (1)
return httpClient.retrieve( GET("/hello/" + name) )
.firstElement() (2)
}
import io.micronaut.http.HttpStatus
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.*
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.client.annotation.Client
import io.reactivex.Maybe
import io.micronaut.http.HttpRequest.GET
@Get("/hello/{name}")
internal fun hello(name: String): Maybe<String> { (1)
return httpClient.retrieve(GET<Any>("/hello/$name"))
.firstElement() (2)
}
1 | The method hello returns a Maybe which may or may not emit an item. If an item is not emitted a 404 is returned. |
2 | The retrieve method is called which returns a Flowable which has a firstElement method that returns the first emitted item or nothing |
Using RxJava (or Reactor if you prefer) you can easily and efficiently compose multiple HTTP client calls without blocking (which will limit the throughput and scalability of your application). |
Debugging / Tracing the HTTP Client
To debug the requests being sent and received from the HTTP client you can enable tracing logging via your logback.xml
file:
<logger name="io.micronaut.http.client" level="TRACE"/>
Client Specific Debugging / Tracing
To enable client-specific logging you could configure the default logger for all HTTP clients. And, you could also configure different loggers for different clients using Client Specific Configuration. For example, in application.yml
:
micronaut:
http:
client:
logger-name: mylogger
services:
otherClient:
logger-name: other.client
And, then enable logging in logback.yml
:
<logger name="mylogger" level="DEBUG"/>
<logger name="other.client" level="TRACE"/>
Customizing the HTTP Request
The previous example demonstrated using the static methods of the HttpRequest interface to construct a MutableHttpRequest instance. Like the name suggests a MutableHttpRequest
can be mutated including the ability to add headers, customize the request body and so on. For example:
Flowable<String> response = client.retrieve(
GET("/hello/John")
.header("X-My-Header", "SomeValue")
);
Flowable<String> response = client.retrieve(
GET("/hello/John")
.header("X-My-Header", "SomeValue")
)
val response = client.retrieve(
GET<Any>("/hello/John")
.header("X-My-Header", "SomeValue")
)
The above example adds an additional header called X-My-Header
to the request before it is sent. The MutableHttpRequest interface has a bunch more convenience methods that make it easy to modify the request in common ways.
Reading JSON Responses
Typically with Microservices a message encoding format is used such as JSON. Micronaut’s HTTP client leverages Jackson for JSON parsing hence whatever type Jackson can decode can passed as a second argument to retrieve
.
For example consider the following @Controller
method that returns a JSON response:
@Get("/greet/{name}")
Message greet(String name) {
return new Message("Hello " + name);
}
@Get("/greet/{name}")
Message greet(String name) {
return new Message("Hello " + name)
}
@Get("/greet/{name}")
internal fun greet(name: String): Message {
return Message("Hello $name")
}
The method above returns a POJO of type Message
which looks like:
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
public class Message {
private final String text;
@JsonCreator
public Message(@JsonProperty("text") String text) {
this.text = text;
}
public String getText() {
return text;
}
}
import com.fasterxml.jackson.annotation.JsonCreator
import com.fasterxml.jackson.annotation.JsonProperty
class Message {
private final String text
@JsonCreator
Message(@JsonProperty("text") String text) {
this.text = text
}
String getText() {
return text
}
}
import com.fasterxml.jackson.annotation.JsonCreator
import com.fasterxml.jackson.annotation.JsonProperty
class Message @JsonCreator
constructor(@param:JsonProperty("text") val text: String)
Jackson annotations are used to map the constructor |
On the client end you can call this endpoint and decode the JSON into a map using the retrieve
method as follows:
Flowable<Map> response = client.retrieve(
GET("/greet/John"), Map.class
);
Flowable<Map> response = client.retrieve(
GET("/greet/John"), Map.class
)
var response: Flowable<Map<*, *>> = client.retrieve(
GET<Any>("/greet/John"), Map::class.java
)
The above examples decodes the response into a Map, representing the JSON. If you wish to customize the type of the key and string you can use the Argument.of(..)
method:
response = client.retrieve(
GET("/greet/John"),
Argument.of(Map.class, String.class, String.class) (1)
);
response = client.retrieve(
GET("/greet/John"),
Argument.of(Map.class, String.class, String.class) (1)
)
response = client.retrieve(
GET<Any>("/greet/John"),
Argument.of(Map::class.java, String::class.java, String::class.java) (1)
)
1 | The Argument.of method is used to return a Map whether the key and value are typed as String |
Whilst retrieving JSON as a map can be desirable, more often than not you will want to decode objects into Plain Old Java Objects (POJOs). To do that simply pass the type instead:
Flowable<Message> response = client.retrieve(
GET("/greet/John"), Message.class
);
assertEquals(
"Hello John",
response.blockingFirst().getText()
);
when:
Flowable<Message> response = client.retrieve(
GET("/greet/John"), Message.class
)
then:
"Hello John" == response.blockingFirst().getText()
val response = client.retrieve(
GET<Any>("/greet/John"), Message::class.java
)
response.blockingFirst().text shouldBe "Hello John"
Note how you can use the same Java type on both the client and the server. The implication of this is that typically you will want to define a common API project where you define the interfaces and types that define your API.
Decoding Other Content Types
If the server you are communicating with uses a custom content type that is not JSON by default Micronaut’s HTTP client will not know how to decode this type.
To resolve this issue you can register MediaTypeCodec as a bean and it will be automatically picked up and used to decode (or encode) messages.
Receiving the Full HTTP Response
Sometimes, receiving just the object is not enough and you need information about the response. In this case, instead of retrieve
you should use the exchange
method:
Flowable<HttpResponse<Message>> call = client.exchange(
GET("/greet/John"), Message.class (1)
);
HttpResponse<Message> response = call.blockingFirst();
Optional<Message> message = response.getBody(Message.class); (2)
// check the status
assertEquals(
HttpStatus.OK,
response.getStatus() (3)
);
// check the body
assertTrue(message.isPresent());
assertEquals(
"Hello John",
message.get().getText()
);
when:
Flowable<HttpResponse<Message>> call = client.exchange(
GET("/greet/John"), Message.class (1)
)
HttpResponse<Message> response = call.blockingFirst();
Optional<Message> message = response.getBody(Message.class) (2)
// check the status
then:
HttpStatus.OK == response.getStatus() (3)
// check the body
message.isPresent()
"Hello John" == message.get().getText()
val call = client.exchange(
GET<Any>("/greet/John"), Message::class.java (1)
)
val response = call.blockingFirst()
val message = response.getBody(Message::class.java) (2)
// check the status
response.status shouldBe HttpStatus.OK (3)
// check the body
message.isPresent shouldBe true
message.get().text shouldBe "Hello John"
1 | The exchange method is used to receive the HttpResponse |
2 | The body can be retrieved using the getBody(..) method of the response |
3 | Other aspects of the response, such as the HttpStatus can be checked |
The above example receives the full HttpResponse object from which you can obtain headers and other useful information.
7.1.2 Posting a Request Body
All the examples up until now have used the same HTTP method i.e GET
. The HttpRequest interface has factory methods for all the different HTTP methods. The following table summarizes the available methods:
Method | Description | Allows Body |
---|---|---|
Constructs an HTTP |
|
|
Constructs an HTTP |
|
|
Constructs an HTTP |
|
|
Constructs an HTTP |
|
|
Constructs an HTTP |
|
|
Constructs an HTTP |
|
|
Constructs an HTTP |
|
A create
method also exists to construct a request for any HttpMethod type. Since the POST
, PUT
and PATCH
methods require a body, a second argument which is the body object is required.
The following example demonstrates how to send a simply String
body:
String
body Flowable<HttpResponse<String>> call = client.exchange(
POST("/hello", "Hello John") (1)
.contentType(MediaType.TEXT_PLAIN_TYPE)
.accept(MediaType.TEXT_PLAIN_TYPE), (2)
String.class (3)
);
String
body Flowable<HttpResponse<String>> call = client.exchange(
POST("/hello", "Hello John") (1)
.contentType(MediaType.TEXT_PLAIN_TYPE)
.accept(MediaType.TEXT_PLAIN_TYPE), (2)
String.class (3)
)
String
body val call = client.exchange(
POST("/hello", "Hello John") (1)
.contentType(MediaType.TEXT_PLAIN_TYPE)
.accept(MediaType.TEXT_PLAIN_TYPE), String::class.java (3)
)
1 | The POST method is used with the first argument being the URI and the second argument the body |
2 | The content type and accepted type are set to text/plain (the default content type is application/json ) |
3 | The expected response type is a String |
Sending JSON
The previous example sends plain text, if you wish send JSON you can simply pass the object you wish to encode as JSON, whether that be a map or a POJO. As long as Jackson is able to encode it.
For example, the Message
class from the previous section, you can create an instance and pass it to the POST
method:
Flowable<HttpResponse<Message>> call = client.exchange(
POST("/greet", new Message("Hello John")), (1)
Message.class (2)
);
Flowable<HttpResponse<Message>> call = client.exchange(
POST("/greet", new Message("Hello John")), (1)
Message.class (2)
)
val call = client.exchange(
POST("/greet", Message("Hello John")), Message::class.java (2)
)
1 | And instance of Message is created and passed to the POST method |
2 | The same class is used to decode the response |
With the above example the following JSON will be sent as the body of the request:
{"text":"Hello John"}
The JSON itself can be customized however you want using Jackson Annotations.
Using a URI Template
If some of the properties of the object need to be in the URI being posted to you can use a URI template.
For example imagine you have a class Book
that has a property called title
. You can represent the title
property in the URI template and then populate it from an instance of Book
. For example:
Flowable<HttpResponse<Book>> call = client.exchange(
POST("/amazon/book/{title}", new Book("The Stand")),
Book.class
);
Flowable<HttpResponse<Book>> call = client.exchange(
POST("/amazon/book/{title}", new Book("The Stand")),
Book.class
);
val call = client.exchange(
POST("/amazon/book/{title}", Book("The Stand")),
Book::class.java
)
In the above case the title
property of the passed object will be included in the URI being posted to.
Sending Form Data
You can also encode a POJO or a map as regular form data instead of JSON. Just set the content type to application/x-www-form-urlencoded
on the post request:
Flowable<HttpResponse<Book>> call = client.exchange(
POST("/amazon/book/{title}", new Book("The Stand"))
.contentType(MediaType.APPLICATION_FORM_URLENCODED),
Book.class
);
Flowable<HttpResponse<Book>> call = client.exchange(
POST("/amazon/book/{title}", new Book("The Stand"))
.contentType(MediaType.APPLICATION_FORM_URLENCODED),
Book.class
)
val call = client.exchange(
POST("/amazon/book/{title}", Book("The Stand"))
.contentType(MediaType.APPLICATION_FORM_URLENCODED),
Book::class.java
)
Note that Jackson is used to bind form data too, so to customize the binding process you can use Jackson annotations.
7.1.3 Multipart Client Uploads
The Micronaut HTTP Client supports the ability to create multipart requests. In order to build a multipart request you must set the content type to multipart/form-data
and set the body to be an instance of MultipartBody:
For example:
import io.micronaut.http.client.multipart.MultipartBody;
String toWrite = "test file";
File file = File.createTempFile("data", ".txt");
FileWriter writer = new FileWriter(file);
writer.write(toWrite);
writer.close();
MultipartBody requestBody = MultipartBody.builder() (1)
.addPart( (2)
"data",
file.getName(),
MediaType.TEXT_PLAIN_TYPE,
file
).build() ; (3)
import io.micronaut.http.multipart.CompletedFileUpload
import io.micronaut.http.multipart.StreamingFileUpload
import io.micronaut.http.client.multipart.MultipartBody
import org.reactivestreams.Publisher
File file = new File(uploadDir, "data.txt")
file.text = "test file"
file.createNewFile()
MultipartBody requestBody = MultipartBody.builder() (1)
.addPart( (2)
"data",
file.name,
MediaType.TEXT_PLAIN_TYPE,
file
).build() (3)
import io.micronaut.http.client.multipart.MultipartBody
val toWrite = "test file"
val file = File.createTempFile("data", ".txt")
val writer = FileWriter(file)
writer.write(toWrite)
writer.close()
val requestBody = MultipartBody.builder() (1)
.addPart( (2)
"data",
file.name,
MediaType.TEXT_PLAIN_TYPE,
file
).build() (3)
1 | You need to create a MultipartBody builder for adding parts to the body. |
2 | Method to add a part to the body, in this case a file. There are different variations of this method which you can see in MultipartBody.Builder. |
3 | Call the build method to assemble all parts from the builder into a MultipartBody. At least one part is required. |
HttpRequest.POST("/multipart/upload", requestBody) (1)
.contentType(MediaType.MULTIPART_FORM_DATA_TYPE) (2)
HttpRequest.POST("/multipart/upload", requestBody) (1)
.contentType(MediaType.MULTIPART_FORM_DATA_TYPE) (2)
HttpRequest.POST("/multipart/upload", requestBody) (1)
.contentType(MediaType.MULTIPART_FORM_DATA_TYPE) (2)
1 | The multipart request body with different sets of data. |
2 | Set the content-type header of the request to multipart/form-data . |
7.1.4 Streaming JSON over HTTP
Micronaut’s HTTP client includes support for streaming data over HTTP via the RxStreamingHttpClient interface which includes methods specific to HTTP streaming including:
Method | Description |
---|---|
|
Returns a stream of data as a Flowable of ByteBuffer |
|
Returns the HttpResponse wrapping a Flowable of ByteBuffer |
|
Returns a non-blocking stream of JSON objects |
In order to do JSON streaming you should on the server side declare a controller method that returns a application/x-json-stream
of JSON objects. For example:
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.reactivex.Flowable;
import java.time.ZonedDateTime;
import java.util.concurrent.TimeUnit;
@Get(value = "/headlines", processes = MediaType.APPLICATION_JSON_STREAM) (1)
Flowable<Headline> streamHeadlines() {
return Flowable.fromCallable(() -> { (2)
Headline headline = new Headline();
headline.setText("Latest Headline at " + ZonedDateTime.now());
return headline;
}).repeat(100) (3)
.delay(1, TimeUnit.SECONDS); (4)
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.reactivex.Flowable
import java.time.ZonedDateTime
import java.util.concurrent.TimeUnit
@Get(value = "/headlines", processes = MediaType.APPLICATION_JSON_STREAM) (1)
Flowable<Headline> streamHeadlines() {
Flowable.fromCallable({ (2)
Headline headline = new Headline()
headline.setText("Latest Headline at " + ZonedDateTime.now())
return headline
}).repeat(100) (3)
.delay(1, TimeUnit.SECONDS) (4)
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.reactivex.Flowable
import java.time.ZonedDateTime
import java.util.concurrent.TimeUnit
@Get(value = "/headlines", processes = [MediaType.APPLICATION_JSON_STREAM]) (1)
internal fun streamHeadlines(): Flowable<Headline> {
return Flowable.fromCallable {
(2)
val headline = Headline()
headline.text = "Latest Headline at " + ZonedDateTime.now()
headline
}.repeat(100) (3)
.delay(1, TimeUnit.SECONDS) (4)
}
1 | A method streamHeadlines is defined that produces application/x-json-stream |
2 | A Flowable is created from a Callable function (note no blocking occurs within the function so this is ok, otherwise you would want to subscribeOn an I/O thread pool). |
3 | The Flowable is set to repeat 100 times |
4 | The Flowable will emit items with a delay of 1 second between each item |
The server does not have to be written in Micronaut, any server that supports JSON streaming will do. |
Then on the client simply subscribe to the stream using jsonStream
and every time the server emits a JSON object the client will decode and consume it:
Flowable<Headline> headlineStream = client.jsonStream(GET("/streaming/headlines"), Headline.class); (1)
CompletableFuture<Headline> future = new CompletableFuture<>(); (2)
headlineStream.subscribe(new Subscriber<Headline>() {
@Override
public void onSubscribe(Subscription s) {
s.request(1); (3)
}
@Override
public void onNext(Headline headline) {
System.out.println("Received Headline = " + headline.getText());
future.complete(headline); (4)
}
@Override
public void onError(Throwable t) {
future.completeExceptionally(t); (5)
}
@Override
public void onComplete() {
// no-op (6)
}
});
Flowable<Headline> headlineStream = client.jsonStream(GET("/streaming/headlines"), Headline.class) (1)
CompletableFuture<Headline> future = new CompletableFuture<>() (2)
headlineStream.subscribe(new Subscriber<Headline>() {
@Override
void onSubscribe(Subscription s) {
s.request(1) (3)
}
@Override
void onNext(Headline headline) {
System.out.println("Received Headline = " + headline.getText())
future.complete(headline) (4)
}
@Override
void onError(Throwable t) {
future.completeExceptionally(t) (5)
}
@Override
void onComplete() {
// no-op (6)
}
})
val headlineStream = client.jsonStream(GET<Any>("/streaming/headlines"), Headline::class.java) (1)
val future = CompletableFuture<Headline>() (2)
headlineStream.subscribe(object : Subscriber<Headline> {
override fun onSubscribe(s: Subscription) {
s.request(1) (3)
}
override fun onNext(headline: Headline) {
println("Received Headline = " + headline.text!!)
future.complete(headline) (4)
}
override fun onError(t: Throwable) {
future.completeExceptionally(t) (5)
}
override fun onComplete() {
// no-op (6)
}
})
1 | The jsonStream method is used return a Flowable |
2 | A CompletableFuture is used in the example to receive a value, but what you do with each emitted item is application specific |
3 | The Subscription is used to request a single item. You can use the Subscription to regulate back pressure and demand. |
4 | The onNext method is called when an item is emitted |
5 | The onError method is called when an error occurs |
6 | The onComplete method is called when all Headline instances have been emitted |
Note neither the server or the client in the example above perform blocking I/O at any point.
7.1.5 Configuring HTTP clients
Global Configuration for All Clients
The default HTTP client configuration is a Configuration Properties called DefaultHttpClientConfiguration that allows configuring the default behaviour for all HTTP clients. For example, in application.yml
:
micronaut:
http:
client:
read-timeout: 5s
The above example sets of readTimeout
property of the HttpClientConfiguration class.
Client Specific Configuration
If you wish to have a separate configuration per client then there a couple of options. You can configure Service Discovery manually in application.yml
and apply per-client configuration:
micronaut:
http:
services:
foo:
urls:
- http://foo1
- http://foo2
read-timeout: 5s (1)
1 | The read timeout is applied to the foo client. |
WARN: This client configuration can be used in conjunction with the @Client
annotation, either by injecting an HttpClient
directly or use on a client interface. In any case, all other attributes on the annotation will be ignored other than the service id.
Then simply inject the named client configuration:
@Client("foo") @Inject RxHttpClient httpClient;
You can also simply define a bean that extends from HttpClientConfiguration and ensuring that the javax.inject.Named
annotation is used to name it appropriately:
@Named("twitter")
@Singleton
class TwitterHttpClientConfiguration extends HttpClientConfiguration {
public TwitterHttpClientConfiguration(ApplicationConfiguration applicationConfiguration) {
super(applicationConfiguration);
}
}
This configuration will then be picked up if you inject a service called twitter
using @Client
using Service Discovery:
@Client("twitter") @Inject RxHttpClient httpClient;
Alternatively if you are not using service discovery then you can use the configuration
member of @Client
to refer to a specific type:
@Client(value="https://api.twitter.com/1.1",
configuration=TwitterHttpClientConfiguration.class)
@Inject
RxHttpClient httpClient;
Using HTTP Client Connection Pooling
If you have a client that needs to handle a significant number of requests then you can benefit from enabling HTTP client connection pooling. The following configuration will enable pooling for the foo
client:
micronaut:
http:
services:
foo:
urls:
- http://foo1
- http://foo2
pool:
enabled: true (1)
max-connections: 50 (2)
1 | Enables the pool |
2 | Sets the maximum number of connections in the pool |
See the API for ConnectionPoolConfiguration for details on available options to configure the pool.
Configuring Event Loop Groups
By default Micronaut will share a common Netty EventLoopGroup
for worker threads and all HTTP clients threads.
This common EventLoopGroup
can be configured via the micronaut.netty.event-loops.default
property:
micronaut:
netty:
event-loops:
default:
num-threads: 10
prefer-native-transport: true
You can also use the micronaut.netty.event-loops
setting to configure one or more additional event loops. The following table summarizes the properties:
Property | Type | Description |
---|---|---|
|
int |
|
|
java.lang.Integer |
|
|
boolean |
|
|
java.lang.String |
For example, if your interactions with an HTTP client involve CPU intensive work it may be worthwhile configuring a separate EventLoopGroup
for one or all clients.
The following example configures an additional event loop group called "other" that uses 10 threads:
micronaut:
netty:
event-loops:
other:
num-threads: 10
prefer-native-transport: true
Once an additional event loop has been configured you can alter the HTTP client configuration to use the newly defined event loop group:
micronaut:
http:
client:
event-loop-group: other
7.1.6 Error Responses
If an HTTP response is returned with a code of 400 or above, an HttpClientResponseException is created. The exception contains the original response. How that exception gets thrown depends on the return type of the method.
For blocking clients, the exception is thrown and should be caught and handled by the caller. For reactive clients, the exception is passed through the publisher as an error.
7.1.7 Bind Errors
Often you want to consume an endpoint and bind to a POJO if the request is successful or bind to a different POJO if an error occurs. The following example shows how to invoke exchange
with a success and error type.
@Controller("/books")
public class BooksController {
@Get("/{isbn}")
public HttpResponse find(String isbn) {
if (isbn.equals("1680502395")) {
Map<String, Object> m = new HashMap<>();
m.put("status", 401);
m.put("error", "Unauthorized");
m.put("message", "No message available");
m.put("path", "/books/"+isbn);
return HttpResponse.status(HttpStatus.UNAUTHORIZED).body(m);
}
return HttpResponse.ok(new Book("1491950358", "Building Microservices"));
}
}
@Controller("/books")
class BooksController {
@Get("/{isbn}")
HttpResponse find(String isbn) {
if (isbn == "1680502395") {
Map<String, Object> m = new HashMap<>()
m.put("status", 401)
m.put("error", "Unauthorized")
m.put("message", "No message available")
m.put("path", "/books/"+isbn)
return HttpResponse.status(HttpStatus.UNAUTHORIZED).body(m)
}
return HttpResponse.ok(new Book("1491950358", "Building Microservices"))
}
}
@Controller("/books")
class BooksController {
@Get("/{isbn}")
fun find(isbn: String): HttpResponse<*> {
if (isbn == "1680502395") {
val m = HashMap<String, Any>()
m["status"] = 401
m["error"] = "Unauthorized"
m["message"] = "No message available"
m["path"] = "/books/$isbn"
return HttpResponse.status<Any>(HttpStatus.UNAUTHORIZED).body(m)
}
return HttpResponse.ok(Book("1491950358", "Building Microservices"))
}
}
@Test
public void afterAnHttpClientExceptionTheResponseBodyCanBeBoundToAPOJO() {
try {
client.toBlocking().exchange(HttpRequest.GET("/books/1680502395"),
Argument.of(Book.class), (1)
Argument.of(CustomError.class)); (2)
} catch (HttpClientResponseException e) {
assertEquals(HttpStatus.UNAUTHORIZED, e.getResponse().getStatus());
Optional<CustomError> jsonError = e.getResponse().getBody(CustomError.class);
assertTrue(jsonError.isPresent());
assertEquals(401, jsonError.get().status);
assertEquals("Unauthorized", jsonError.get().error);
assertEquals("No message available", jsonError.get().message);
assertEquals("/books/1680502395", jsonError.get().path);
}
}
def "after an HttpClientException the response body can be bound to a POJO"() {
when:
client.toBlocking().exchange(HttpRequest.GET("/books/1680502395"),
Argument.of(Book), (1)
Argument.of(CustomError)) (2)
then:
def e = thrown(HttpClientResponseException)
e.response.status == HttpStatus.UNAUTHORIZED
when:
Optional<CustomError> jsonError = e.response.getBody(CustomError)
then:
jsonError.isPresent()
jsonError.get().status == 401
jsonError.get().error == 'Unauthorized'
jsonError.get().message == 'No message available'
jsonError.get().path == '/books/1680502395'
}
"after an httpclient exception the response body can be bound to a POJO" {
try {
client.toBlocking().exchange(HttpRequest.GET<Any>("/books/1680502395"),
Argument.of(Book::class.java), (1)
Argument.of(CustomError::class.java)) (2)
} catch (e: HttpClientResponseException) {
e.response.status shouldBe HttpStatus.UNAUTHORIZED
}
}
1 | Success Type |
2 | Error Type |
7.2 Proxying Requests with ProxyHttpClient
A common requirement in Microservice environments is to proxy requests in a Gateway Microservice to other backend Microservices.
The regular HttpClient API is designed around simplifying exchange of messages and is not really designed for proxying requests. For this use case you should use the the ProxyHttpClient which can be used from a HTTP Server Filter to proxy requests to backend Microservices.
The following example demonstrates rewriting requests under the URI /proxy
to the URI /real
onto the same server (clearly in a real environment you would generally proxy onto another server):
import io.micronaut.core.async.publisher.Publishers;
import io.micronaut.core.util.StringUtils;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.MutableHttpResponse;
import io.micronaut.http.annotation.Filter;
import io.micronaut.http.client.ProxyHttpClient;
import io.micronaut.http.filter.*;
import io.micronaut.http.filter.ServerFilterChain;
import io.micronaut.runtime.server.EmbeddedServer;
import org.reactivestreams.Publisher;
@Filter("/proxy/**")
public class ProxyFilter extends OncePerRequestHttpServerFilter { (1)
private final ProxyHttpClient client;
private final EmbeddedServer embeddedServer;
public ProxyFilter(ProxyHttpClient client, EmbeddedServer embeddedServer) { (2)
this.client = client;
this.embeddedServer = embeddedServer;
}
@Override
protected Publisher<MutableHttpResponse<?>> doFilterOnce(HttpRequest<?> request, ServerFilterChain chain) {
return Publishers.map(client.proxy( (3)
request.mutate() (4)
.uri(b -> b (5)
.scheme("http")
.host(embeddedServer.getHost())
.port(embeddedServer.getPort())
.replacePath(StringUtils.prependUri(
"/real",
request.getPath().substring("/proxy".length())
))
)
.header("X-My-Request-Header", "XXX") (6)
), response -> response.header("X-My-Response-Header", "YYY"));
}
}
import io.micronaut.core.async.publisher.Publishers
import io.micronaut.core.util.StringUtils
import io.micronaut.http.HttpRequest
import io.micronaut.http.MutableHttpResponse
import io.micronaut.http.annotation.Filter
import io.micronaut.http.client.ProxyHttpClient
import io.micronaut.http.filter.*
import io.micronaut.http.filter.ServerFilterChain
import io.micronaut.http.uri.UriBuilder
import io.micronaut.runtime.server.EmbeddedServer
import org.reactivestreams.Publisher
@Filter("/proxy/**")
class ProxyFilter extends OncePerRequestHttpServerFilter { (1)
private final ProxyHttpClient client
private final EmbeddedServer embeddedServer
ProxyFilter(ProxyHttpClient client, EmbeddedServer embeddedServer) { (2)
this.client = client
this.embeddedServer = embeddedServer
}
@Override
protected Publisher<MutableHttpResponse<?>> doFilterOnce(HttpRequest<?> request, ServerFilterChain chain) {
return Publishers.map(client.proxy( (3)
request.mutate() (4)
.uri { UriBuilder b -> (5)
b.with {
scheme("http")
host(embeddedServer.getHost())
port(embeddedServer.getPort())
replacePath(StringUtils.prependUri(
"/real",
request.getPath().substring("/proxy".length())
))
}
}
.header("X-My-Request-Header", "XXX") (6)
), { MutableHttpResponse<?> response -> response.header("X-My-Response-Header", "YYY")})
}
}
import io.micronaut.core.async.publisher.Publishers
import io.micronaut.core.util.StringUtils
import io.micronaut.http.*
import io.micronaut.http.annotation.Filter
import io.micronaut.http.client.ProxyHttpClient
import io.micronaut.http.filter.*
import io.micronaut.http.uri.UriBuilder
import io.micronaut.runtime.server.EmbeddedServer
import org.reactivestreams.Publisher
import java.util.function.Function
@Filter("/proxy/**")
class ProxyFilter(
private val client: ProxyHttpClient, (2)
private val embeddedServer: EmbeddedServer) : OncePerRequestHttpServerFilter() { (1)
override fun doFilterOnce(request: HttpRequest<*>, chain: ServerFilterChain): Publisher<MutableHttpResponse<*>> {
return Publishers.map(client.proxy( (3)
request.mutate() (4)
.uri { b: UriBuilder -> (5)
b.apply {
scheme("http")
host(embeddedServer.host)
port(embeddedServer.port)
replacePath(StringUtils.prependUri(
"/real",
request.path.substring("/proxy".length)
))
}
}
.header("X-My-Request-Header", "XXX") (6)
), Function { response: MutableHttpResponse<*> -> response.header("X-My-Response-Header", "YYY") })
}
}
1 | The filter extends OncePerRequestHttpServerFilter |
2 | The ProxyHttpClient is injected into the constructor. |
3 | The proxy method is used to proxy the request |
4 | The request is mutated to modify the URI and include an additional header |
5 | Here the UriBuilder API is used to rewrite the URI |
6 | Additional request and response headers are included |
The ProxyHttpClient API is a low level API that can be used to build a higher level abstraction such as an API Gateway. |
7.3 Declarative HTTP Clients with @Client
Now that you have gathered an understanding of the workings of the lower level HTTP client, it is time to take a look at Micronaut’s support for declarative clients via the Client annotation.
Essentially, the @Client
annotation can be declared on any interface or abstract class and through the use of Introduction Advice the abstract methods will be implemented for you at compile time, greatly simplifying the creation of HTTP clients.
Let’s start with a simple example. Given the following class:
public class Pet {
private String name;
private int age;
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;
}
}
class Pet {
String name
int age
}
class Pet {
var name: String? = null
var age: Int = 0
}
You can define a common interface for saving new Pet
instances:
import io.micronaut.http.annotation.Post;
import io.micronaut.validation.Validated;
import io.reactivex.Single;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
@Validated
public interface PetOperations {
@Post
Single<Pet> save(@NotBlank String name, @Min(1L) int age);
}
import io.micronaut.http.annotation.Post
import io.micronaut.validation.Validated
import io.reactivex.Single
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank
@Validated
interface PetOperations {
@Post
Single<Pet> save(@NotBlank String name, @Min(1L) int age)
}
import io.micronaut.http.annotation.Post
import io.micronaut.validation.Validated
import io.reactivex.Single
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank
@Validated
interface PetOperations {
@Post
fun save(@NotBlank name: String, @Min(1L) age: Int): Single<Pet>
}
Note how the interface uses Micronaut’s HTTP annotations which are usable on both the server and client side. Also, as you can see you can use javax.validation
constraints to validate arguments.
Be aware that some annotations, such as Produces and Consumes, have different semantics between server and client side usage. For example, @Produces on a controller method (server side) indicates how the method’s return value is formatted, while @Produces on a client indicates how the method’s parameters are formatted when sent to the server. While this may seem a little confusing at first, it is actually logical considering the different semantics between a server producing/consuming vs a client: A server consumes an argument and returns a response to the client, whereas a client consumes an argument and sends output to a server.
|
Additionally, to use the javax.validation
features you should have the validation
module on your classpath:
implementation("io.micronaut:micronaut-validator")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-validator</artifactId>
</dependency>
On the server-side of Micronaut you can implement the PetOperations
interface:
import io.micronaut.http.annotation.Controller;
import io.reactivex.Single;
@Controller("/pets")
public class PetController implements PetOperations {
@Override
public Single<Pet> save(String name, int age) {
Pet pet = new Pet();
pet.setName(name);
pet.setAge(age);
// save to database or something
return Single.just(pet);
}
}
import io.micronaut.http.annotation.Controller
import io.reactivex.Single
@Controller("/pets")
class PetController implements PetOperations {
@Override
Single<Pet> save(String name, int age) {
Pet pet = new Pet()
pet.setName(name)
pet.setAge(age)
// save to database or something
return Single.just(pet)
}
}
import io.micronaut.http.annotation.Controller
import io.reactivex.Single
@Controller("/pets")
open class PetController : PetOperations {
override fun save(name: String, age: Int): Single<Pet> {
val pet = Pet()
pet.name = name
pet.age = age
// save to database or something
return Single.just(pet)
}
}
You can then define a declarative client in src/test/java
that uses @Client
to automatically, at compile time, implement a client:
import io.micronaut.http.client.annotation.Client;
import io.reactivex.Single;
@Client("/pets") (1)
public interface PetClient extends PetOperations { (2)
@Override
Single<Pet> save(String name, int age); (3)
}
import io.micronaut.http.client.annotation.Client
import io.reactivex.Single
@Client("/pets") (1)
interface PetClient extends PetOperations { (2)
@Override
Single<Pet> save(String name, int age) (3)
}
import io.micronaut.http.client.annotation.Client
import io.reactivex.Single
@Client("/pets") (1)
interface PetClient : PetOperations { (2)
override fun save(name: String, age: Int): Single<Pet> (3)
}
1 | The Client annotation is used with a value relative to the current server. In this case /pets |
2 | The interface extends from PetOperations |
3 | The save method is overridden. See warning below. |
Notice in the above example we override the save method. This is necessary if you compile without the -parameters option since Java does not retain parameters names in the byte code otherwise. If you compile with -parameters then overriding is not necessary.
|
Once you have defined a client you can simply @Inject
it wherever you may need it.
Recall that the value of @Client
can be:
-
An absolute URI. Example
https://api.twitter.com/1.1
-
A relative URI, in which case the server targeted will be the current server (useful for testing)
-
A service identifier. See the section on Service Discovery for more information on this topic.
In a production deployment you would typically use a service ID and Service Discovery to discover services automatically.
Another important thing to notice regarding the save
method in the example above is that is returns a Single type.
This is a non-blocking reactive type and typically you want your HTTP clients not to block. There are cases where you may want to write an HTTP client that does block (such as in unit test cases), but this are rare.
The following table illustrates common return types usable with @Client:
Type | Description | Example Signature |
---|---|---|
Any type that implements the Publisher interface |
|
|
An HttpResponse and optional response body type |
Single<HttpResponse<String>> hello() |
|
A Publisher implementation that emits a POJO |
|
|
A Java |
|
|
A blocking native type. Such as |
|
|
T |
Any simple POJO type. |
|
Generally, any reactive type that can be converted to the Publisher interface is supported as a return type including (but not limited to) the reactive types defined by RxJava 1.x, RxJava 2.x and Reactor 3.x.
Returning CompletableFuture instances is also supported. Note that returning any other type will result in a blocking request and is not recommended other than for testing.
7.3.1 Customizing Parameter Binding
The previous example presented a trivial example that uses the parameters of a method to represent the body of a POST
request:
@Post
Single<Pet> save(@NotBlank String name, @Min(1L) int age);
The save
method when called will perform an HTTP POST
with the following JSON by default:
{"name":"Dino", "age":10}
You may however want to customize what is sent as the body, the parameters, URI variables and so on. The @Client annotation is very flexible in this regard and supports the same HTTP Annotations as Micronaut’s HTTP server.
For example, the following defines a URI template and the name
parameter is used as part of the URI template, whilst @Body is used declare that the contents to send to the server are represented by the Pet
POJO:
@Post("/{name}")
Single<Pet> save(
@NotBlank String name, (1)
@Body @Valid Pet pet) (2)
1 | The name parameter, included as part of the URI, and declared @NotBlank |
2 | The pet parameter, used to encode the body and declared @Valid |
The following table summarizes the parameter annotations, their purpose, and provides an example:
Annotation | Description | Example |
---|---|---|
Allows to specify the parameter that is the body of the request |
|
|
Allows specifying parameters that should be sent as cookies |
|
|
Allows specifying parameters that should be sent as HTTP headers |
|
|
Allows customizing the name of the URI parameter to bind from |
|
|
Used to bind a parameter exclusively from a Path Variable. |
|
|
Allows specifying parameters that should be set as request attributes |
|
Type Based Binding Parameters
Some parameters are recognized by their type instead of their annotation. The following table summarizes the parameter types, their purpose, and provides an example:
Type | Description | Example |
---|---|---|
Allows binding of basic authorization credentials |
|
7.3.2 Streaming with @Client
The @Client annotation can also handle streaming HTTP responses.
Streaming JSON with @Client
For example to write a client that streams data from the controller defined in the JSON Streaming section of the documentation you can simply define a client that returns an unbound Publisher such as a RxJava Flowable or Reactor Flux
:
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.client.annotation.Client;
import io.reactivex.Flowable;
@Client("/streaming")
public interface HeadlineClient {
@Get(value = "/headlines", processes = MediaType.APPLICATION_JSON_STREAM) (1)
Flowable<Headline> streamHeadlines(); (2)
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import io.reactivex.Flowable
@Client("/streaming")
interface HeadlineClient {
@Get(value = "/headlines", processes = MediaType.APPLICATION_JSON_STREAM) (1)
Flowable<Headline> streamHeadlines() (2)
}
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import io.reactivex.Flowable
@Client("/streaming")
interface HeadlineClient {
@Get(value = "/headlines", processes = [MediaType.APPLICATION_JSON_STREAM]) (1)
fun streamHeadlines(): Flowable<Headline> (2)
1 | The @Get method is defined as processing responses of type APPLICATION_JSON_STREAM |
2 | A Flowable is used as the return type |
The following example shows how the previously defined HeadlineClient
can be invoked from a JUnit test:
@Test
public void testClientAnnotationStreaming() throws Exception {
try( EmbeddedServer embeddedServer = ApplicationContext.run(EmbeddedServer.class) ) {
HeadlineClient headlineClient = embeddedServer
.getApplicationContext()
.getBean(HeadlineClient.class); (1)
Maybe<Headline> firstHeadline = headlineClient.streamHeadlines().firstElement(); (2)
Headline headline = firstHeadline.blockingGet(); (3)
assertNotNull( headline );
assertTrue( headline.getText().startsWith("Latest Headline") );
}
}
void "test client annotation streaming"() throws Exception {
when:
HeadlineClient headlineClient = embeddedServer.getApplicationContext()
.getBean(HeadlineClient.class) (1)
Maybe<Headline> firstHeadline = headlineClient.streamHeadlines().firstElement() (2)
Headline headline = firstHeadline.blockingGet() (3)
then:
null != headline
headline.getText().startsWith("Latest Headline")
}
"test client annotation streaming" {
val headlineClient = embeddedServer
.applicationContext
.getBean(HeadlineClient::class.java) (1)
val firstHeadline = headlineClient.streamHeadlines().firstElement() (2)
val headline = firstHeadline.blockingGet() (3)
headline shouldNotBe null
headline.text shouldStartWith "Latest Headline"
}
1 | The client is retrieved from the ApplicationContext |
2 | The firstElement method is used to return the first emitted item from the Flowable as a Maybe. |
3 | The blockingGet() is used in the test to retrieve the result. |
Streaming Clients and Response Types
The example defined in the previous section expects the server to respond with a stream of JSON objects and the content type to be application/x-json-stream
. For example:
{"title":"The Stand"}
{"title":"The Shining"}
The reason for this is simple, a sequence of JSON object is not, in fact, valid JSON and hence the response content type cannot be application/json
. For the JSON to be valid it would have to return an array:
[
{"title":"The Stand"},
{"title":"The Shining"}
]
Micronaut’s client does however support streaming of both individual JSON objects via application/x-json-stream
and also JSON arrays defined with application/json
.
Streaming Clients and Read Timeout
When streaming responses from servers, the underlying HTTP client will not apply the default readTimeout
setting (which defaults to 10 seconds) of the HttpClientConfiguration since the delay between reads for streaming responses may differ from normal reads.
Instead the read-idle-timeout
setting (which defaults to 60 seconds) is used to dictate when a connection should be closed after becoming idle.
If you are streaming data from a server that defines a longer delay than 60 seconds between items being sent to the client you should adjust the readIdleTimeout
. The following configuration in application.yml
demonstrates how:
micronaut:
http:
client:
read-idle-timeout: 5m
The above example sets the readIdleTimeout
to 5 minutes.
Streaming Server Sent Events
Micronaut features a native client for Server Sent Events (SSE) defined by the interface SseClient.
You can use this client to stream SSE events from any server that emits them.
Although SSE streams are typically consumed by a browser EventSource , there are a few cases where you may wish to consume a SSE stream via SseClient such as in unit testing or when a Micronaut service acts as a gateway for another service.
|
The @Client annotation also supports consuming SSE streams. For example, consider the following controller method that produces a stream of SSE events:
@Get(value = "/headlines", processes = MediaType.TEXT_EVENT_STREAM) (1)
Flowable<Event<Headline>> streamHeadlines() {
return Flowable.<Event<Headline>>create((emitter) -> { (2)
Headline headline = new Headline();
headline.setText("Latest Headline at " + ZonedDateTime.now());
emitter.onNext(Event.of(headline));
emitter.onComplete();
}, BackpressureStrategy.BUFFER).repeat(100) (3)
.delay(1, TimeUnit.SECONDS); (4)
}
@Get(value = "/headlines", processes = MediaType.TEXT_EVENT_STREAM) (1)
Flowable<Event<Headline>> streamHeadlines() {
Flowable.<Event<Headline>>create( { emitter -> (2)
Headline headline = new Headline()
headline.setText("Latest Headline at " + ZonedDateTime.now())
emitter.onNext(Event.of(headline))
emitter.onComplete()
}, BackpressureStrategy.BUFFER).repeat(100) (3)
.delay(1, TimeUnit.SECONDS) (4)
}
@Get(value = "/headlines", processes = [MediaType.TEXT_EVENT_STREAM]) (1)
internal fun streamHeadlines(): Flowable<Event<Headline>> {
return Flowable.create<Event<Headline>>( { (2)
emitter ->
val headline = Headline()
headline.text = "Latest Headline at " + ZonedDateTime.now()
emitter.onNext(Event.of(headline))
emitter.onComplete()
}, BackpressureStrategy.BUFFER).repeat(100) (3)
.delay(1, TimeUnit.SECONDS) (4)
}
1 | The controller defines a @Get annotation that produces a MediaType.TEXT_EVENT_STREAM |
2 | The method itself uses Reactor to emit a hypothetical Headline object |
3 | The repeat method is used to repeat the emission 100 times |
4 | With a delay of 1 second between each item emitted. |
Notice that the return type of the controller is also Event and that the Event.of
method is used to create events to stream to the client.
To define a client that consumes the events you simply have to define a method that processes MediaType.TEXT_EVENT_STREAM
:
@Client("/streaming/sse")
public interface HeadlineClient {
@Get(value = "/headlines", processes = MediaType.TEXT_EVENT_STREAM)
Flowable<Event<Headline>> streamHeadlines();
}
@Client("/streaming/sse")
interface HeadlineClient {
@Get(value = "/headlines", processes = MediaType.TEXT_EVENT_STREAM)
Flowable<Event<Headline>> streamHeadlines()
}
@Client("/streaming/sse")
interface HeadlineClient {
@Get(value = "/headlines", processes = [MediaType.TEXT_EVENT_STREAM])
fun streamHeadlines(): Flowable<Event<Headline>>
}
The generic type of the Flux
or Flowable
can be either an Event, in which case you will receive the full event object, or a POJO, in which case you will receive only the data contained within the event converted from JSON.
7.3.3 Error Responses
If an HTTP response is returned with a code of 400 or above, an HttpClientResponseException is created. The exception contains the original response. How that exception gets thrown depends on the return type of the method.
-
For reactive response types, the exception is passed through the publisher as an error.
-
For blocking response types, the exception is thrown and should be caught and handled by the caller.
The one exception to this rule is HTTP Not Found (404) responses. This exception only applies to the declarative client. |
HTTP Not Found (404) responses for blocking return types is not considered an error condition and the client exception will not be thrown. That behavior includes methods that return void
.
If the method returns an HttpResponse
, the original response will be returned. If the return type is Optional
, an empty optional will be returned. For all other types, null
will be returned.
7.3.4 Customizing Request Headers
Customizing the request headers deserves special mention as there are several ways that can be accomplished.
Populating Headers Using Configuration
The @Header annotation can be declared at the type level and is repeatable such that it is possible to drive the request headers sent via configuration using annotation metadata.
The following example serves to illustrate this:
@Client("/pets")
@Header(name="X-Pet-Client", value="${pet.client.id}")
public interface PetClient extends PetOperations {
@Override
Single<Pet> save(String name, int age);
@Get("/{name}")
Single<Pet> get(String name);
}
@Client("/pets")
@Header(name="X-Pet-Client", value='${pet.client.id}')
interface PetClient extends PetOperations {
@Override
Single<Pet> save(String name, int age)
@Get("/{name}")
Single<Pet> get(String name)
}
@Client("/pets")
@Header(name = "X-Pet-Client", value = "\${pet.client.id}")
interface PetClient : PetOperations {
override fun save(name: String, age: Int): Single<Pet>
@Get("/{name}")
operator fun get(name: String): Single<Pet>
}
The above example defines a @Header annotation on the PetClient
interface that reads a property using property placeholder configuration called pet.client.id
.
In your application configuration you then set the following in application.yml
to populate the value:
pet:
client:
id: foo
Alternatively you can supply a PET_CLIENT_ID
environment variable and the value will be populated.
Populating Headers using an Client Filter
Alternatively if you need the ability to dynamically populate headers an alternative is to use a Client Filter.
For more information on writing client filters see the Client Filters section of the guide.
7.3.5 Customizing Jackson Settings
As mentioned previously, Jackson is used for message encoding to JSON. A default Jackson ObjectMapper
is configured and used by Micronaut HTTP clients.
You can override the settings used to construct the ObjectMapper
using the properties defined by the JacksonConfiguration class in application.yml
.
For example, the following configuration enabled indented output for Jackson:
jackson:
serialization:
indentOutput: true
However, these settings apply globally and impact both how the HTTP server renders JSON and how JSON is sent from the HTTP client. Given that sometimes it useful to provide client specific Jackson settings which can be done with the @JacksonFeatures annotation on any client:
As an example, the following snippet is taken from Micronaut’s native Eureka client (which, of course, is built using Micronaut’s HTTP client):
@Client(id = EurekaClient.SERVICE_ID, path = "/eureka", configuration = EurekaConfiguration.class)
@JacksonFeatures(
enabledSerializationFeatures = WRAP_ROOT_VALUE,
disabledSerializationFeatures = WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED,
enabledDeserializationFeatures = {UNWRAP_ROOT_VALUE, ACCEPT_SINGLE_VALUE_AS_ARRAY}
)
public interface EurekaClient {
...
}
The Eureka serialization format for JSON uses the WRAP_ROOT_VALUE
serialization feature of Jackson, hence it is enabled just for that client.
If the customization offered by JacksonFeatures is not enough, you can also write a BeanCreatedEventListener for the ObjectMapper and add whatever customizations you need.
|
7.3.6 Retry and Circuit Breaker
Being able to recover from failure is critical for HTTP clients, and that is where the integrated Retry Advice included as part of Micronaut comes in really handy.
You can declare the @Retryable or @CircuitBreaker annotations on any @Client interface and the retry policy will be applied, for example:
@Client("/pets")
@Retryable
public interface PetClient extends PetOperations {
@Override
Single<Pet> save(String name, int age);
}
@Client("/pets")
@Retryable
interface PetClient extends PetOperations {
@Override
Single<Pet> save(String name, int age)
}
@Client("/pets")
@Retryable
interface PetClient : PetOperations {
override fun save(name: String, age: Int): Single<Pet>
}
For more information on customizing retry, see the section on Retry Advice.
7.3.7 Client Fallbacks
In distributed systems, failure happens and it is best to be prepared for it and handle it in as graceful a manner possible.
In addition, when developing Microservices it is quite common to work on a single Microservice without other Microservices the project requires being available.
With that in mind Micronaut features a native fallback mechanism that is integrated into Retry Advice that allows falling back to another implementation in the case of failure.
Using the @Fallback annotation you can declare a fallback implementation of a client that will be picked up and used once all possible retries have been exhausted.
In fact the mechanism is not strictly linked to Retry, you can declare any class as @Recoverable and if a method call fails (or, in the case of reactive types, an error is emitted) a class annotated with @Fallback
will be searched for.
To illustrate this consider again the PetOperations
interface declared earlier. You can define a PetFallback
class that will be called in the case of failure:
@Fallback
public class PetFallback implements PetOperations {
@Override
public Single<Pet> save(String name, int age) {
Pet pet = new Pet();
pet.setAge(age);
pet.setName(name);
return Single.just(pet);
}
}
@Fallback
class PetFallback implements PetOperations {
@Override
public Single<Pet> save(String name, int age) {
Pet pet = new Pet()
pet.setAge(age)
pet.setName(name)
return Single.just(pet)
}
}
@Fallback
open class PetFallback : PetOperations {
override fun save(name: String, age: Int): Single<Pet> {
val pet = Pet()
pet.age = age
pet.name = name
return Single.just(pet)
}
}
If you purely want to use fallbacks to help with testing against external Microservices you can define fallbacks in the src/test/java directory so they are not included in production code.
|
As you can see the fallback does not perform any network operations and is quite simple, hence will provide a successful result in the case of an external system being down.
Of course, the actual behaviour of the fallback is down to you. You could for example implement a fallback that pulls data from a local cache when the real data is not available, and sends alert emails to operations about downtime or whatever.
7.3.8 Netflix Hystrix Support
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features netflix-hystrix |
Netflix Hystrix is a fault tolerance library developed by the Netflix team and designed to improve resilience of inter process communication.
Micronaut features integration with Hystrix through the netflix-hystrix
module, which you can add to your build.gradle
or pom.xml
:
implementation("io.micronaut.netflix:micronaut-netflix-hystrix")
<dependency>
<groupId>io.micronaut.netflix</groupId>
<artifactId>micronaut-netflix-hystrix</artifactId>
</dependency>
Using the @HystrixCommand Annotation
With the above dependency declared you can annotate any method (including methods defined on @Client
interfaces) with the @HystrixCommand annotation and it will wrap the methods execution in a Hystrix command. For example:
@HystrixCommand
String hello(String name) {
return "Hello $name"
}
This works for reactive return types such as Flowable etc. as well and the reactive type will be wrapped in a HystrixObservableCommand .
|
The @HystrixCommand annotation also integrates with Micronauts support for Retry Advice and Fallbacks
For information on how to customize the Hystrix thread pool, group and properties see the javadoc for @HystrixCommand. |
Enabling Hystrix Stream & Dashboard
You can enable a Server Sent Event stream to feed into the Hystrix Dashboard by setting the hystrix.stream.enabled
setting to true
in application.yml
:
hystrix:
stream:
enabled: true
This exposes a /hystrix.stream
endpoint with the format the Hystrix Dashboard expects.
7.4 HTTP Client Filters
Often, you need to include the same HTTP headers or URL parameters in a set of requests against a third-party API or when calling another Microservice.
To simplify this, Micronaut includes the ability to define HttpClientFilter classes that are applied to all matching HTTP client requests.
As an example say you want to build a client to communicate with the Bintray REST API. It would be terribly tedious to have to specify authentication for every single HTTP call.
To resolve this burden you can define a filter. The following is an example BintrayService
:
class BintrayApi {
public static final String URL = 'https://api.bintray.com'
}
@Singleton
class BintrayService {
final RxHttpClient client;
final String org;
BintrayService(
@Client(BintrayApi.URL) RxHttpClient client, (1)
@Value("${bintray.organization}") String org ) {
this.client = client;
this.org = org;
}
Flowable<HttpResponse<String>> fetchRepositories() {
return client.exchange(HttpRequest.GET("/repos/" + org), String.class); (2)
}
Flowable<HttpResponse<String>> fetchPackages(String repo) {
return client.exchange(HttpRequest.GET("/repos/" + org + "/" + repo + "/packages"), String.class); (2)
}
}
class BintrayApi {
public static final String URL = 'https://api.bintray.com'
}
@Singleton
class BintrayService {
final RxHttpClient client
final String org
BintrayService(
@Client(BintrayApi.URL) RxHttpClient client, (1)
@Value('${bintray.organization}') String org ) {
this.client = client
this.org = org
}
Flowable<HttpResponse<String>> fetchRepositories() {
return client.exchange(HttpRequest.GET("/repos/$org"), String) (2)
}
Flowable<HttpResponse<String>> fetchPackages(String repo) {
return client.exchange(HttpRequest.GET("/repos/${org}/${repo}/packages"), String) (2)
}
}
class BintrayApi {
public static final String URL = 'https://api.bintray.com'
}
@Singleton
internal class BintrayService(
@param:Client(BintrayApi.URL) val client: RxHttpClient, (1)
@param:Value("\${bintray.organization}") val org: String) {
fun fetchRepositories(): Flowable<HttpResponse<String>> {
return client.exchange(HttpRequest.GET<Any>("/repos/$org"), String::class.java) (2)
}
fun fetchPackages(repo: String): Flowable<HttpResponse<String>> {
return client.exchange(HttpRequest.GET<Any>("/repos/$org/$repo/packages"), String::class.java) (2)
}
}
1 | An RxHttpClient is injected for the Bintray API |
2 | The organization is configurable via configuration |
The Bintray API is secured. To authenticate you need to add an Authorization
header for every request. You could modify fetchRepositories
and fetchPackages
methods to include the necessary HTTP Header for each request. Using a filter is much simpler though:
@Filter("/repos/**") (1)
class BintrayFilter implements HttpClientFilter {
final String username;
final String token;
BintrayFilter(
@Value("${bintray.username}") String username, (2)
@Value("${bintray.token}") String token ) { (2)
this.username = username;
this.token = token;
}
@Override
public Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
return chain.proceed(
request.basicAuth(username, token) (3)
);
}
}
@Filter('/repos/**') (1)
class BintrayFilter implements HttpClientFilter {
final String username
final String token
BintrayFilter(
@Value('${bintray.username}') String username, (2)
@Value('${bintray.token}') String token ) { (2)
this.username = username
this.token = token
}
@Override
Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
return chain.proceed(
request.basicAuth(username, token) (3)
)
}
}
@Filter("/repos/**") (1)
internal class BintrayFilter(
@param:Value("\${bintray.username}") val username: String, (2)
@param:Value("\${bintray.token}") val token: String)(2)
: HttpClientFilter {
override fun doFilter(request: MutableHttpRequest<*>, chain: ClientFilterChain): Publisher<out HttpResponse<*>> {
return chain.proceed(
request.basicAuth(username, token) (3)
)
}
}
1 | You can match only a subset of paths with a Client filter. |
2 | The username and token are injected via configuration |
3 | The basicAuth method is used include the HTTP BASIC credentials |
Now, whenever you invoke the bintrayService.fetchRepositories()
method, the Authorization
HTTP header is included in the request.
Injecting Another Client into a HttpClientFilter
It should be noted that in order to create a RxHttpClient Micronaut needs to resolve all of the HttpClientFilter
instances which creates a circular dependency in the case where you need to inject another RxHttpClient or a @Client
bean into an instance of a HttpClientFilter
.
To resolve this issue you should use the javax.inject.Provider
interface to inject another RxHttpClient or a @Client
bean into an instance of HttpClientFilter
.
The following example which implements a filter that allows authentication between services on Google Cloud Run demonstrates how to use Provider
to inject another client:
import io.micronaut.context.annotation.Requires;
import io.micronaut.context.env.Environment;
import io.micronaut.http.*;
import io.micronaut.http.annotation.Filter;
import io.micronaut.http.client.RxHttpClient;
import io.micronaut.http.filter.ClientFilterChain;
import io.micronaut.http.filter.HttpClientFilter;
import io.reactivex.Flowable;
import org.reactivestreams.Publisher;
import javax.inject.Provider;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.net.URLEncoder;
@Requires(env = Environment.GOOGLE_COMPUTE)
@Filter(patterns = "/google-auth/api/**")
public class GoogleAuthFilter implements HttpClientFilter {
private final Provider<RxHttpClient> authClientProvider;
public GoogleAuthFilter(Provider<RxHttpClient> httpClientProvider) { (1)
this.authClientProvider = httpClientProvider;
}
@Override
public Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
Flowable<String> token = Flowable.fromCallable(() -> encodeURI(request))
.flatMap(authURI -> authClientProvider.get().retrieve(HttpRequest.GET(authURI).header( (2)
"Metadata-Flavor", "Google"
)));
return token.flatMap(t -> chain.proceed(request.bearerAuth(t)));
}
private String encodeURI(MutableHttpRequest<?> request) throws UnsupportedEncodingException {
URI fullURI = request.getUri();
String receivingURI = fullURI.getScheme() + "://" + fullURI.getHost();
return "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=" +
URLEncoder.encode(receivingURI, "UTF-8");
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.context.env.Environment
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.annotation.Filter
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import io.reactivex.Flowable
import org.reactivestreams.Publisher
import javax.inject.Provider
@Requires(env = Environment.GOOGLE_COMPUTE)
@Filter(patterns = "/google-auth/api/**")
class GoogleAuthFilter implements HttpClientFilter {
private final Provider<RxHttpClient> authClientProvider
GoogleAuthFilter(Provider<RxHttpClient> httpClientProvider) { (1)
this.authClientProvider = httpClientProvider
}
@Override
Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
Flowable<String> token = Flowable.fromCallable(() -> encodeURI(request))
.flatMap(authURI -> authClientProvider.get().retrieve(HttpRequest.GET(authURI).header( (2)
"Metadata-Flavor", "Google"
)))
return token.flatMap(t -> chain.proceed(request.bearerAuth(t)))
}
private static String encodeURI(MutableHttpRequest<?> request) {
String receivingURI = "$request.uri.scheme://$request.uri.host"
return "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=" +
URLEncoder.encode(receivingURI, "UTF-8")
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.context.env.Environment
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.annotation.Filter
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import io.reactivex.Flowable
import org.reactivestreams.Publisher
import java.net.URLEncoder
import javax.inject.Provider
@Requires(env = [Environment.GOOGLE_COMPUTE])
@Filter(patterns = ["/google-auth/api/**"])
class GoogleAuthFilter (
private val authClientProvider: Provider<RxHttpClient>) : HttpClientFilter { (1)
override fun doFilter(request: MutableHttpRequest<*>, chain: ClientFilterChain): Publisher<out HttpResponse<*>?> {
val token = Flowable.fromCallable { encodeURI(request) }
.flatMap { authURI: String ->
authClientProvider.get().retrieve(HttpRequest.GET<Any>(authURI).header( (2)
"Metadata-Flavor", "Google"
))
}
return token.flatMap { t -> chain.proceed(request.bearerAuth(t)) }
}
private fun encodeURI(request: MutableHttpRequest<*>): String {
val receivingURI = "${request.uri.scheme}://${request.uri.host}"
return "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=" +
URLEncoder.encode(receivingURI, "UTF-8")
}
}
1 | The javax.inject.Provider interface is used to inject another client, avoiding a circular reference |
2 | The get() method of the Provider interface is used to obtain the client instance. |
Filter Matching By Annotation
For cases where a filter should be applied to a client, regardless of the URL, filters can be matched by the presence of an annotation applied to both the filter and the client. Given the following client:
import io.micronaut.http.annotation.Get;
import io.micronaut.http.client.annotation.Client;
@BasicAuth (1)
@Client("/message")
public interface BasicAuthClient {
@Get
String getMessage();
}
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
@BasicAuth (1)
@Client("/message")
interface BasicAuthClient {
@Get
String getMessage()
}
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
@BasicAuth (1)
@Client("/message")
interface BasicAuthClient {
@Get
fun getMessage(): String
}
1 | The @BasicAuth annotation is applied to the client |
The following filter will filter the client requests:
import io.micronaut.http.HttpResponse;
import io.micronaut.http.MutableHttpRequest;
import io.micronaut.http.filter.ClientFilterChain;
import io.micronaut.http.filter.HttpClientFilter;
import org.reactivestreams.Publisher;
import javax.inject.Singleton;
@BasicAuth (1)
@Singleton (2)
public class BasicAuthClientFilter implements HttpClientFilter {
@Override
public Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
return chain.proceed(request.basicAuth("user", "pass"));
}
}
import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import org.reactivestreams.Publisher
import javax.inject.Singleton
@BasicAuth (1)
@Singleton (2)
class BasicAuthClientFilter implements HttpClientFilter {
@Override
Publisher<? extends HttpResponse<?>> doFilter(MutableHttpRequest<?> request, ClientFilterChain chain) {
chain.proceed(request.basicAuth("user", "pass"))
}
}
import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpRequest
import io.micronaut.http.filter.ClientFilterChain
import io.micronaut.http.filter.HttpClientFilter
import org.reactivestreams.Publisher
import javax.inject.Singleton
@BasicAuth (1)
@Singleton (2)
class BasicAuthClientFilter : HttpClientFilter {
override fun doFilter(request: MutableHttpRequest<*>, chain: ClientFilterChain): Publisher<out HttpResponse<*>> {
return chain.proceed(request.basicAuth("user", "pass"))
}
}
1 | The same annotation, @BasicAuth , is applied to the filter |
2 | Normally the @Filter annotation makes filters singletons by default. Because the @Filter annotation is not used, the desired scope must be applied |
The @BasicAuth
annotation is just an example and can be replaced with your own custom annotation.
import io.micronaut.http.annotation.FilterMatcher;
import java.lang.annotation.*;
@FilterMatcher (1)
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.PARAMETER})
public @interface BasicAuth {
}
import io.micronaut.http.annotation.FilterMatcher
import java.lang.annotation.*
@FilterMatcher (1)
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target([ElementType.TYPE, ElementType.PARAMETER])
@interface BasicAuth {
}
import io.micronaut.http.annotation.FilterMatcher
@FilterMatcher (1)
@MustBeDocumented
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS, AnnotationTarget.VALUE_PARAMETER)
annotation class BasicAuth
1 | The only requirement for custom annotations is that the @HttpFilterStereotype annotation must be present |
7.5 HTTP Client Sample
8 Cloud Native Features
The majority of frameworks in use today on the JVM were designed before the rise of cloud deployments and microservice architectures. Applications built with these frameworks were intended to be deployed to traditional Java containers. As a result, cloud support in these frameworks typically comes as an add-on rather than as core design features.
Micronaut was designed from the ground up for building microservices for the cloud. As a result, many key features that typically require external libraries or services are available within your application itself. To override one of the industry’s current favorite buzzwords, Micronaut applications are "natively cloud-native".
The following are some of the cloud-specific features that are integrated directly into the Micronaut runtime:
-
Distributed Configuration
-
Service Discovery
-
Client-Side Load-Balancing
-
Distributed Tracing
-
Serverless Functions
Many of the features in Micronaut and heavily inspired by features from Spring and Grails. This is by design and helps developers who are already familiar with systems such as Spring Cloud.
The following sections cover these features and how to use them.
8.1 Cloud Configuration
Applications that are built for the Cloud often need adapt to running in a Cloud environment, read and share configuration in a distributed manner and externalize configuration to the environment where necessary.
Micronaut’s Environment concept is by default Cloud platform aware and will make a best effort to detect the underlying active environment.
You can then use the Requires annotation to conditionally load bean definitions.
The following table summarizes the constants provided by the Environment interface and provides an example:
Constant | Description | Requires Example | Environment name |
---|---|---|---|
The application is running as an Android application |
|
|
|
The application is running within a JUnit or Spock test |
|
|
|
The application is running in a Cloud environment (present for all other cloud platform types) |
|
|
|
Running on Amazon EC2 |
|
|
|
Running on Google Compute |
|
|
|
Running on Kubernetes |
|
|
|
Running on Heroku |
|
|
|
Running on Cloud Foundry |
|
|
|
Running on Microsoft Azure |
|
|
|
Running on IBM Cloud |
|
|
|
Running on Digital Ocean |
|
|
|
Running on Oracle Cloud |
|
|
Note that it may be the case that you have multiple active environment names since you may run Kubernetes on AWS for example.
In addition, using the value of the constants defined in the table above you can create environment specific configuration files. For example if you create a src/main/resources/application-gcp.yml
file then that configuration will only be loaded when running on Google Compute.
Any configuration property in the Environment can also be set via an environment variable. For example, setting the CONSUL_CLIENT_HOST environment variable will override the host property in ConsulConfiguration.
|
Using Cloud Instance Metadata
When Micronaut detects it is running on any of the cloud platforms listed above, such as Google Compute or AWS EC2, upon startup Micronaut will populate the interface ComputeInstanceMetadata.
Depending on the environment you are running in the backing implementation will be either GoogleComputeInstanceMetadata, AmazonEC2InstanceMetadata, DigitalOceanInstanceMetadata or OracleCloudInstanceMetadata with metadata found from the cloud provider metadata services. |
All of this data is merged together into the metadata
property for the running ServiceInstance.
If you need to access the metadata for your application instance you can use the interface EmbeddedServerInstance, and call getMetadata()
which will get a map of all of the metadata.
If you are connecting remotely via client, the instance metadata can be referenced once you have retrieved a ServiceInstance from either the LoadBalancer or DiscoveryClient APIs.
The Netflix Ribbon client side load balancer can be configured to use the metadata to do zone aware client side load balancing. See Client Side Load Balancing |
To obtain metadata for a service via Service Discovery use the LoadBalancerResolver interface to resolve a LoadBalancer and obtain a reference to a service by identifier:
LoadBalancer loadBalancer = loadBalancerResolver.resolve("some-service");
Flowable.fromPublisher(
loadBalancer.select()
).subscribe((instance) ->
ConvertibleValues<String> metaData = instance.getMetadata();
...
);
The EmbeddedServerInstance is available through event listeners that listen for the ServiceReadyEvent. The @EventListener annotation makes it easy to listen for the event inside one of your existing beans.
To obtain metadata for the locally running server use an EventListener for the ServiceReadyEvent:
@EventListener
void onServiceStarted(ServiceReadyEvent event) {
ServiceInstance serviceInstance = event.getSource()
ConvertibleValues<String> metadata = serviceInstance.metadata
}
8.1.1 Distributed Configuration
As you can see, Micronaut features a robust system for externalizing and adapting configuration to the environment inspired by similar approaches found in Grails and Spring Boot.
However, what if you want two Microservices to share configuration? Micronaut comes with built in APIs for doing distributed configuration.
The ConfigurationClient interface has a single method called getPropertySources
that can be implemented to read and resolve configuration from distributed sources.
The getPropertySources
returns a Publisher that emits zero or many PropertySource instances.
The default implementation is DefaultCompositeConfigurationClient which merges all registered ConfigurationClient
beans into a single bean.
You can either implement your own ConfigurationClient implementation or you can use one of the ones already built into Micronaut. The following sections cover those.
8.1.2 HashiCorp Consul Support
Consul is a popular Service Discovery and Distributed Configuration server provided by HashiCorp. Micronaut features a native ConsulClient that is built using Micronaut’s support for Declarative HTTP Clients.
Starting Consul
The quickest way to start using Consul is via Docker:
-
Starting Consul with Docker
docker run -p 8500:8500 consul
Alternatively you can install and run a local Consul instance.
Enabling Distributed Configuration with Consul
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features config-consul |
To enable distributed configuration, similar to Spring Boot and Grails, you need to create a src/main/resources/bootstrap.yml
configuration file and configure Consul as well as enable the configuration client:
micronaut:
application:
name: hello-world
config-client:
enabled: true
consul:
client:
defaultZone: "${CONSUL_HOST:localhost}:${CONSUL_PORT:8500}"
Once you have enabled distributed configuration you need to store the configuration you wish to share in Consul’s Key/Value store.
There are a number of different ways to do that.
Storing Configuration as Key/Value Pairs
One way is to store each key and value directly in Consul. In this case by default Micronaut will look for configuration in the /config
folder of Consul.
You can alter the path searched for by setting consul.client.config.path
|
Within the /config
folder Micronaut will search values within the following folders in order of precedence:
Folder | Description |
---|---|
|
Configuration shared by all applications |
|
Configuration shared by all applications for the |
|
Application specific configuration, example |
|
Application specific configuration for an active Environment |
The value of APPLICATION_NAME
is whatever your have configured micronaut.application.name
to be in bootstrap.yml
.
To see this in action use the following curl command to store a property called foo.bar
with a value of myvalue
in the folder /config/application
.
curl -X PUT -d @- localhost:8500/v1/kv/config/application/foo.bar <<< myvalue
If you now define a @Value("${foo.bar}")
or call environment.getProperty(..)
the value myvalue
will be resolved from Consul.
Storing Configuration in YAML, JSON etc.
Some Consul users prefer storing configuration in blobs of a certain format, such as YAML. Micronaut supports this mode and supports storing configuration in either YAML, JSON or Java properties format.
The ConfigDiscoveryConfiguration has a number of configuration options for configuring how distributed configuration is discovered. |
You can set the consul.client.config.format
option to configure the format with which properties are read.
For example, to configure JSON:
consul:
client:
config:
format: JSON
Now write your configuration in JSON format to Consul:
curl -X PUT localhost:8500/v1/kv/config/application \
-d @- << EOF
{ "foo": { "bar": "myvalue" } }
EOF
Storing Configuration as File References
Another popular option is git2consul which mirrors the contents of a Git repository to Consul’s Key/Value store.
You can setup a Git repository that contains files like application.yml
, hello-world-test.json
etc. and the contents of these files are cloned to Consul.
In this case each key in consul represents a file with an extension. For example /config/application.yml
and you must configure the FILE
format:
consul:
client:
config:
format: FILE
8.1.3 HashiCorp Vault Support
Micronaut features support for integration with HashiCorp Vault as a distributed configuration source.
To enable support for Vault Configuration simply add the following configuration to your bootstrap.yml
file:
micronaut:
application:
name: hello-world
config-client:
enabled: true
vault:
client:
config:
enabled: true
See the configuration reference for all configuration options.
Micronaut will use the configured micronaut.application.name
to lookup property sources for the application from Vault.
Folder | Description |
---|---|
|
Configuration shared by all applications |
|
Application specific configuration |
|
Configuration shared by all applications for an active environment name |
|
Application specific configuration for an active environment name |
See the Documentation for HashiCorp Vault for more information on how to setup the server.
8.1.4 Spring Cloud Config Support
Since 1.1, Micronaut features a native Spring Cloud Configuration for those who have not switched to a dedicated more complete solution like Consul.
To enable support for Spring Cloud Configuration simply add the following configuration to your bootstrap.yml
file:
micronaut:
application:
name: hello-world
config-client:
enabled: true
spring:
cloud:
config:
enabled: true
uri: http://localhost:8888/
retry-attempts: 4 # optional, number of times to retry
retry-delay: 2s # optional, delay between retries
Micronaut will use the configured micronaut.application.name
to lookup property sources for the application from Spring Cloud config server configured via spring.cloud.config.uri
.
See the Documentation for Spring Cloud Config Server for more information on how to setup the server.
8.1.5 AWS Parameter Store Support
Micronaut supports configuration sharing via AWS System Manager Parameter Store. You will need the following dependencies configured:
implementation("io.micronaut.aws:micronaut-aws-parameter-store")
<dependency>
<groupId>io.micronaut.aws</groupId>
<artifactId>micronaut-aws-parameter-store</artifactId>
</dependency>
To enable distributed configuration a src/main/resources/bootstrap.yml
configuration file must be created and configured to use Parameter Store:
micronaut:
application:
name: hello-world
config-client:
enabled: true
See the configuration reference for all configuration options.
You can configure shared properties by going into the AWS Console → System Manager → Parameter Store
Micronaut will use a hierarchy to read the configuration values, and supports String
, StringList
, and SecureString
types.
You can make environment specific configurations as well by including the environment name after an underscore _
. For example if your micronaut.application.name
setting is set to helloworld
then providing configuration values under helloworld_test
will be applied only to the test
environment.
Folder | Description |
---|---|
|
Configuration shared by all applications |
|
Application specific configuration, example |
|
Configuration shared by all applications for the |
|
Application specific configuration for an active Environment |
For example, if the configuration name /config/application_test/server.url
is configured in AWS Parameter Store, then any application connecting to that parameter store can retrieve the value using server.url
. If the application has micronaut.application.name
configured to be myapp
, then a value with the name /config/myapp_test/server.url
will override the value just for that application.
Each level of the tree can be composed of key=value pairs. If you want multiple key value pairs, set the type to 'StringList'.
For special secure information, like keys or passwords, use the type "SecureString". KMS will be automatically invoked when you add and retrieve values and decrypt them with the default key store for your account. If you set the configuration to not use secure strings, they will be returned to you encrypted and you must manually decrypt them.
The https://github.com/micronaut-projects/micronaut-examples/aws repository showcases a sample application using this feature.
8.1.6 Oracle Cloud Vault Support
Micronaut supports loading configuration values stored in Oracle Cloud Vaults. To use this feature, add the following dependencies:
build.gradle
for Oracle Cloud Vaultcompile "io.micronaut:micronaut-discovery-client"
compile group: 'com.oracle.oci.sdk', name: 'oci-java-sdk-vault', version: '1.15.4'
compile group: 'com.oracle.oci.sdk', name: 'oci-java-sdk-secrets', version: '1.15.4'
compile group: 'com.oracle.oci.sdk', name: 'oci-java-sdk-common', version: '1.15.4'
To enable distributed configuration a src/main/resources/bootstrap.yml
configuration file must be created and configured to use one or more Oracle Cloud Vaults:
micronaut:
application:
name: vault-test
config-client:
enabled: true
oraclecloud:
vault:
config:
enabled: true
vaults:
- ocid: ocid1.vault.oc1.phx...
compartment-ocid: ocid1.compartment.oc1...
use-instance-principal: false
path-to-config: ~/.oci/config
profile: DEFAULT
region: US-PHOENIX-1
See the configuration reference for all configuration options.
You can learn more about Oracle Cloud Vault Secrets by reading this blog post. |
Each configured vault will be read and all of the secrets within the vault will be retrieved and set into configuration variables with the exact same name as the secret in the Oracle Cloud Vault.
For example, if you create a secret with the name of SECRET_ONE
in your Oracle Cloud Vault, then it will be available to use in your application like any standard configuration variable:
@Value("${SECRET_ONE}") String secretOne
You can also use @PropertyName
:
@Property(name = "SECRET_ONE") String secretOne
Another option is to inject your variables in to your configuration files which gives you the ability to store things like database passwords and API keys in your vault:
datasources:
default:
password: ${DB_PASSWORD}
Vault retrieved values are always String
, but you can use @ConfigurationProperties
on a bean in conjunction with your application.yml
file to provide properly typed configuration variables.
So if you where to create secrets in your Oracle Cloud Vault like so:
Name | Value |
---|---|
SECRET_ONE |
Value One |
SECRET_TWO |
value two |
SECRET_THREE |
true |
SECRET_FOUR |
42 |
SECRET_FIVE |
3.16 |
And then added the following to your application.yml
file:
secrets:
one: ${SECRET_ONE}
two: ${SECRET_TWO}
three: ${SECRET_THREE}
four: ${SECRET_FOUR}
five: ${SECRET_FIVE}
You could add a config bean like so:
@ConfigurationProperties("secrets")
public class Config {
private String one;
private String two;
private boolean three;
private int four;
private Double five;
/* getters/setters removed for brevity */
}
You could then inject and use this bean in your application with properly typed values.
@Controller("/hello")
public class HelloController {
private Config config;
public HelloController(
Config config
) {
this.config = config;
}
@Get("/")
public HttpStatus index() {
return HttpStatus.OK;
}
@Get("/secret")
public HttpResponse getSecret() {
return HttpResponse.ok(config);
}
}
Calling the /hello/secret
endpoint would return:
{
"one": "Value One",
"two": "value two",
"three": true,
"four": 42,
"five": 3.16
}
If you need support for different configurations per environment, you can create an environment specific bootstrap.yml file and utilize a different vault(s) configuration per environment.
|
8.2 Service Discovery
Service Discovery enables the ability for Microservices to find each other without necessarily knowing the physical location or IP address of associated services.
Micronaut provides integration with different tools and libraries. Check Micronaut Service Discovery documentation for more details.
8.2.1 Consul Support
8.2.2 Eureka Support
8.2.3 Kubernetes Support
Kubernetes is a container runtime which has a whole bunch of features including integrated Service Discovery and Distributed Configuration.
Micronaut have a first-class integration with Kubernetes. Check the Micronaut Kubernetes documentation for more details.
8.2.4 AWS Route 53 Support
To use the Route 53 Service Discovery, you must meet the following criteria:
-
Run EC2 instances of some type
-
Have a domain name hosted in Route 53
-
Have a newer version of AWS-CLI (such as 14+)
Assuming you have those things, you are ready. It is not as fancy as Consul or Eureka, but other than some initial setup with the AWS-CLI, there is no other software running to go wrong. You can even support health checks if you add a custom health check to your service. If you would like to test if your account can create and use Service Discovery see the Integration Test section. More information can be found at https://docs.aws.amazon.com/Route53/latest/APIReference/overview-service-discovery.html.
Here are the steps:
-
Use AWS-CLI to create a namespace. You can make either a public or private one depending on what IPs or subnets you are using
-
Create a service with DNS Records with AWS-CLI command
-
Add health checks or custom health checks (optional)
-
Add Service ID to your application configuration file like so:
aws:
route53:
registration
enabled: true
aws-service-id: srv-978fs98fsdf
namespace: micronaut.io
micronaut:
application:
name: something
-
Make sure you have the following dependencies included in your build file:
implementation("io.micronaut.aws:micronaut-aws-route53")
<dependency>
<groupId>io.micronaut.aws</groupId>
<artifactId>micronaut-aws-route53</artifactId>
</dependency>
-
On the client side, you will need the same dependencies and less configuration options:
aws:
route53:
discovery:
client:
enabled: true
aws-service-id: srv-978fs98fsdf
namespace-id: micronaut.io
You can then use the DiscoveryClient API to find other services registered via Route 53. For example:
DiscoveryClient discoveryClient = embeddedServer.applicationContext.getBean(DiscoveryClient);
List<String> serviceIds = Flowable.fromPublisher(discoveryClient.getServiceIds()).blockingFirst();
List<ServiceInstance> instances = Flowable.fromPublisher(discoveryClient.getInstances(serviceIds.get(0))).blockingFirst();
Creating the Namespace
Namespaces are similar to a regular Route53 hosted zone, and they appear in the Route53 console but the console doesn’t support modifying them. You must use the AWS-CLI at this time for any Service Discovery functionality.
First decide if you are creating a public facing namespace or a private one, as the commands are different:
$ aws servicediscovery create-public-dns-namespace --name micronaut.io --create-request-id create-1522767790 --description adescrptionhere
or
$ aws servicediscovery create-private-dns-namespace --name micronaut.internal.io --create-request-id create-1522767790 --description adescrptionhere --vpc yourvpcID
When you run this you will get an operation ID. You can check the status with the get-operation
CLI command:
$ aws servicediscovery get-operation --operation-id asdffasdfsda
You can use this command to get the status of any call you make that returns an operation id.
The result of the command will tell you the ID of the namespace. Write that down, you’ll need it for the next steps. If you get an error it will say what the error was.
Creating the Service & DNS Records
The next step is creating the Service and DNS records.
$ aws create-service --name yourservicename --create-request-id somenumber --description someservicedescrption --dns-config NamespaceId=yournamespaceid,RoutingPolicy=WEIGHTED,DnsRecords=[{Type=A,TTL=1000},{Type=A,TTL=1000}]
The DnsRecord
type can be A
(ipv4),AAAA
(ipv6),SRV
, or CNAME
. RoutingPolicy
can be WEIGHTED
or MULTIVALUE
. Keep in mind CNAME
must use weighted routing type, SRV
must have a valid port configured.
If you want to add a health check, you can use the following syntax on the CLI:
Type=string,ResourcePath=string,FailureThreshold=integer
Type can be 'HTTP','HTTPS', or 'TCP'. You can only use a standard health check on a public namespace. See Custom Health Checks for private namespaces. Resource path should be a url that returns 200 OK if it’s healthy.
For a custom health check, you only need to specify --health-check-custom-config FailureThreshold=integer
which will work on private namespaces as well.
This is also good because Micronaut will send out pulsation commands to let AWS know the instance is still healthy.
For more help run 'aws discoveryservice create-service help'.
You will get a service ID and an ARN back from this command if successful. Write that down, it’s going to go into the Micronaut configuration.
Setting up the configuration in Micronaut
Auto Naming Registration
You will need to add the configuration to make your applications register with Route 53 Auto-discovery:
aws:
route53:
registration:
enabled: true
aws-service-id=<enter the service id you got after creation on aws cli>
discovery:
namespace-id=<enter the namespace id you got after creating the namespace>
Discovery Client Configuration
aws:
route53:
discovery:
client
enabled: true
aws-service-id: <enter the service id you got after creation on aws cli>
You can also call the following methods by getting the bean "Route53AutoNamingClient":
// if serviceId is null it will use property "aws.route53.discovery.client.awsServiceId"
Publisher<List<ServiceInstance>> getInstances(String serviceId)
// reads property "aws.route53.discovery.namespaceId"
Publisher<List<String>> getServiceIds()
Integration Tests
If you set the environment variable AWS_SUBNET_ID and have credentials configured in your home directory that are valid (in ~/.aws/credentials
)
you can run the integration tests. You will still need a domain hosted on route53 as well. This test will create a t2.nano instance, a namespace, service, and register that instance to service discovery.
When the test completes it will remove/terminate all resources it spun up.
8.2.5 Manual Service Discovery Configuration
If you do not wish to involve a service discovery server like Consul or you are interacting with a third-party service that cannot register with Consul you can instead manually configure services that are available via Service discovery.
To do this you should use the micronaut.http.services
setting. The following is an example configuration:
micronaut:
http:
services:
foo:
urls:
- http://foo1
- http://foo2
You can then inject a client with @Client("foo")
and it will use the above configuration to load balance between the two configured servers.
You can override this configuration in production by specifying an environment variable such as MICRONAUT_HTTP_SERVICES_FOO_URLS=http://prod1,http://prod2
|
Note that by default no health checking will happen to assert that the referenced services are operational. You can alter that by enabling health checking and optionally specifying a health check path (the default is /health
):
micronaut:
http:
services:
foo:
...
health-check: true (1)
health-check-interval: 15s (2)
health-check-uri: /health (3)
1 | Whether to health check the service |
2 | The interval to wait between checks |
3 | The URI to send the health check request to |
Micronaut will start a background thread to check the health status of the service and if any of the configured services respond with an error code, they will be removed from the list of available services.
8.3 Client Side Load Balancing
When discovering services from Consul, Eureka or other Service Discovery servers the DiscoveryClient will emit a list of available ServiceInstance.
Micronaut by default will automatically perform Round Robin client-side load balancing using the servers in this list. This combined with Retry Advice adds extra resiliency to your Microservice infrastructure.
The load balancing itself is handled by the LoadBalancer interface which defines a LoadBalancer.select() method that returns a Publisher
that emits a ServiceInstance.
The Publisher is returned because the process for selecting a ServiceInstance may result in a network operation depending on the Service Discovery strategy employed.
The default implementation of the LoadBalancer interface is DiscoveryClientRoundRobinLoadBalancer. You can replace this strategy for another implementation if you wish to customize how client side load balancing is handled in Micronaut since there are many different ways you may wish to optimize load balancing.
For example, you may wish to load balance between services in a particular zone or you may wish to load balance between servers that have the best overall response time.
To replace the LoadBalancer used you should define a bean that replaces the DiscoveryClientLoadBalancerFactory.
In fact that is exactly what the Netflix Ribbon support does, described in the next section.
8.3.1 Netflix Ribbon Support
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features netflix-ribbon |
Netflix Ribbon is a inter-process communication library used at Netflix that has support for customizable load balancing strategies.
If you need more flexibility in how your application performs client-side load balancing then you may wish use Micronaut’s Netflix Ribbon support.
To add Ribbon support to your application add the netflix-ribbon
configuration to build.gradle
or pom.xml
:
compile "io.micronaut.netflix:micronaut-netflix-ribbon"
The LoadBalancer implementations will now be RibbonLoadBalancer instances.
Ribbon’s Configuration options can be set using the ribbon
namespace in configuration. For example in application.yml
:
ribbon:
VipAddress: test
ServerListRefreshInterval: 2000
Each discovered client can also be configured under ribbon.clients
. For example given a @Client(id = "hello-world")
you can configure Ribbon settings with:
ribbon:
clients:
hello-world:
VipAddress: test
ServerListRefreshInterval: 2000
By default Micronaut registers a DiscoveryClientServerList for each client that integrates Ribbon with Micronaut’s DiscoveryClient.
8.4 Distributed Tracing
When operating Microservices in production it can be challenging to troubleshoot interactions between Microservices in a distributed architecture.
To solve this problem a way to visualize interactions between Microservices in a distributed manner can be critical. Currently, there are various distributed tracing solutions, the most popular of which are Zipkin and Jaeger both of which provide different levels of support for the Open Tracing API.
Micronaut features integration with both Zipkin and Jaeger (via the Open Tracing API).
To enable tracing you should add the tracing
module to your build.gradle
or pom.xml
file:
implementation("io.micronaut:micronaut-tracing")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-tracing</artifactId>
</dependency>
Tracing Annotations
The io.micronaut.tracing.annotation package contains annotations that can be declared on methods to create new spans or continue existing spans.
The available annotations are:
-
The @NewSpan annotation will create a new span, wrapping the method call or reactive type.
-
The @ContinueSpan annotation will continue an existing span, wrapping the method call or reactive type.
-
The @SpanTag annotation can be used on method arguments to include the value of each argument within a Span’s tags. When you use
@SpanTag
on a method argument, you need either to annotate the method with@NewSpan
or@ContinueSpan
.
The following snippet presents an example of using the annotations:
@Singleton
class HelloService {
@NewSpan("hello-world") (1)
public String hello(@SpanTag("person.name") String name) { (2)
return greet("Hello " + name);
}
@ContinueSpan (3)
public String greet(@SpanTag("hello.greeting") String greet) {
return greet;
}
}
1 | The @NewSpan annotation is used to start a new span |
2 | You can use @SpanTag to include arguments of methods as tags for the span |
3 | The @ContinueSpan annotation can be used to continue as existing span and incorporate additional tags using @SpanTag |
Tracing Instrumentation
In addition to explicit tracing tags, Micronaut includes a number of instrumentations to ensure that the Span context is propagated between threads and across Microservice boundaries.
These instrumentations are found in the io.micronaut.tracing.instrument package and include HTTP Client Filters and Server Filters to propagate the necessary headers via HTTP.
Tracing Beans
If the Tracing annotations and existing instrumentations are not enough, Micronaut’s tracing integration registers a io.opentracing.Tracer
bean that can be injected into any class and exposes the Open Tracing API.
Depending on the implementation you choose there are also additional beans. For example for Zipkin brave.Tracing
and brave.SpanCustomizer
beans are available too.
8.4.1 Tracing with Zipkin
Zipkin is a distributed tracing system. It helps gather timing data needed to troubleshoot latency problems in microservice architectures. It manages both the collection and lookup of this data.
Running Zipkin
The quickest way to get up and started with Zipkin is with Docker:
$ docker run -d -p 9411:9411 openzipkin/zipkin
You can then open a browser tab to the location http://localhost:9411
to view traces.
Sending Traces to Zipkin
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features tracing-zipkin |
To send tracing spans to Zipkin the minimal configuration requires you add the following dependencies to build.gradle
or pom.xml
:
runtime 'io.zipkin.brave:brave-instrumentation-http'
runtime 'io.zipkin.reporter2:zipkin-reporter'
compile 'io.opentracing.brave:brave-opentracing'
Then you need to enable ZipKin tracing in your configuration (potentially only your production configuration):
tracing:
zipkin:
enabled: true
Or alternatively if you have the Micronaut CLI installed you can configure Zipkin when creating your service with: mn create-app hello-world --features tracing-zipkin
|
Customizing the Zipkin Sender
In order to send spans you need to configure a Zipkin sender. You can configure a HttpClientSender that sends Spans asynchronously using Micronaut’s native HTTP client using the tracing.zipkin.http.url
setting:
tracing:
zipkin:
enabled: true
http:
url: http://localhost:9411
It is unlikely that sending spans to localhost will be suitable for production deployment so you generally will want to configure the location of one or many Zipkin servers for production:
tracing:
zipkin:
enabled: true
http:
urls:
- http://foo:9411
- http://bar:9411
In production, setting TRACING_ZIPKIN_HTTP_URLS environment variable with a comma separated list of URLs will also work.
|
Alternatively if you wish to use a different zipkin2.reporter.Sender
implementation, you can simply define a bean that is of type zipkin2.reporter.Sender
and it will be picked up.
Zipkin Configuration
There are many configuration options available for the Brave client that sends Spans to Zipkin and they are generally exposed via the BraveTracerConfiguration class. You can refer to the javadoc for all the available options.
Below is an example of customizing Zipkin configuration:
tracing:
zipkin:
enabled: true
traceId128Bit: true
sampler:
probability: 1
You can also optionally dependency inject common configuration classes into BraveTracerConfiguration such as brave.sampler.Sampler
just by defining them as beans. See the API for BraveTracerConfiguration for available injection points.
8.4.2 Tracing with Jaeger
Jaeger is another distributed tracing system developed at Uber that is more or less the reference implementation for Open Tracing.
Running Jaeger
The easiest way to get started with Jaeger is to run Jaeger via Docker:
$ docker run -d \
-e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-p 5775:5775/udp \
-p 6831:6831/udp \
-p 6832:6832/udp \
-p 5778:5778 \
-p 16686:16686 \
-p 14268:14268 \
-p 9411:9411 \
jaegertracing/all-in-one:1.6
You can then navigate to http://localhost:16686
to access the Jaeger UI.
See Getting Started with Jaeger for more information.
Sending Traces to Jaeger
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features tracing-jaeger |
To send tracing spans to Jaeger the minimal configuration requires you add the following dependencies to build.gradle
or pom.xml
:
compile 'io.jaegertracing:jaeger-thrift:0.31.0'
Then you need to enable Jaeger tracing in your configuration (potentially only your production configuration):
tracing:
jaeger:
enabled: true
By default Jaeger will be configured to send traces to a locally running Jaeger agent.
Or alternatively if you have the Micronaut CLI installed you can configure Jaeger when creating your service with: mn create-app hello-world --features tracing-jaeger
|
Jaeger Configuration
There are many configuration options available for the Jaeger client that sends Spans to Jaeger and they are generally exposed via the JaegerConfiguration class. You can refer to the javadoc for all the available options.
Below is an example of customizing JaegerConfiguration configuration:
tracing:
jaeger:
enabled: true
sampler:
probability: 0.5
sender:
agentHost: foo
agentPort: 5775
reporter:
flushInterval: 2000
maxQueueSize: 200
You can also optionally dependency inject common configuration classes into JaegerConfiguration such as io.jaegertracing.Configuration.SamplerConfiguration
just by defining them as beans. See the API for JaegerConfiguration for available injection points.
9 Serverless Functions
Server-less architectures where as a developer you deploy functions that are fully managed by the Cloud environment and are executed in ephemeral processes require a unique approach.
Traditional frameworks like Grails and Spring are not really suitable since low memory consumption and fast startup time are critical, since the Function as a Service (FaaS) server will typically spin up your function for a period using a cold start and then keep it warm.
Micronaut’s compile-time approach, fast startup time and low-memory footprint make it a great candidate for using as a framework for developing functions and in fact Micronaut features dedicated support for developing and deploying functions to AWS Lambda, Google Cloud Function, Azure Function and any FaaS system that supports running functions as containers (such as OpenFaaS, Rift or Fn).
There are generally 2 approaches to writing functions with Micronaut:
-
Low-level functions that are written using the native API of the function platform
-
Higher-level functions where you simply define controllers as you would normally do in a typical Micronaut application and deploy to the function platform.
The first approach has marginally less startup time overhead and is typically used for non-HTTP functions such as functions that listen to an event or background functions.
The second approach is only for HTTP functions and is useful for users who want to take a slice of an existing application and deploy it as a serverless function. If cold start performance is a concern it is recommended that you consider building a native image with GraalVM for this option.
9.1 AWS Lambda
Support for AWS Lambda is implemented in the Micronaut AWS subproject.
Simple Functions with AWS Lambda
You can implement AWS Request Handlers with Micronaut that implement directly the AWS Lambda SDK API. See the documentation on Micronaut Request Handlers for more information.
Using the CLI
To create an AWS Lambda Function: $ mn create-function-app my-app --features aws-lambda Or with Micronaut Launch $ curl https://launch.micronaut.io/create/function/example\?features\=aws-lambda -o example.zip $ unzip example.zip -d example |
HTTP Functions with AWS Lambda
You can deploy regular Micronaut applications that use @Controller etc. using Micronaut’s support for AWS API Gateway. See the documentation on AWS API Gateway Support for more information.
Using the CLI
To create an AWS API Gateway Proxy application: $ mn create-app my-app --features aws-lambda Or with Micronaut Launch $ curl https://launch.micronaut.io/example.zip\?features\=aws-lambda -o example.zip $ unzip example.zip -d example |
9.2 Google Cloud Function
Support for Google Cloud Function is implemented in the Micronaut GCP subproject.
Simple Functions with Cloud Function
You can implement Cloud Functions with Micronaut that implement directly the Cloud Function Framework API. See the documentation on Simple Functions for more information.
Using the CLI
To create a Google Cloud Function: $ mn create-function-app my-app --features google-cloud-function Or with Micronaut Launch $ curl https://launch.micronaut.io/create/function/example\?features\=google-cloud-function -o example.zip $ unzip example.zip -d example |
HTTP Functions with Cloud Function
You can deploy regular Micronaut applications that use @Controller etc. using Micronaut’s support for HTTP Functions. See the documentation on Google Cloud HTTP Functions for more information.
Using the CLI
To create a Google Cloud HTTP Function: $ mn create-app my-app --features google-cloud-function Or with Micronaut Launch $ curl https://launch.micronaut.io/example.zip\?features\=google-cloud-function -o example.zip $ unzip example.zip -d example |
9.3 Google Cloud Run
To deploy to Google Cloud Run we recommend using JIB to containerize your application.
Using the CLI
Creating an application with JIB: $ mn create-app my-app --features jib Or with Micronaut Launch $ curl https://launch.micronaut.io/example.zip\?features\=jib -o example.zip $ unzip example.zip -d example |
With JIB setup to deploy your application to Google Container Registry you can simple run:
$ ./gradlew jib
You are now ready to deploy your application :
$ gcloud run deploy --image gcr.io/[PROJECT ID]/example --platform=managed --allow-unauthenticated
Where [PROJECT ID]
is replaced for your project ID. You should be asked to specify a region and see output like the following:
Service name: (example):
Deploying container to Cloud Run service [example] in project [PROJECT_ID] region [us-central1]
✓ Deploying... Done.
✓ Creating Revision...
✓ Routing traffic...
✓ Setting IAM Policy...
Done.
Service [example] revision [example-00004] has been deployed and is serving 100 percent of traffic at https://example-9487r97234-uc.a.run.app
The URL is the URL of your Cloud Run application.
9.4 Azure Function
Support for Azure Function is implemented in the Micronaut Azure subproject.
Simple Functions with Azure Function
You can implement Azure Functions with Micronaut that implement directly the Azure Function Java SDK. See the documentation on Azure Functions for more information.
Using the CLI
To create an Azure Function: $ mn create-function-app my-app --features azure-function Or with Micronaut Launch $ curl https://launch.micronaut.io/create/function/example\?features\=azure-function -o example.zip $ unzip example.zip -d example |
HTTP Functions with Azure Function
You can deploy regular Micronaut applications that use @Controller etc. using Micronaut’s support for Azure HTTP Functions. See the documentation on Azure HTTP Functions for more information.
Using the CLI
To create a Azure HTTP Function: $ mn create-app my-app --features azure-function Or with Micronaut Launch $ curl https://launch.micronaut.io/example.zip\?features\=azure-function -o example.zip $ unzip example.zip -d example |
10 Message-Driven Microservices
In the past, with monolithic applications, message listeners that listened to messages from messaging systems would frequently be embedded in the same application unit.
In Microservice architectures it is common to have individual Microservice applications that are driven by a message system such as RabbitMQ or Kafka.
In fact a Message-driven Microservice may not even feature an HTTP endpoint or HTTP server (although this can be valuable from a health check and visibility perspective).
10.1 Kafka Support
Apache Kafka is a distributed stream processing platform that can be used for a range of messaging requirements in addition to stream processing and real-time data handling.
Micronaut features dedicated support for defining both Kafka Producer
and Consumer
instances. Micronaut applications built with Kafka can be deployed with or without the presence of an HTTP server.
With Micronaut’s efficient compile-time AOP and cloud native features, writing efficient Kafka consumer applications that use very little resources is a breeze.
See the documentation for Micronaut Kafka for more information on how to build Kafka applications with Micronaut.
10.2 RabbitMQ Support
RabbitMQ is the most widely deployed open source message broker.
Micronaut features dedicated support for defining both RabbitMQ publishers and consumers. Micronaut applications built with RabbitMQ can be deployed with or without the presence of an HTTP server.
With Micronaut’s efficient compile-time AOP, using RabbitMQ has never been easier. Support has been added for publisher confirms and RPC through reactive streams.
See the documentation for Micronaut RabbitMQ for more information on how to build RabbitMQ applications with Micronaut.
10.3 Nats.io Support
Nats.io is a simple, secure and high performance open source messaging system for cloud native applications, IoT messaging, and microservices architectures.
Micronaut features dedicated support for defining both Nats.io publishers and consumers. Micronaut applications built with Nats.io can be deployed with or without the presence of an HTTP server.
With Micronaut’s efficient compile-time AOP, using Nats.io has never been easier. Support has been added for publisher confirms and RPC through reactive streams.
See the documentation for Micronaut Nats for more information on how to build Nats.io applications with Micronaut.
11 Standalone Command Line Applications
In certain cases you may wish to create standalone command-line (CLI) applications that interact with your Microservice infrastructure.
Examples of applications like this include scheduled tasks, batch applications and general command line applications.
In this case having a robust way to parse command line options and positional parameters is important.
11.1 Picocli Support
Picocli is a command line parser that supports usage help with ANSI colors, autocomplete and nested subcommands. It has an annotations API to create command line applications with almost no code, and a programmatic API for dynamic uses like creating Domain Specific Languages.
See the documentation for the Picocli integration for more information.
12 Configurations
Micronaut features several built-in configurations that enable integration with common databases and other servers.
12.1 Configurations for Reactive Programming
RxJava 2 is the default reactive programming library used by Micronaut, however individual modules for other reactive libraries have been added.
12.1.1 RxJava 3 Support
To add support for RxJava 3 add the following module:
implementation("io.micronaut.rxjava3:micronaut-rxjava3")
<dependency>
<groupId>io.micronaut.rxjava3</groupId>
<artifactId>micronaut-rxjava3</artifactId>
</dependency>
To use the RxJava 3 HTTP client add the following dependency:
implementation("io.micronaut.rxjava3:micronaut-rxjava3-http-client")
<dependency>
<groupId>io.micronaut.rxjava3</groupId>
<artifactId>micronaut-rxjava3-http-client</artifactId>
</dependency>
For more information see the documentation for Micronaut RxJava 3.
12.1.2 Reactor Support
To add support for Reactor add the following module:
implementation("io.micronaut.reactor:micronaut-reactor")
<dependency>
<groupId>io.micronaut.reactor</groupId>
<artifactId>micronaut-reactor</artifactId>
</dependency>
To use the RxJava 3 HTTP client add the following dependency:
implementation("io.micronaut.reactor:micronaut-reactor-http-client")
<dependency>
<groupId>io.micronaut.reactor</groupId>
<artifactId>micronaut-reactor-http-client</artifactId>
</dependency>
For more information see the documentation for Micronaut Reactor.
12.1.3 RxJava 1 Support
Legacy support for RxJava 1 can be added with the following module:
implementation("io.micronaut.rxjava1:micronaut-rxjava1")
<dependency>
<groupId>io.micronaut.rxjava1</groupId>
<artifactId>micronaut-rxjava1</artifactId>
</dependency>
For more information see the Micronaut RxJava1 documentation.
12.2 Configurations for Data Access
The table summarizes the configuration modules and the dependencies you should add to your build to enable them.
Dependency | Description |
---|---|
|
Configures SQL DataSource instances using Commons DBCP |
|
Configures SQL DataSource instances using Hikari Connection Pool |
|
Configures SQL DataSource instances using Tomcat Connection Pool |
|
Configures Hibernate/JPA EntityManagerFactory beans |
|
Configures GORM for Hibernate for Groovy applications |
|
Configures the MongoDB Reactive Driver |
|
Configures GORM for MongoDB for Groovy applications |
|
Configures the Bolt Java Driver for Neo4j |
|
Configures GORM for Neo4j for Groovy applications |
|
Configures the Reactive MySQL Client |
|
Configures the Reactive Postgres Client |
|
|
|
Configures the Datastax Java Driver for Cassandra |
For example, to add support for MongoDB you define the following dependency:
compile "io.micronaut.mongodb:micronaut-mongo-reactive"
For Groovy users, Micronaut provides special support for GORM.
For GORM for Hibernate you should not have both the hibernate-jpa and hibernate-gorm dependency.
|
The following sections go into more detail about configuration options and the exposed beans for each implementation.
12.2.1 Configuring a SQL Data Source
Java data sources can be configured for one of three currently provided implementations. Apache DBCP2, Hikari, and Tomcat are supported by default.
Configuring a JDBC DataSource
Using the CLI
If you are creating your project using the Micronaut CLI, supply one of the $ mn create-app my-app --features jdbc-tomcat |
To get started, simply add a dependency to one of the JDBC configurations that corresponds to the implementation you would like to use. Choose one of the following:
runtime("io.micronaut.sql:micronaut-jdbc-tomcat")
<dependency>
<groupId>io.micronaut.sql</groupId>
<artifactId>micronaut-jdbc-tomcat</artifactId>
<scope>runtime</scope>
</dependency>
runtime("io.micronaut.sql:micronaut-jdbc-hikari")
<dependency>
<groupId>io.micronaut.sql</groupId>
<artifactId>micronaut-jdbc-hikari</artifactId>
<scope>runtime</scope>
</dependency>
runtime("io.micronaut.sql:micronaut-jdbc-dbcp")
<dependency>
<groupId>io.micronaut.sql</groupId>
<artifactId>micronaut-jdbc-dbcp</artifactId>
<scope>runtime</scope>
</dependency>
runtime("io.micronaut.sql:micronaut-jdbc-ucp")
<dependency>
<groupId>io.micronaut.sql</groupId>
<artifactId>micronaut-jdbc-ucp</artifactId>
<scope>runtime</scope>
</dependency>
You also need to add a JDBC driver dependency to your classpath. For example to add the H2 In-Memory Database:
runtime("com.h2database:h2")
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>
For more information see the Configuring JDBC section of the Micronaut SQL libraries project.
12.2.2 Configuring Hibernate
Setting up a Hibernate/JPA EntityManager
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features hibernate-jpa |
Micronaut features built in support for configuring a Hibernate / JPA EntityManager
that builds on the SQL DataSource support.
Once you have configured one or many DataSources to use Hibernate, you will need to add the hibernate-jpa
dependency to your build configuration:
implementation("io.micronaut.sql:micronaut-hibernate-jpa")
<dependency>
<groupId>io.micronaut.sql</groupId>
<artifactId>micronaut-hibernate-jpa</artifactId>
</dependency>
For more information see the Configuring Hibernate section of the Micronaut SQL libraries project.
Using GORM for Hibernate
For Groovy users and users familiar with the Grails framework, special support for GORM for Hibernate is available. To use GORM for Hibernate you should not include Micronaut’s built in SQL Support or the hibernate-jpa
dependency since GORM itself takes responsibility for creating the DataSource
, SessionFactory
etc.
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features hibernate-gorm |
See the GORM Modules section of the Micronaut for Groovy user guide.
12.2.3 Configuring MongoDB
Setting up the Native MongoDB Driver
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features mongo-reactive |
Micronaut includes a configuration to automatically configure the native MongoDB Java driver. To use this configuration, add the following dependency to your application:
implementation("io.micronaut.mongodb:micronaut-mongo-reactive")
<dependency>
<groupId>io.micronaut.mongodb</groupId>
<artifactId>micronaut-mongo-reactive</artifactId>
</dependency>
Then configure the URI of the MongoDB server in application.yml
:
mongodb:
uri: mongodb://username:password@localhost:27017/databaseName
The mongodb.uri follows the MongoDB Connection String format.
|
A non-blocking Reactive Streams MongoClient is then available for dependency injection.
To use the blocking driver, add a dependency to your application to the mongo-java-driver.
compile "org.mongodb:mongo-java-driver"
Then the blocking MongoClient will be available for injection.
See the Micronaut MongoDB documentation for further information on configuring and using MongoDB within Micronaut.
12.2.4 Configuring Neo4j
Micronaut features dedicated support for automatically configuring the Neo4j Bolt Driver for the popular Neo4j Graph Database.
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features neo4j-bolt |
To configure the Neo4j Bolt driver you should first add the neo4j-bolt
module to your classpath:
implementation("io.micronaut:micronaut-neo4j-bolt")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-neo4j-bolt</artifactId>
</dependency>
You should then configure the URI of the Neo4j server you wish to communicate with in application.yml
:
neo4j.uri
neo4j:
uri: bolt://localhost
The neo4j.uri setting should be in the format as described in the Connection URIs section of the Neo4j documentation
|
Once you have the above configuration in place you can inject an instance of the org.neo4j.driver.v1.Driver
bean, which features both a synchronous blocking API and a non-blocking API based on CompletableFuture
.
See the Micronaut Neo4j documentation for further information on configuring and using Neo4j within Micronaut.
12.2.5 Configuring Postgres
Micronaut supports reactive and non-blocking client to connect to Postgres using vertx-pg-client, allowing to handle many database connections with a single thread.
Configuring the Reactive Postgres Client
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features vertx-pg-client |
To configure the Reactive Postgres client you should first add vertx-pg-client
module to your classpath:
compile "io.micronaut.sql:micronaut-vertx-pg-client"
For more information see the Configuring Reactive Postgres section of the Micronaut SQL libraries project.
12.2.6 Configuring Redis
Micronaut features automatic configuration of the Lettuce driver for Redis via the redis-lettuce
module.
Configuring Lettuce
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features redis-lettuce |
To configure the Lettuce driver you should first add the redis-lettuce
module to your classpath:
compile "io.micronaut.redis:micronaut-redis-lettuce"
You should then configure the URI of the Redis server you wish to communicate with in application.yml
:
redis.uri
redis:
uri: redis://localhost
The redis.uri setting should be in the format as described in the Connection URIs section of the Lettuce wiki
|
You can also specify multiple Redis URIs using redis.uris
in which case a RedisClusterClient
is created instead.
For more information and further documentation see the Micronaut Redis documentation.
12.2.7 Configuring Cassandra
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features cassandra |
For more information see the Micronaut Cassandra Module documentation.
12.2.8 Configuring Liquibase
To configure Micronaut integration with Liquibase, please follow these instructions.
12.2.9 Configuring Flyway
To configure Micronaut integration with Flyway, please follow these instructions
13 Language Support
Micronaut supports any JVM language that implements the Java Annotation Processor API.
Although Groovy, does not in fact support this API, special support has been built via an AST transformation. The current list of supported languages is: Java, Groovy and Kotlin (via the kapt tool).
Theoretically any language that supports a way to analyze the AST at compile time could be supported. The io.micronaut.inject.writer package includes classes that are language neutral and are used to build BeanDefinition classes at compile time using the ASM tool. |
The following sections cover language specific features and considerations for using Micronaut.
13.1 Micronaut for Java
For Java, Micronaut uses a Java BeanDefinitionInjectProcessor annotation processor to process classes at compile time and produce BeanDefinition classes.
The major advantage here is that you pay a slight cost at compile time, but at runtime Micronaut is largely reflection-free, fast and consumes very little memory.
13.1.1 Using Micronaut with Java 9+
Micronaut is built with Java 8, however works fine with Java 9/10 and above as well. The classes that Micronaut generates sit alongside existing classes within the same package, hence do not violate anything regarding the Java module system.
There are some considerations to take into account when using Java 9/10 with Micronaut.
The javax.annotation package
Using the CLI
If you are creating your project using the Micronaut CLI, the |
The javax.annotation
, which includes @PostConstruct
, @PreDestroy
etc. is no longer part of the core JDK but instead a module. If you run under Java 9+ you will need to import the module or add the dependency to your classpath:
javax.annotation
dependencyimplementation 'javax.annotation:javax.annotation-api:1.3.2'
13.1.2 Incremental Annotation Processing with Gradle
Micronaut supports Gradle incremental annotation processing which helps speed up builds by compiling only classes that have changed avoiding a full recompilation.
However, the support is disabled by default since Micronaut allows the definition of custom meta-annotations (to for example define custom AOP advice) that need to be configured for processing.
The following example demonstrates how to enable and configure incremental annotation processing for annotations you have defined under the com.example
package:
tasks.withType(JavaCompile) {
options.compilerArgs = [
'-Amicronaut.processing.incremental=true',
'-Amicronaut.processing.annotations=com.example.*',
]
}
If you do not enable processing for custom annotations you define these annotations will simple be ignored by Micronaut which may break your application. |
13.1.3 Using Project Lombok
Project Lombok is a popular java library that adds a number of useful AST transformations to the Java language via annotation processors.
Since both Micronaut and Lombok use annotation processors, special care needs to be taken when configuring Lombok to ensure that the Lombok processor runs before Micronaut’s processor.
For example in Gradle adding the following dependencies to the dependencies
block:
compileOnly 'org.projectlombok:lombok:1.18.12'
annotationProcessor "org.projectlombok:lombok:1.18.12"
...
// Micronaut processor define after Lombok
annotationProcessor "io.micronaut:micronaut-inject-java"
Or when using Maven:
<dependencies>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.12</version>
<scope>provided</scope>
</dependency>
</dependencies>
...
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.12</version>
</path>
<path>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-inject-java</artifactId>
<version>${micronaut.version}</version>
</path>
</annotationProcessorPaths>
In both cases (Gradle and Maven) the Micronaut processor should be configured after the Lombok processor, reversing the order of the declared dependencies will not work. |
13.1.4 Configuring an IDE
You can use any IDE to develop Micronaut applications, if you depend on your configured build tool (Gradle or Maven) to build the application.
However, if you wish to run tests within the IDE that is currently possible with IntelliJ IDEA or Eclipse 4.9 M2 or above.
See the section on IDE Setup in the Quick start for more information on how to configure IntelliJ or Eclipse.
13.1.5 Retaining Parameter Names
By default with Java, the parameter name data for method parameters is not retained at compile time. This can be a problem for Micronaut if you do not define parameter names explicitly and depend on an external JAR that is already compiled.
Consider this interface:
interface HelloOperations {
@Get("/hello/{name}")
String hello(String name);
}
At compile time the parameter name name
is lost and becomes simply arg0
when compiled against or read via reflection later. To avoid this problem you have two options. You can either declare the parameter name explicitly:
interface HelloOperations {
@Get("/hello/{name}")
String hello(@QueryValue("name") String name);
}
Or alternatively it is recommended that you compile all byte code with -parameters
flag to javac
. See Obtaining Names of Method Parameters. For example in build.gradle
:
compileJava.options.compilerArgs += '-parameters'
13.2 Micronaut for Groovy
The Groovy language has first class support in Micronaut.
Groovy Specific Modules
Additional modules exist specific to Groovy that improve the overall experience. These are detailed in the table below:
Dependency | Description |
---|---|
|
Includes AST transformations to generate bean definitions. Should be |
|
Adds the ability to specify configuration placed in |
|
Includes AST transforms that make it easier to write Functions for AWS Lambda |
The most common module you will need is micronaut-inject-groovy
, which enables DI and AOP for classes written in Groovy.
Groovy Support in the CLI
The Command Line Interface for Micronaut includes special support for Groovy. To create a Groovy application use the groovy
lang option. For example:
$ mn create-app hello-world --lang groovy
The above will generate a Groovy project, built with Gradle. You can use the -build maven
flag to generate a project built with Maven instead.
Once you have created an application with the groovy
feature commands like create-controller
, create-client
etc. will generate Groovy files instead of Java. The following example demonstrates this action when using interactive mode of the CLI:
$ mn
| Starting interactive mode...
| Enter a command name to run. Use TAB for completion:
mn>
create-bean create-client create-controller
create-job help
mn> create-bean helloBean
| Rendered template Bean.groovy to destination src/main/groovy/hello/world/HelloBean.groovy
The above example demonstrates creating a Groovy bean that looks like the following:
package hello.world
import javax.inject.Singleton
@Singleton
class HelloBean {
}
Groovy automatically imports groovy.lang.Singleton which can be confusing as it conflicts with javax.inject.Singleton . Make sure you use javax.inject.Singleton when declaring a Micronaut singleton bean to avoid surprising behavior.
|
We can also create a client - don’t forget Micronaut can act as a client or a server!
mn> create-client helloClient
| Rendered template Client.groovy to destination src/main/groovy/hello/world/HelloClient.groovy
package hello.world
import io.micronaut.http.client.annotation.Client
import io.micronaut.http.annotation.Get
import io.micronaut.http.HttpStatus
@Client("hello")
interface HelloClient {
@Get
HttpStatus index()
}
Now let’s create a controller:
mn> create-controller helloController
| Rendered template Controller.groovy to destination src/main/groovy/hello/world/HelloController.groovy
| Rendered template ControllerSpec.groovy to destination src/test/groovy/hello/world/HelloControllerSpec.groovy
mn>
package hello.world
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.HttpStatus
@Controller("/hello")
class HelloController {
@Get
HttpStatus index() {
return HttpStatus.OK
}
}
As you can see from the output from the CLI a Spock test was also generated for you demonstrating how to test the controller:
...
void "test index"() {
given:
HttpResponse response = client.toBlocking().exchange("/hello")
expect:
response.status == HttpStatus.OK
}
...
Notice how you use Micronaut both as client and as a server to test itself.
Programmatic Routes with GroovyRouterBuilder
If you prefer to build your routes programmatically (similar to Grails UrlMappings
) then a special io.micronaut.web.router.GroovyRouteBuilder
exists that has some enhancements to make the DSL better.
The following example shows GroovyRouteBuilder
in act:
@Singleton
static class MyRoutes extends GroovyRouteBuilder {
MyRoutes(ApplicationContext beanContext) {
super(beanContext)
}
@Inject
void bookResources(BookController bookController, AuthorController authorController) {
GET(bookController) {
POST("/hello{/message}", bookController.&hello) (1)
}
GET(bookController, ID) { (2)
GET(authorController)
}
}
}
1 | You can use injected controllers to create routes by convention and Groovy method references to create routes to methods |
2 | The ID property can be used to reference include an {id} URI variable |
The above example results in the following routes:
-
/book
- Maps toBookController.index()
-
/book/hello/{message}
- Maps toBookController.hello(String)
-
/book/{id}
- Maps toBookController.show(String id)
-
/book/{id}/author
- Maps toAuthorController.index
Using GORM in a Groovy application
GORM is a data access toolkit originally created as part of Grails framework. It supports multiple database types. The following table summarizes the modules needed to use GORM and links to documentation.
Dependency | Description |
---|---|
|
Configures GORM for Hibernate for Groovy applications. See the Hibernate Support docs |
|
Configures GORM for MongoDB for Groovy applications. See the Mongo Support docs. |
|
Configures GORM for Neo4j for Groovy applications. See the Neo4j Support docs. |
Once you have configured a GORM implementation per the instructions linked in the table above you can use all features of GORM.
GORM Data Services can also participate in dependency injection and life cycle methods:
@Service(Vehicle)
abstract class VehicleService {
@PostConstruct
void init() {
// do something on initialization
}
abstract Vehicle findVehicle(@NotBlank String name)
abstract Vehicle saveVehicle(@NotBlank String name)
}
You can also define the service as an interface instead of an abstract class if you want GORM to do all of the work and you don’t want to add your own behaviors.
Serverless Functions with Groovy
A microservice application is just one way to use Micronaut. You can also use it for serverless functions like on AWS Lambda.
With the function-groovy
module, Micronaut features enhanced support for functions written in Groovy.
See the section on Serverless Functions for more information.
13.3 Micronaut for Kotlin
The Command Line Interface for Micronaut includes special support for Kotlin. To create a Kotlin application use the kotlin lang option. For example:
|
$ mn create-app hello-world --lang kotlin
Support for Kotlin in Micronaut is built upon the Kapt compiler plugin, which includes support for Java annotation processors. To use Kotlin in your Micronaut application, you will simply need to add the proper dependencies to configure and run kapt on your kt
source files. Kapt will create Java "stub" classes for each of your Kotlin classes, which can then be processed by Micronaut’s Java annotation processor. The stubs are not included in the final compiled application.
Learn more about kapt and its features from the official documentation. |
The Micronaut annotation processors are declared in the kapt
scope when using Gradle. For example:
dependencies {
compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlinVersion" (1)
compile "org.jetbrains.kotlin:kotlin-reflect:$kotlinVersion"
kapt "io.micronaut:micronaut-inject-java" (2)
kaptTest "io.micronaut:micronaut-inject-java" (3)
...
}
1 | Add the Kotlin standard libraries |
2 | Add the micronaut-inject-java dependency under the kapt scope, so classes in src/main are processed |
3 | Add the micronaut-inject-java dependency under the kaptTest scope, so classes in src/test are processed. |
With a build.gradle
file similar to the above, you can now run your Micronaut application using the run
task (provided by the Application plugin):
$ ./gradlew run
An example controller written in Kotlin can be seen below:
package example
import io.micronaut.http.annotation.*
@Controller("/")
class HelloController {
@Get("/hello/{name}")
fun hello(name: String): String {
return "Hello $name"
}
}
13.3.1 Kotlin, Kapt and IntelliJ
As of this writing IntelliJ’s built-in compiler does not directly support Kapt and annotation processing. You must instead configure Intellij to run Gradle (or Maven) compilation as a build step before running your tests or application class.
First edit the run configuration for tests or for the application and select "Run Gradle task" as a build step:
Then add the classes
task as task to execute for the application or for tests the testClasses
task:
Now whenever you run tests or the application Micronaut classes will be generated at compilation time.
Alternatively, you can delegate IntelliJ build/run actions to Gradle completely:
13.3.2 Incremental Annotation Processing with Gradle and Kapt
To enable gradle incremental annotation processing with Kapt the arguments as specified Incremental Annotation Processing with Gradle must be sent to Kapt
The following example demonstrates how to enable and configure incremental annotation processing for annotations you have defined under the com.example
and io.example
packages:
kapt {
arguments {
arg("micronaut.processing.incremental", true)
arg("micronaut.processing.annotations", "com.example.*,io.example.*")
}
}
If you do not enable processing for custom annotations you define these annotations will simple be ignored by Micronaut which may break your application. |
13.3.3 Kotlin and AOP Advice
Micronaut provides a compile-time AOP API that does not use reflection. When you use any Micronaut’s AOP Advice,
it creates a subclass at compile-time to provide the AOP behaviour. This can be a problem because Kotlin classes are final by default. If the application was created with the Micronaut CLI, then the Kotlin all-open plugin is configured for you to automatically change your classes to open
when an AOP annotation is used. To configure it yourself, simply add the Around class to the list of supported annotations.
If you prefer not to or cannot use the all-open
plugin, you must declare the classes that are annotated with an AOP annotation to be open:
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.HttpStatus
import io.micronaut.validation.Validated
import javax.validation.constraints.NotBlank
@Validated
@Controller("/email")
open class EmailController { (1)
@Get("/send")
fun index(@NotBlank recipient: String, (1)
@NotBlank subject: String): HttpStatus {
return HttpStatus.OK
}
}
1 | if you use @Validated AOP Advice, you need to use open at class and method level. |
The all-open plugin does not handle methods. If you declare an AOP annotation on a method, you must manually declare it as open.
|
13.3.4 Kotlin and Retaining Parameter Names
Like with Java, the parameter name data for method parameters is not retained at compile time when using Kotlin. This can be a problem for Micronaut if you do not define parameter names explicitly and depend on an external JAR that is already compiled.
To enable the retention of parameter name data with Kotlin you should set the javaParameters
option to true
in your build.gradle
:
compileTestKotlin {
kotlinOptions {
jvmTarget = '1.8'
javaParameters = true
}
}
13.3.5 Coroutines Support
Kotlin coroutines allow you to create asynchronous applications with imperative style code. A Micronaut’s controller
action can be a suspend
function:
@Get("/simple")
suspend fun simple(): String { (1)
return "Hello"
}
1 | The function is marked as suspend , though in reality it won’t be suspended. |
@Get("/delayed")
suspend fun delayed(): String { (1)
delay(1) (2)
return "Delayed"
}
1 | The function is marked as suspend . |
2 | The delay is called to make sure that a function is suspended and the response is returned from a different thread. |
@Status(HttpStatus.CREATED) (1)
@Get("/status")
suspend fun status(): Unit {
}
1 | suspend function also works when all we want is to return a status. |
@Status(HttpStatus.CREATED)
@Get("/statusDelayed")
suspend fun statusDelayed(): Unit {
delay(1)
}
You can also use Flow
type for streaming server and client. A streaming controller can return Flow
, for example:
@Get(value = "/headlinesWithFlow", processes = [MediaType.APPLICATION_JSON_STREAM])
internal fun streamHeadlinesWithFlow(): Flow<Headline> = (1)
flow { (2)
repeat(100) { (3)
with (Headline()) {
text = "Latest Headline at " + ZonedDateTime.now()
emit(this) (4)
delay(1_000) (5)
}
}
}
1 | A method streamHeadlinesWithFlow is defined that produces application/x-json-stream |
2 | A Flow is created using flow |
3 | This Flow will emit 100 messages |
4 | Emitting will happend with emit suspend function |
5 | There will be a 1 second delay between messages |
A streaming client can simply return a Flow
, for example:
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import kotlinx.coroutines.flow.Flow
@Client("/streaming")
interface HeadlineFlowClient {
@Get(value = "/headlinesWithFlow", processes = [MediaType.APPLICATION_JSON_STREAM]) (1)
fun streamFlow(): Flow<Headline> (2)
}
1 | The @Get method is defined as processing responses of type APPLICATION_JSON_STREAM |
2 | A Flow is used as the return type |
13.4 Micronaut for GraalVM
GraalVM is a new universal virtual machine from Oracle that supports a polyglot runtime environment and the ability to compile Java applications down to native machine code.
Any Micronaut application can be run using the GraalVM JVM, however special support has been added to Micronaut to support running Micronaut applications using GraalVM’s native-image
tool.
Micronaut currently supports GraalVM 20.2.0 version and the team is improving the support in every new release. Don’t hesitate to report issues however if you find any problem.
A lot of Micronaut’s modules and third party libraries have been verified to work with GraalVM: HTTP server, HTTP client, Function support, Micronaut Data JDBC and JPA, Service Discovery, RabbitMQ, Views, Security, Zipkin,… Support for other modules is still evolving and will improve over time.
Getting Started
Use of GraalVM’s native-image tool is only supported in Java or Kotlin projects. Groovy relies heavily on
reflection which is only partially supported by GraalVM.
|
To start using GraalVM you should first install the GraalVM SDK via the Getting Started or using Sdkman!.
13.4.1 Microservices as GraalVM native images
Getting Started with Micronaut and Graal
To get started creating a Microservice that can be compiled into a native image, use the graalvm
feature when creating the application with the CLI:
$ mn create-app hello-world --features graalvm
The graalvm
feature adds three important items:
-
The
svm
andgraal
dependencies to yourbuild.gradle
(orpom.xml
if--build maven
is used). -
A
Dockerfile
which can be used to construct the native image using Docker and a scriptdocker-build.sh
to run it. -
A
native-image.properties
configuration filesrc/main/resources/META-INF/native-image
to simplify building the image.
The native-image.properties
file that is generated looks something like:
Args = -H:Name=example \ (1)
-H:Class=example.Application (2)
1 | The -H:Name argument specifies the name of the native image that will be generated. |
2 | The -H:Class argument specifies the entry point of your application (the class that defines a static void main method. |
Building a Native Image Using Docker
To build your native image using Docker simply run:
$ ./gradlew assemble # or ./mvnw package if using Maven
$ docker build . -t hello-world
$ docker run -p 8080:8080 hello-world
Or use the provided script:
$ ./gradlew assemble # or ./mvnw package if using Maven
$ ./docker-build.sh
The provided Dockerfile
is a multi-stage dockerfile which builds the project in two steps:
-
A GraalVM official image will build the native image.
-
A typical dockerfile structure will build the final image which is smaller due to layering.
Building a Native Image Without Using Docker
To build your native image without using Docker you need to install GraalVM SDK via the Getting Started instructions or using Sdkman!:
$ sdk install java 20.2.0.r8-grl # or 20.2.0.r11-grl if you want to use JDK 11
$ sdk use java 20.2.0.r8-grl
The native-image
tool was extracted from the base GraalVM distribution. Currently it is available as an early adopter plugin. To install it, run:
native-image
tool$ gu install native-image
$ ./gradlew assemble
$ native-image -cp build/libs/hello-world-0.1-all.jar
$ ./mvnw package
$ native-image -cp target/hello-world-0.1-all.jar
$ ./hello-world
Understanding Micronaut and Graal
Micronaut itself does not rely on reflection or dynamic classloading so works automatically with GraalVM native, however certain third party libraries used by Micronaut may require additional input about uses of reflection.
Micronaut includes an annotation processor that helps to handle generating the reflection-config.json
and resource-config.json
metadata files that are automatically picked up by the native-image
tool:
annotationProcessor("io.micronaut:micronaut-graal")
<annotationProcessorPaths>
<path>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-graal</artifactId>
</path>
</annotationProcessorPaths>
This processor will generate:
- A reflection-config.json
file in the META-INF/native-image
directory in your build classes directory (target/classes
with Maven and typically build/classes/java/main
with Gradle).
- A native-image.properties
file to read this configuration for all classes annotated with either @Introspected or @TypeHint.
- A resource-config.json
file also in the META-INF/native-image
directory in your build classes directory containing
all the files in the src/main/resources
file.
For example the following class:
package example;
import io.micronaut.core.annotation.*;
@Introspected
class Test {
...
}
The above example will result in the public methods and declared constructors of example.Test
being included in reflection-config.json
.
If you have more advanced requirements and only wish to include certain fields or methods, you can use @ReflectiveAccess instead which can be present on any constructor, field or method to include only the specific field, constructor or method.
If you wish to provide your own reflect.json you can add one to src/main/graal/reflect.json and it will be automatically picked up.
|
Stating with Micronaut 2.0, as the framework generates automatically the file resource-config.json
, if you want to
include your own additional resources you can provide them in src/main/graal/resource-config.json
and they will
automatically added to the generated file.
Adding Additional Classes for Reflective Access
To inform Micronaut of additional classes that should be included in the generated reflect.json
file at compilation time you can either annotate a class with @Introspected or @TypeHint.
The former will generate a compile time introspection as well as allowing reflective access and the latter will only allow reflective access and is typically used on a module or Application
class to include classes that are needed reflectively. For example, the following is taken from Micronaut’s Jackson module:
@TypeHint(
value = { (1)
PropertyNamingStrategy.UpperCamelCaseStrategy.class,
ArrayList.class,
LinkedHashMap.class,
HashSet.class
},
accessType = TypeHint.AccessType.ALL_DECLARED_CONSTRUCTORS (2)
)
1 | The value member is used to specify which classes require reflection. |
2 | The accessType member specifies if only classloading access is needed or whether full reflection on all public members is needed. |
Generating Native Images
GraalVM’s native-image
command is used to generate native images. You can use this command manually to generate your native image. An example can be seen below.
native-image
commandnative-image --class-path build/libs/hello-world-0.1-all.jar (1)
1 | The class-path argument is used to refer to the Micronaut shaded JAR |
Once the image has been built you can run the application using the native image name:
$ ./hello-world
15:15:15.153 [main] INFO io.micronaut.runtime.Micronaut - Startup completed in 14ms. Server Running: http://localhost:8080
As you can see the advantage of having a native image is startup completes in milliseconds and memory consumption does not include the overhead of the JVM (a native Micronaut application runs with just 20mb of memory).
13.4.2 GraalVM and Micronaut FAQ
How does Micronaut manage to run on GraalVM?
Micronaut features a Dependency Injection and Aspect-Oriented Programming runtime that uses no reflection. This makes it easier for Micronaut applications to run on GraalVM since there are limitations particularly around reflection on SubstrateVM.
How can I make a Micronaut application that uses picocli run on GraalVM?
Picocli provides a picocli-codegen
module with a tool for generating a GraalVM reflection configuration file. The tool can be run manually or automatically as part of the build. The module’s README has usage instructions with code snippets for configuring Gradle and Maven to generate a cli-reflect.json
file automatically as part of the build. Add the generated file to the -H:ReflectionConfigurationFiles
option when running the native-image
tool.
What about other Third-Party Libraries?
Micronaut cannot guarantee that third-party libraries work on GraalVM SubstrateVM, that is down to each individual library to implement support.
I Get a "Class XXX is instantiated reflectively…" Exception. What do I do?
If you get an error such as:
Class myclass.Foo[] is instantiated reflectively but was never registered. Register the class by using org.graalvm.nativeimage.RuntimeReflection
You may need to manually tweak the generated reflect.json
file. For regular classes you need to add an entry into the array:
[
{
"name" : "myclass.Foo",
"allDeclaredConstructors" : true
},
...
]
For arrays this needs to use the Java JVM internal array representation. For example:
[
{
"name" : "[Lmyclass.Foo;",
"allDeclaredConstructors" : true
},
...
]
What if I want to set the heap’s maximum size with -Xmx
, but I get an OutOfMemoryError
?
If you set heap’s maximum size in the Dockerfile that you use to build your native image, you will probably get runtime an error like this:
java.lang.OutOfMemoryError: Direct buffer memory
The problem is that Netty is trying to allocate 16MiB of memory per chunk with its default settings for io.netty.allocator.pageSize
and io.netty.allocator.maxOrder
:
int defaultChunkSize = DEFAULT_PAGE_SIZE << DEFAULT_MAX_ORDER; // 8192 << 11 = 16MiB
The simplest solution is to specify io.netty.allocator.maxOrder
explicitly in your Dockerfile’s entrypoint. A working example with -Xmx64m
:
ENTRYPOINT ["/app/application", "-Xmx64m", "-Dio.netty.allocator.maxOrder=8"]
If you want to go further, you can also experiment with io.netty.allocator.numHeapArenas
or io.netty.allocator.numDirectArenas
. You can find more information about Netty’s PooledByteBufAllocator
in the official documentation.
14 Management & Monitoring
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features management |
Inspired by Spring Boot and Grails, the Micronaut management
dependency adds support for monitoring of your application via endpoints: special URIs that return details about the health and state of your application. The management
endpoints are also integrated with Micronaut’s security
dependency, allowing for sensitive data to be restricted to authenticated users in your security system (see Built-in Endpoints Access in the Security section).
To use the management
features described in this section, add the dependency on your classpath.
implementation("io.micronaut:micronaut-management")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-management</artifactId>
</dependency>
14.1 Creating Endpoints
In addition to the Built-In Endpoints, the management
dependency also provides support for creating custom endpoints. Custom endpoints can be enabled and configured identically to the built-in endpoints, and can be used to retrieve and return any metrics or other application data that you require.
14.1.1 The Endpoint Annotation
An Endpoint can be created by annotating a class with the Endpoint annotation, and supplying it with (at minimum) an endpoint id.
@Endpoint("foo")
class FooEndpoint {
...
}
If a single String
argument is supplied to the annotation, it will be used as the endpoint id.
It is possible to supply additional (named) arguments to the annotation. Other possible arguments to @Endpoint
are described in the table below:
Argument | Description | Endpoint Example |
---|---|---|
|
The endpoint id (or name) |
|
|
Prefix used for configuring the endpoint (see Endpoint Configuration) |
|
|
Sets whether the endpoint is enabled when no configuration is set (see Endpoint Configuration) |
|
|
Sets whether the endpoint is sensitive if no configuration is set (see Endpoint Configuration) |
|
Example of custom Endpoint
The following example Endpoint
class will create an endpoint accessible at /date
:
import io.micronaut.management.endpoint.annotation.Endpoint;
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
public class CurrentDateEndpoint {
//.. endpoint methods
}
import io.micronaut.management.endpoint.annotation.Endpoint
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
class CurrentDateEndpoint {
//.. endpoint methods
}
import io.micronaut.management.endpoint.annotation.Endpoint
@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {
//.. endpoint methods
}
14.1.2 Endpoint Methods
Endpoints respond to GET
("read"), POST
("write") and DELETE
("delete") requests. To return a response from an endpoint, annotate its public method/s with one of following annotations:
Annotation | Description |
---|---|
Responds to |
|
Responds to |
|
Responds to |
Read Methods
Annotating a method with the Read annotation will cause it to respond to GET
requests.
import io.micronaut.management.endpoint.annotation.Endpoint;
import io.micronaut.management.endpoint.annotation.Read;
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
public class CurrentDateEndpoint {
private Date currentDate;
@Read
public Date currentDate() {
return currentDate;
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Read
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
class CurrentDateEndpoint {
Date currentDate
@Read
Date currentDate() {
return currentDate
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Read
@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {
private var currentDate: Date? = null
@Read
fun currentDate(): Date? {
return currentDate
}
}
The above method responds to the following request:
$ curl -X GET localhost:55838/date
1526085903689
The Read annotation accepts an optional produces
argument, which sets the media type returned from the method (default is application/json
):
import io.micronaut.management.endpoint.annotation.Endpoint;
import io.micronaut.management.endpoint.annotation.Read;
import io.micronaut.http.MediaType;
import io.micronaut.management.endpoint.annotation.Selector;
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
public class CurrentDateEndpoint {
private Date currentDate;
@Read(produces = MediaType.TEXT_PLAIN) (1)
public String currentDatePrefix(@Selector String prefix) {
return prefix + ": " + currentDate;
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Read
import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
class CurrentDateEndpoint {
Date currentDate
@Read(produces = MediaType.TEXT_PLAIN) (1)
String currentDatePrefix(@Selector String prefix) {
return "${prefix}: ${currentDate}"
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Read
import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector
@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {
private var currentDate: Date? = null
@Read(produces = [MediaType.TEXT_PLAIN]) (1)
fun currentDatePrefix(@Selector prefix: String): String {
return "$prefix: $currentDate"
}
}
1 | Supported media types are represented by MediaType |
The above method responds to the following request:
$ curl -X GET localhost:8080/date/the_date_is
the_date_is: Fri May 11 19:24:21 CDT
Write Methods
Annotating a method with the Write annotation will cause it to respond to POST
requests.
import io.micronaut.management.endpoint.annotation.Endpoint;
import io.micronaut.management.endpoint.annotation.Write;
import io.micronaut.http.MediaType;
import io.micronaut.management.endpoint.annotation.Selector;
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
public class CurrentDateEndpoint {
private Date currentDate;
@Write
public String reset() {
currentDate = new Date();
return "Current date reset";
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Write
import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector
@Endpoint(id = "date",
prefix = "custom",
defaultEnabled = true,
defaultSensitive = false)
class CurrentDateEndpoint {
Date currentDate
@Write
String reset() {
currentDate = new Date()
return "Current date reset"
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Write
import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector
@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {
private var currentDate: Date? = null
@Write
fun reset(): String {
currentDate = Date()
return "Current date reset"
}
}
The above method responds to the following request:
$ curl -X POST http://localhost:39357/date
Current date reset
The Write annotation accepts an optional consumes
argument, which sets the media type accepted by the method (default is application/json
):
import io.micronaut.context.annotation.Requires;
import io.micronaut.management.endpoint.annotation.Endpoint;
import io.micronaut.management.endpoint.annotation.Write;
import io.micronaut.http.MediaType;
@Endpoint(id = "message", defaultSensitive = false)
public class MessageEndpoint {
String message;
@Write(consumes = MediaType.APPLICATION_FORM_URLENCODED, produces = MediaType.TEXT_PLAIN)
public String updateMessage(String newMessage) {
this.message = newMessage;
return "Message updated";
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Write
import io.micronaut.http.MediaType
@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {
String message
@Write(consumes = MediaType.APPLICATION_FORM_URLENCODED, produces = MediaType.TEXT_PLAIN)
String updateMessage(String newMessage) { (1)
message = newMessage
return "Message updated"
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Write
import io.micronaut.http.MediaType
@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {
internal var message: String? = null
@Write(consumes = [MediaType.APPLICATION_FORM_URLENCODED], produces = [MediaType.TEXT_PLAIN])
fun updateMessage(newMessage: String): String { (1)
this.message = newMessage
return "Message updated"
}
}
The above method responds to the following request:
$ curl -X POST http://localhost:65013/message -H 'Content-Type: application/x-www-form-urlencoded' -d $'newMessage=A new message'
Message updated
Delete Methods
Annotating a method with the Delete annotation will cause it to respond to DELETE
requests.
import io.micronaut.context.annotation.Requires;
import io.micronaut.management.endpoint.annotation.Endpoint;
import io.micronaut.management.endpoint.annotation.Delete;
@Endpoint(id = "message", defaultSensitive = false)
public class MessageEndpoint {
String message;
@Delete
public String deleteMessage() {
this.message = null;
return "Message deleted";
}
}
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Delete
@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {
String message
@Delete
String deleteMessage() {
message = null
return "Message deleted"
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Delete
@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {
internal var message: String? = null
@Delete
fun deleteMessage(): String {
this.message = null
return "Message deleted"
}
}
The above method responds to the following request:
$ curl -X DELETE http://localhost:65013/message
Message deleted
14.1.3 Endpoint Sensitivity
Endpoint sensitivity can be controlled for the entire endpoint through the endpoint annotation and configuration. Individual methods can be configured independently from the endpoint as a whole, however. The @Sensitive annotation can be applied to methods to control their sensitivity.
import io.micronaut.context.annotation.Requires;
import io.micronaut.http.MediaType;
import io.micronaut.management.endpoint.annotation.*;
import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
@Endpoint(id = "alerts", defaultSensitive = false) (1)
public class AlertsEndpoint {
private final List<String> alerts = new CopyOnWriteArrayList<>();
@Read
List<String> getAlerts() {
return alerts;
}
@Delete
@Sensitive(true) (2)
void clearAlerts() {
alerts.clear();
}
@Write(consumes = MediaType.TEXT_PLAIN)
@Sensitive(property = "add.sensitive", defaultValue = true) (3)
void addAlert(String alert) {
alerts.add(alert);
}
}
import io.micronaut.context.annotation.Requires;
import io.micronaut.http.MediaType;
import io.micronaut.management.endpoint.annotation.*;
import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
@Endpoint(id = "alerts", defaultSensitive = false) (1)
class AlertsEndpoint {
private final List<String> alerts = new CopyOnWriteArrayList<>();
@Read
List<String> getAlerts() {
alerts
}
@Delete
@Sensitive(true) (2)
void clearAlerts() {
alerts.clear()
}
@Write(consumes = MediaType.TEXT_PLAIN)
@Sensitive(property = "add.sensitive", defaultValue = true) (3)
void addAlert(String alert) {
alerts.add(alert)
}
}
import io.micronaut.context.annotation.Requires
import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.*
import java.util.concurrent.CopyOnWriteArrayList
@Endpoint(id = "alerts", defaultSensitive = false) (1)
class AlertsEndpoint {
private val alerts: MutableList<String> = CopyOnWriteArrayList()
@Read
fun getAlerts(): List<String> {
return alerts
}
@Delete
@Sensitive(true) (2)
fun clearAlerts() {
alerts.clear()
}
@Write(consumes = [MediaType.TEXT_PLAIN])
@Sensitive(property = "add.sensitive", defaultValue = true) (3)
fun addAlert(alert: String) {
alerts.add(alert)
}
}
1 | The endpoint is not sensitive by default and the default prefix of endpoints is used. |
2 | This method is always sensitive, regardless of any other factors |
3 | The property value is appended to the prefix and id to lookup a configuration value |
If the configuration key endpoints.alerts.add.sensitive
is set, that value will determine the sensitivity of the addAlert
method.
-
endpoint
is the first token because that is the default value forprefix
in the endpoint annotation and is not set explicity in this example. -
alerts
is the next token because that is the endpoint id -
add.sensitive
is the next token because that is the value set to theproperty
member of the @Sensitive annotation.
If the configuration key is not set, the defaultValue
will be used (defaults to true
).
14.1.4 Endpoint Configuration
Endpoints with the endpoints
prefix can be configured through their default endpoint id. If an endpoint exists with the id of foo
, it can be configured through endpoints.foo
. In addition, default values can be provided through the all
prefix.
For example, consider the following endpoint.
@Endpoint("foo")
class FooEndpoint {
...
}
By default the endpoint will be enabled. To disable the endpoint, set endpoints.foo.enabled
to false. If endpoints.foo.enabled
is not set at all and endpoints.all.enabled
is set to false, the endpoint will be disabled.
The configuration values for the endpoint override the ones for all
. If endpoints.foo.enabled
is explicitly set to true
and endpoints.all.enabled
is explicitly set to false
, the endpoint will be enabled.
For all endpoints, the following configuration values can be set.
endpoints:
<any endpoint id>:
enabled: Boolean
sensitive: Boolean
The base path for all endpoints is / by default. If you prefer the endpoints to be available under a different base path, configure endpoints.all.path . For example, if the value is set to /endpoints , the foo endpoint will be accessible at /endpoints/foo .
|
14.2 Built-In Endpoints
When the management
dependency is added to your project, the following built-in endpoints are enabled by default:
Endpoint | URI | Description |
---|---|---|
|
Returns information about the loaded bean definitions in the application (see BeansEndpoint) |
|
|
Returns information about the "health" of the application (see HealthEndpoint) |
|
|
Returns static information from the state of the application (see InfoEndpoint) |
|
|
Returns information about available loggers and permits changing the configured log level (see LoggersEndpoint) |
|
|
Return the application metrics. Requires the |
|
|
Refreshes the application state (see RefreshEndpoint) |
|
|
Returns information about URIs available to be called for your application (see RoutesEndpoint) |
|
|
Returns information about the environment and its property sources (see EnvironmentEndpoint) |
|
|
Returns information about the current threads in the application. |
In addition, the following built-in endpoint(s) are provided by the management
dependency but are not enabled by default:
Endpoint | URI | Description |
---|---|---|
|
Returns information about the caches and permits invalidating them (see CachesEndpoint) |
|
|
Shuts down the application server (see ServerStopEndpoint) |
It is possible to open all endpoints for unauthenticated access defining endpoints.all.sensitive: false but
this should be used with care because private and sensitive information will be exposed.
|
Management Port
By default all management endpoints are exposed over the same port as the application. You can alter this behaviour by specifying the endpoints.all.port
setting:
endpoints:
all:
port: 8085
In the above example the management endpoints will be exposed only over port 8085.
JMX
Micronaut provides functionality to register endpoints with JMX. See the section on JMX to get started.
14.2.1 The Beans Endpoint
The beans endpoint returns information about the loaded bean definitions in the application. The bean data returned by default is an object where the key is the bean definition class name and the value is an object of properties about the bean.
To execute the beans endpoint, send a GET request to /beans.
Configuration
To configure the beans endpoint, supply configuration through endpoints.beans
.
endpoints:
beans:
enabled: Boolean
sensitive: Boolean
Customization
The beans endpoint is composed of a bean definition data collector and a bean data implementation. The bean definition data collector (BeanDefinitionDataCollector) is responsible for returning a publisher that will return the data used in the response. The bean definition data (BeanDefinitionData) is responsible for returning data about an individual bean definition.
To override the default behavior for either of the helper classes, either extend the default implementations (RxJavaBeanDefinitionDataCollector, DefaultBeanDefinitionData), or implement the relevant interface directly. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
14.2.2 The Info Endpoint
The info endpoint returns static information from the state of the application. The info exposed can be provided by any number of "info sources".
To execute the info endpoint, send a GET request to /info.
Configuration
To configure the info endpoint, supply configuration through endpoints.info
.
endpoints:
info:
enabled: Boolean
sensitive: Boolean
Customization
The info endpoint consists of an info aggregator and any number of info sources. To add an info source, simply create a bean class that implements InfoSource. If your info source needs to retrieve data from Java properties files, you can extend the PropertiesInfoSource interface which provides a helper method for this purpose.
All of the info source beans will be collected together with the info aggregator. To provide your own implementation of the info aggregator, create a class that implements InfoAggregator and register it as a bean. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
The default info aggregator returns map containing the combined properties returned by all the info sources. This map is returned as JSON from the /info endpoint.
Provided Info Sources
Configuration Info Source
The ConfigurationInfoSource will return configuration properties under the info
key. In addition to string, integer and boolean values, more complex properties can be exposed as maps in the JSON output (if the configuration format supports it).
application.groovy
)info.demo.string = "demo string"
info.demo.number = 123
info.demo.map = [key: 'value', other_key: 123]
The above config will result in the following JSON response from the info endpoint:
{
"demo": {
"string": "demo string",
"number": 123,
"map": {
"key": "value",
"other_key": 123
}
}
}
Configuration
The configuration info source can be disabled using the endpoints.info.config.enabled
property.
Git Info Source
If a git.properties
file is available on the classpath, the GitInfoSource will expose the values in that file under the git
key. Generating of a git.properties
file will need to be configured as part of your build. One easy option for Gradle users is the Gradle Git Properties Plugin. Maven users can look at the Maven Git Commit Id Plugin.
Configuration
To specify an alternate path/name of the properties file, you can supply a custom value in the endpoints.info.git.location
property.
The git info source can be disabled using the endpoints.info.git.enabled
property.
Build Info Source
If a META-INF/build-info.properties
file is available on the classpath, the BuildInfoSource will expose the values in that file under the build
key. Generating of a build-info.properties
file will need to be configured as part of your build. One easy option for Gradle users is the Gradle Build Info Plugin. Another option for Maven users is the Spring Boot Maven Plugin
Configuration
To specify an alternate path/name of the properties file, you can supply a custom value in the endpoints.info.build.location
property.
The build info source can be disabled using the endpoints.info.build.enabled
property.
14.2.3 The Health Endpoint
The health endpoint returns information about the "health" of the application. The application health is determined by any number of "health indicators".
To execute the health endpoint, send a GET request to /health.
Configuration
To configure the health endpoint, supply configuration through endpoints.health
.
endpoints:
health:
enabled: Boolean
sensitive: Boolean
details-visible: String (1)
status:
http-mapping: Map<String, HttpStatus>
1 | One of DetailsVisibility |
The details-visible
setting is used to control whether health detail should be exposed to users who are not authenticated.
For example setting:
details-visible
endpoints:
health:
details-visible: ANONYMOUS
Will expose detailed information read from the various health indicators about the health status of the application to anonymous unauthenticated users.
The endpoints.health.status.http-mapping
setting can be used to control what status codes are returned for each health status. The defaults are described in the table below:
Status | HTTP Code |
---|---|
OK (200) |
|
OK (200) |
|
SERVICE_UNAVAILABLE (503) |
You can provide custom mappings in application.yml
:
endpoints:
health:
status:
http-mapping:
DOWN: 200
The above will return OK (200) even when the HealthStatus is DOWN.
Customization
The health endpoint consists of a health aggregator and any number of health indicators. To add a health indicator, simply create a bean class that implements HealthIndicator. A base class AbstractHealthIndicator has been provided for you to extend to make the process easier.
All of the health indicator beans will be collected together with the health aggregator. To provide your own implementation of the health aggregator, create a class that implements HealthAggregator and register it as a bean. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
The default health aggregator returns an overall status that is calculated based on the health statuses of the indicators. A health status consists of several pieces of information.
Name |
The name of the status |
Description |
The description of the status |
Operational |
Whether the functionality the indicator represents is functional |
Severity |
How severe the status is. A higher number is more severe |
The "worst" status will be returned as the overall status. A non operational status will be selected over an operational status. A higher severity will be selected over a lower severity.
Provided Indicators
Disk Space
A health indicator is provided that determines the health of the application based on the amount of free disk space. Configuration for the disk space health indicator can be provided under the endpoints.health.disk-space
key.
endpoints:
health:
disk-space:
enabled: Boolean
path: String #The file path used to determine the disk space
threshold: String | Long #The minimum amount of free space
The threshold can be provided as a string like "10MB" or "200KB", or the number of bytes.
JDBC
The JDBC health indicator determines the health of your application based on the ability to successfully create connections to datasources in the application context. The only configuration option supported is to enable or disable the indicator by the endpoints.health.jdbc.enabled
key.
Discovery Client
If your application is using service discovery, a health indicator will be included to monitor the health of the discovery client. The data returned can include a list of the services available.
14.2.4 The Metrics Endpoint
Micronaut includes the ability to expose Metrics via integration with Micrometer.
Using the CLI
If you are creating your project using the Micronaut CLI, supply one of the micrometer features to enable metrics and preconfigure the selected registery in your project. For example: $ mn create-app my-app --features micrometer-atlas |
The metrics endpoint returns information about the "metrics" of the application. To execute the metrics endpoint, send a GET request to /metrics
. This will return a list of availble metric names.
You can get specific metrics by using /metrics/[name]
such as /metrics/jvm.memory.used
.
See the documentation for Micronaut Micrometer for a list of registries and information on how to configure, expose and customize metrics output.
14.2.5 The Refresh Endpoint
The refresh endpoint will refresh the application state, causing all Refreshable beans in the context to be destroyed and reinstantiated upon further requests. This is accomplished by publishing a RefreshEvent in the Application Context.
To execute the refresh endpoint, send a POST request to /refresh.
$ curl -X POST http://localhost:8080/refresh
When executed without a body, the endpoint will first refresh the Environment and perform a diff to detect any changes, and will then only perform the refresh if changes are detected. To skip this check and refresh all @Refreshable
beans regardless of environment changes (e.g., to force refresh of cached responses from third-party services), you can supply a force
parameter in the POST request body.
$ curl -X POST http://localhost:8080/refresh -H 'Content-Type: application/json' -d '{"force": true}'
Configuration
To configure the refresh endpoint, supply configuration through endpoints.refresh
.
endpoints:
refresh:
enabled: Boolean
sensitive: Boolean
14.2.6 The Routes Endpoint
The routes endpoint returns information about URIs available to be called for your application. By default the data returned includes the URI, allowed method, content types produced, and information about the method that would be executed.
To execute the routes endpoint, send a GET request to /routes.
Configuration
To configure the routes endpoint, supply configuration through endpoints.routes
.
endpoints:
routes:
enabled: Boolean
sensitive: Boolean
Customization
The routes endpoint is composed of a route data collector and a route data implementation. The route data collector (RouteDataCollector) is responsible for returning a publisher that will return the data used in the response. The route data (RouteData) is responsible for returning data about an individual route.
To override the default behavior for either of the helper classes, either extend the default implementations (RxJavaRouteDataCollector, DefaultRouteData), or implement the relevant interface directly. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
14.2.7 The Loggers Endpoint
The loggers endpoint returns information about the available loggers in the application and permits configuring the their log level.
The loggers endpoint is disabled by default and needs to be explicitly enabled with the setting endpoints.loggers.enabled=true .
|
To get a collection of all loggers by name with their configured and effective log levels, send a GET request to /loggers. This will also provide a list of the available log levels.
$ curl http://localhost:8080/loggers
{
"levels": [
"ALL", "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF", "NOT_SPECIFIED"
],
"loggers": {
"ROOT": {
"configuredLevel": "INFO",
"effectiveLevel": "INFO"
},
"io": {
"configuredLevel": "NOT_SPECIFIED",
"effectiveLevel": "INFO"
},
"io.micronaut": {
"configuredLevel": "NOT_SPECIFIED",
"effectiveLevel": "INFO"
},
// etc...
}
}
To get the log levels of a particular logger, include the logger name in your GET request. For example, to access the log levels of the logger 'io.micronaut.http':
$ curl http://localhost:8080/loggers/io.micronaut.http
{
"configuredLevel": "NOT_SPECIFIED",
"effectiveLevel": "INFO"
}
If the named logger does not exist, it will be created with an unspecified (i.e. NOT_SPECIFIED
)
configured log level. (It’s effective log level will usually be that of the root logger.)
To update the log level of a single logger, send a POST request to the named logger URL and include a body providing the log level to configure.
$ curl -i -X POST \
-H "Content-Type: application/json" \
-d '{ "configuredLevel": "ERROR" }' \
http://localhost:8080/loggers/ROOT
HTTP/1.1 200 OK
$ curl http://localhost:8080/loggers/ROOT
{
"configuredLevel": "ERROR",
"effectiveLevel": "ERROR"
}
Configuration
To configure the loggers endpoint, supply configuration through endpoints.loggers
.
endpoints:
loggers:
enabled: Boolean
sensitive: Boolean
By default the endpoint doesn’t allow to change the log level by unauthorized users (even if sensitive is set to
false ). To allow it is necessary set endpoints.loggers.write-sensitive to false .
|
Customization
The loggers endpoint is composed of two customizable parts: a loggers manager and a logging system.
The loggers manager (LoggersManager) is responsible for returning a Publisher that will return data collected and transformed for the response, and it is also responsible for updating a logger with a new log level.
To override the default behavior for the loggers manager, either extend the default implementation (DefaultLoggersManager) or implement the LoggersManager interface directly. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
The logging system (LoggingSystem) is responsible for processing requests from the loggers manager against a particular logging library (e.g. logback, log4j, etc.)
The current default implementation for the logging system is LogbackLoggingSystem, which works with the logback logging framework. Additional logging systems will be implemented in future revisions of Micronaut. For custom logging system behavior, implement the LoggingSystem interface directly. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
@Singleton
@Replaces(LogbackLoggingSystem.class)
public class CustomLoggingSystem implements LoggingSystem {
// ...
}
14.2.8 The Caches Endpoint
The caches endpoint returns information about the caches in the application and permits invalidating them.
To get a collection of all caches by name with their configuration, send a GET request to /caches.
$ curl http://localhost:8080/caches
To get the configuration of a particular cache, include the cache name in your GET request. For example, to access the configuration of the cache 'book-cache':
$ curl http://localhost:8080/caches/book-cache
To invalidate all cached values within a single cache, send a DELETE request to the named cache URL.
$ curl -X DELETE http://localhost:8080/caches/book-cache
To invalidate all caches, send a DELETE request to /caches.
$ curl -X DELETE http://localhost:8080/caches
Configuration
To configure the caches endpoint, supply configuration through endpoints.caches
.
endpoints:
caches:
enabled: Boolean
sensitive: Boolean
Customization
The caches endpoint is composed of a cache data collector and a cache data implementation. The cache data collector (CacheDataCollector) is responsible for returning a publisher that will return the data used in the response. The cache data (CacheData) is responsible for returning data about an individual cache.
To override the default behavior for either of the helper classes, either extend the default implementations (RxJavaRouteDataCollector, DefaultRouteData), or implement the relevant interface directly. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
14.2.9 The Server Stop Endpoint
The stop endpoint shuts down the application server.
To execute the stop endpoint, send a POST request to /stop.
Configuration
To configure the stop endpoint, supply configuration through endpoints.stop
.
endpoints:
stop:
enabled: Boolean
sensitive: Boolean
By default, the stop endpoint is disabled and needs to be explicitly enabled to be used. |
14.2.10 The Environment Endpoint
The environment endpoint returns information about the Environment and its PropertySources.
Properties that may contain sensitive data will be masked. |
Configuration
To configure the environment endpoint, supply configuration through endpoints.env
.
endpoints:
env:
enabled: Boolean # default: true
sensitive: Boolean # default: true
Getting information about the environment
To execute the endpoint, send a GET
request to /env
.
Getting information about a particular PropertySource
To execute the endpoint, send a GET
request to /env/{propertySourceName}
.
15 Security
Micronaut has a full featured security solution for all of the common security patterns.
See the documentation for Micronaut Security for more information on how to secure your applications.
16 Multi-Tenancy
Multi-Tenancy, as it relates to software development, is when a single instance of an application is used to service multiple clients (tenants) in a way that each tenant’s data is isolated from the other.
To use the Micronaut’s multitenancy capabilities you must have the multitenancy
dependency on your classpath.
implementation("io.micronaut:micronaut-multitenancy")
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-multitenancy</artifactId>
</dependency>
A common requirement for supporting Multi-tenancy is the ability to resolve the current tenant. Micronaut ships with the following built-in TenantResolvers:
name |
description |
Resolves the current tenant from an HTTP cookie. See CookieTenantResolver Configuration Properties. |
|
Resolves against a fixed tenant id. See FixTenantResolver Configuration Properties. |
|
Resolves the current tenant from the request HTTP Header. See FixTenantResolver Configuration Properties. |
|
Resolves the current tenant from the authenticated username. See PrincipalTenantResolver Configuration Properties. |
|
Resolves the current tenant from the HTTP session. See SessionTenantResolver Configuration Properties. |
|
Resolves the tenant id from the subdomain. See SubdomainTenantResolver Configuration Properties. |
|
Resolves the tenant id from a system property. See SystemPropertyTenantResolver Configuration Properties. |
Micronaut supports tenant propagation. As an example, take the following scenario:
You want incoming requests to the gateway
microservice to resolve the tenant id via subdomain. However, you want
your requests to other internal microservices to include the tenant Id
as an HTTP Header.
Your configuration in the gateway
microservice will look like:
micronaut:
multitenancy:
propagation:
enabled: true
service-id-regex: 'catalogue'
tenantresolver:
subdomain:
enabled: true
tenantwriter:
httpheader:
enabled: true
In the catalogue
microservice the configuration will look like:
micronaut:
multitenancy:
tenantresolver:
httpheader:
enabled: true
To propagate the tenant you will need to write the resolved tenant ID to the outgoing requests.
Currently, Micronaut ships with two built-in implementations for TenantWriter:
name |
description |
Writes the current tenant to a Cookie in your outgoing requests. See CookieTenantWriter Configuration Properties. |
|
Writes the current tenant to a HTTP Header. See HttpHeaderTenantWriter Configuration Properties. |
16.1 Multi-Tenancy GORM
GORM supports Multi-tenancy and integrates with Micronaut.
To use Micronaut and GORM multitenancy capabilities you must have the multitenancy-gorm
dependency on your classpath. For example in build.gradle
:
compile "io.micronaut.configuration:micronaut-multitenancy-gorm"
GORM is a powerful Groovy-based data access toolkit for the JVM with implementations several data access technologies (Hibernate, Neo4j, MongoDB, GraphQL …).
GORM supports the following different multitenancy modes:
-
DATABASE
- A separate database with a separate connection pool is used to store each tenants data. -
SCHEMA
- The same database, but different schemas are used to store each tenants data. -
DISCRIMINATOR
- The same database is used with a discriminator used to partition and isolate data.
In order to use GORM - Multitenancy you will need to configure the following properties: grails.gorm.multiTenancy.mode
and grails.gorm.multiTenancy.tenantResolverClass
.
Micronaut support for Multi-tenancy integrates with GORM.
The following table contains all of the TenantResolver implementations that ship with `multitenancy-gorm
module and are usable out of the box.
name |
description |
Resolves the current tenant from an HTTP cookie. |
|
Resolves against a fixed tenant id |
|
Resolves the current tenant from the request HTTP Header. |
|
Resolves the current tenant from the authenticated username. |
|
Resolves the current tenant from the HTTP session. |
|
Resolves the tenant id from the subdomain. |
|
Resolves the tenant id from a system property. |
You will need to add something like the following snippet to your app configuration:
grails:
gorm:
multiTenancy:
mode: DISCRIMINATOR
tenantResolverClass: 'io.micronaut.multitenancy.gorm.PrincipalTenantResolver'
Please, read GORM Multi-tenancy documentation to learn more.
17 Micronaut CLI
The Micronaut CLI is the recommended way to create new Micronaut projects. The CLI includes commands for generating specific categories of projects, allowing you to choose between build tools, test frameworks, and even pick the language you wish to use in your application. The CLI also provides commands for generating artifacts such as controllers, client interfaces, and serverless functions.
We have a website that can be used to generate projects instead of the CLI. Check out Micronaut Launch to get started! |
When Micronaut is installed on your computer, you can call the CLI with the mn
command.
$ mn create-app my-app
A Micronaut CLI project can be identified by the micronaut-cli.yml
file, which will be included at the root of the project (if it was generated via the CLI). This file will include the project’s profile, default package, and other variables. The project’s default package is evaluated based on the project name.
$ mn create-app my-demo-app
Will result in the default package being my.demo.app
.
You can supply your own default package when creating the application by prefixing the application name with the package:
$ mn create-app example.my-demo-app
Will result in the default package being example
.
Interactive Mode
If you run mn
without any arguments, the Micronaut CLI will launch in interactive mode. This is a shell-like mode which allows you to run multiple CLI commands without re-initializing the CLI runtime, and is especially suitable when you are making use of code-generation commands (such as create-controller
), creating multiple projects, or simply exploring the features included in the CLI. Tab-completion is enabled in the CLI, enabling you to hit the TAB
key to see possible options for a given command or flag.
$ mn
| Starting interactive mode...
| Enter a command name to run. Use TAB for completion:
mn>
Help and Info
General usage information can be viewed using the help
flag on a command.
mn> create-app -h
Usage: mn create-app [-hivVx] [--list-features] [-b=BUILD-TOOL] [--jdk=<javaVersion>] [-l=LANG]
[-t=TEST] [-f=FEATURE[,FEATURE...]]... [NAME]
Creates an application
[NAME] The name of the application to create.
-b, --build=BUILD-TOOL Which build tool to configure. Possible values: gradle, maven.
-f, --features=FEATURE[,FEATURE...]
-h, --help Show this help message and exit.
-i, --inplace Create a service using the current directory
--jdk, --java-version=<javaVersion>
The JDK version the project should target
-l, --lang=LANG Which language to use. Possible values: java, groovy, kotlin.
--list-features Output the available features and their descriptions
-t, --test=TEST Which test framework to use. Possible values: junit, spock, kotlintest.
A list of available features can be viewed using the --list-features
flag on any of the create commands.
mn> create-app --list-features
Available Features
(+) denotes the feature is included by default
Name Description
------------------------------- ---------------
Cache
cache-caffeine Adds support for cache using Caffeine (https://github.com/ben-manes/caffeine)
cache-ehcache Adds support for cache using EHCache (https://www.ehcache.org/)
cache-hazelcast Adds support for cache using Hazelcast (https://hazelcast.org/)
cache-infinispan Adds support for cache using Infinispan (https://infinispan.org/)
17.1 Creating a Project
Creating a project is the primary usage of the CLI. There primary command for creating a new project is create-app
. That will create a standard server application that communicates over HTTP. For other types of applications, see the documentation below.
Command | Description | Options | Example |
---|---|---|---|
|
Creates a basic Micronaut application. |
|
|
|
Creates a command-line Micronaut application. |
|
|
|
Creates a Micronaut serverless function, using AWS by default. |
|
|
|
Creates a Micronaut application that only communicates via a messaging protocol. Uses Kafka by default but can be switched to RabbitMQ with |
|
|
|
Creates a Micronaut application that uses gRPC. |
|
|
Create Command Flags
The create-* commands will generate a basic Micronaut project, with optional flags to specify features, language, test framework, and build tool. All projects except functions will include a default Application
class for starting the application.
Flag | Description | Example |
---|---|---|
|
Language to use for the project (one of |
|
|
Test framework to use for the project (one of |
|
|
Build tool (one of |
|
|
Features to use for the project, comma-separated |
or
|
|
If present, generates the project in the current directory (project name is optional if this flag is set) |
|
Once created, the application can be started using the Application
class, or the appropriate build tool task.
$ ./gradlew run
$ ./mvnw mn:run
Language/Test Features
By default, the create commands will generate a Java application, with JUnit configured as the test framework. All of the options chosen and features applied are stored as properties in the micronaut-cli.yml
file, as shown below:
applicationType: default
defaultPackage: com.example
testFramework: junit
sourceLanguage: java
buildTool: gradle
features: [annotation-api, app-name, application, gradle, http-client, java, junit, logback, netty-server, shade, yaml]
Some commands rely on the data in this file in order to determine if they should be executable. For example, the create-kafka-listener
command requires kafka
to be one of the features in the list.
The values in micronaut-cli.yml are used by the CLI for code generation purposes. After a project has been generated, you can edit these values to change the project defaults, however you will still need to supply the required dependencies and/or configuration in order to use your chosen language/framework. E.g, you could edit the testFramework property to spock to cause the CLI to generate Spock tests when running commands (such as create-controller ), but you will still need to add the Spock dependency to your project.
|
Groovy
To create an app with Groovy support (which comes with Spock by default), supply the appropriate language via the lang
flag:
$ mn create-app my-groovy-app --lang groovy
This will include the Groovy & Spock dependencies in your project, and write the appropriates values in micronaut-cli.yml
.
Kotlin
To create an app with Kotlin support (which comes with Kotlintest by default), supply the appropriate language via the lang
flag:
$ mn create-app my-kotlin-app --lang kotlin
This will include the Kotlin & Kotlintest dependencies in your project, and write the appropriates values in micronaut-cli.yml
.
Build Tool
By default create-app
will create a Gradle project, with a build.gradle
file at the root of the project directory. To create an app using the Maven build tool, supply the appropriate option via the build
flag:
$ mn create-app my-maven-app --build maven
Create-Cli-App
The create-cli-app
command will generate a Micronaut command line application project,
with optional flags to specify language, test framework, features, profile, and build tool.
By default the project will have the picocli
feature to support command line option parsing.
The project will include a *Command
class (based on the project name - e.g., hello-world
will generate HelloWorldCommand
),
and an associated test which will instantiate the command and verify that it can parse command line options.
Once created, the application can be started using the *Command
class, or the appropriate build tool task.
$ ./gradlew run
$ ./mvnw mn:run
Create Function App
The create-function-app
command will generate a Micronaut function project, optimized for serverless environments, with optional flags to specify language, test framework, features and build tool. The project will include a *Function
class (based on the project name - e.g., hello-world
will generate HelloWorldFunction
), and an associated test which will instantiate the function and verify that it can receive requests.
Currently AWS Lambda, Micronaut Azure, and Google Cloud are the supported cloud providers for Micronaut functions. To use other providers, add one in the features: --features azure-function or --features google-cloud-function .
|
Contribute
The CLI’s source code is at https://github.com/micronaut-projects/micronaut-starter. Information about how to contribute and other resources are there.
17.2 Profiles
Profiles are project templates, consisting of a "skeleton" project structure with default configuration, build dependencies and other assets, along with a set of commands for generating application-appropriate artifacts (such as controllers, client interfaces, etc).
Profiles can inherit from other profiles, augmenting/overriding defaults set in their parent. All profiles inherit from the base
profile, which provides the bare minimum required to set up a Micronaut application.
Many Micronaut apps will use the service
profile, which augments the base
profile to add HTTP client/server libraries, create-controller
and create-client
commands, and other features that are appropriate for web service applications. This is the default profile used when running the create-app
command.
Other Micronaut apps will be better served by the cli
profile, which adds the create-command
command and the picocli library for parsing command line input. This is the default profile used when running the create-cli-app
command.
You can view all of the built-in profiles using the CLI command list-profiles
.
Profiles can be chosen using the profile
flag on the create-app
, create-cli-app
, and create-federation
commands.
$ mn create-app my-project --profile rabbitmq
17.2.1 Comparing Versions
The easiest way to see version dependency updates and other changes for a new version of Micronaut, is to produce one clean application using the older and one using the newer version of the mn
CLI, and then comparing those directories.
17.3 Features
Features consist of additional dependencies and configuration to enable specific functionality in your application. The Micronaut profiles define a large number of features, including features for many of the configurations provided by Micronaut, such as the Data Access Configurations
$ mn create-app my-demo-app --features mongo-reactive
This will add the necessary dependencies and configuration for the MongoDB Reactive Driver in your application. You can view all the available features using the profile-info
command.
$ mn profile-info service
17.4 Commands
Profiles can include commands for generating common code artifacts. Not all commands are supported by all profiles; the available commands for a given profile can be viewed using the profile-info
command.
$ mn profile-info service
Profile: service
------------------
The service profile
Provided Commands:
--------------------
create-bean Creates a singleton bean
create-client Creates a client interface
create-controller Creates a controller and associated test
create-job Creates a job with scheduled method
create-test Creates a simple test for the project's testing framework
create-websocket-client Creates a Websocket client
create-websocket-server Creates a Websocket server
help Prints help information for a specific command
Provided Features:
------------------
...
All of the code-generation commands will honor the values written in micronaut-cli.yml
. For example, assume the following micronaut-cli.yml
file.
profile: service
defaultPackage: example
---
testFramework: spock
sourceLanguage: java
With the above settings, the create-controller
command will (by default) generate Java controllers with an associated Spock test, under the example
package. Commands accept arguments and these defaults can be overriden on a per-command basis.
Base Profile Commands
Commands in the base profile are inherited by all other profiles and are always available.
Create-Bean
Flag | Description | Example |
---|---|---|
|
The language used for the bean class |
|
|
Whether to overwrite existing files |
|
The create-bean
command generates a simple Singleton class. It does not create an associated test.
$ mn create-bean EmailService
| Rendered template Bean.java to destination src/main/java/example/EmailService.java
Create-Job
Flag | Description | Example |
---|---|---|
|
The language used for the job class |
|
|
Whether to overwrite existing files |
|
The create-job
command generates a simple Scheduled class. It follows a *Job
convention for generating the class name. It does not create an associated test.
$ mn create-job UpdateFeeds --lang groovy
| Rendered template Job.groovy to destination src/main/groovy/example/UpdateFeedsJob.groovy
Service Profile Commands
The service profile includes commands that are dependent upon the HTTP server and client dependencies (which are not included in the base profile).
Create-Controller
Flag | Description | Example |
---|---|---|
|
The language used for the controller |
|
|
Whether to overwrite existing files |
|
The create-controller
command generates a Controller class. It follows a *Controller
convention for generating the class name. It creates an associated test that will run the application and instantiate an HTTP client, which can make requests against the controller.
$ mn create-controller Book
| Rendered template Controller.java to destination src/main/java/example/BookController.java
| Rendered template ControllerTest.java to destination src/test/java/example/BookControllerTest.java
Create-Client
Flag | Description | Example |
---|---|---|
|
The language used for the client |
|
|
Whether to overwrite existing files |
|
The create-client
command generates a simple Client interface. It follows a *Client
convention for generating the class name. It does not create an associated test.
$ mn create-client Book
| Rendered template Client.java to destination src/main/java/example/BookClient.java
Create-Websocket-Server
Flag | Description | Example |
---|---|---|
|
The language used for the server |
|
|
Whether to overwrite existing files |
|
The create-websocket-server
command generates a simple WebSocketServer class. It follows a *Server
convention for generating the class name. It does not create an associated test.
$ mn create-websocket-server MyChat
| Rendered template WebsocketServer.java to destination src/main/java/example/MyChatServer.java
Create-Websocket-Client
Flag | Description | Example |
---|---|---|
|
The language used for the client |
|
|
Whether to overwrite existing files |
|
The create-websocket-client
command generates a simple WebSocketClient abstract class. It follows a *Client
convention for generating the class name. It does not create an associated test.
$ mn create-websocket-client MyChat
| Rendered template WebsocketClient.java to destination src/main/java/example/MyChatClient.java
CLI Profile Commands
The cli profile lets you generate CLI commands to control your application.
Create-Command
Flag | Description | Example |
---|---|---|
|
The language used for the command |
|
|
Whether to overwrite existing files |
|
The create-command
command generates a standalone application that can be executed as a
picocli Command.
It follows a *Command
convention for generating the class name.
It creates an associated test that will run the application and verify that a command line option was set.
$ mn create-command print
| Rendered template Command.java to destination src/main/java/example/PrintCommand.java
| Rendered template CommandTest.java to destination src/test/java/example/PrintCommandTest.java
17.5 Reloading
Reloading (or "hot-loading") refers to the framework reinitializing classes (and parts of the application) when changes to the source files are detected.
Since Micronaut prioritizes startup time and most Micronaut apps can start up within seconds, a productive workflow can often be had by restarting the application as changes are made; for example, by running a test class within an IDE.
However, if you wish to have your changes automatically reloaded Micronaut does support automatic restart or the use of third-party reloading agents.
17.5.1 Automatic Restart
There are various ways to achieve reloading of classes on the JVM, all have their advantages and disadvantages. The following are possible ways to achieve reloading without restarting the JVM:
-
JVM Agents - A JVM agent like JRebel can be used, however these can produce unusual errors, may not support all JDK versions and can result in cached / stale classes.
-
ClassLoader Reloading - Class Loader based reloading is a popular solution used by most JVM frameworks, however it once again can lead to cached / stale classes, memory leaks and weird errors if the incorrect classloader is used at any moment.
-
Debugger HotSwap - The Java debugger supports hotswapping of changes at runtime, but only supports a few use cases.
Given the problems with existing solutions and a lack of a way built into the JVM to reload changes, the safest and best solution to reloading, and the one recommended by the Micronaut team, is to use automatic application restart via third-party tool.
Micronaut’s startup time is fast and automatic restart leads to a clean slate without potential hard to debug problems cropping up or memory leaks.
Maven Restart
To have automatic application restarts with Maven use the Micronaut Maven plugin (including by default when creating new Maven projects) and run the following command:
$ ./mvnw mn:run
Every time you change a class Micronaut’s plugin will automatically restart the server.
Gradle Restart
For Gradle restart you can create a new application with the file-watch
feature already configured using the CLI with the command mn create-app myapp --features file-watch
This essentially introduces the following configuration to application.yml
:
micronaut:
io:
watch:
paths: src/main
restart: true
By setting micronaut.io.watch.paths
what happens is that Micronaut will fire a FileChangedEvent if any file is changed. Setting micronaut.io.watch.restart
tells Micronaut to stop the server if a file is changed.
The micronaut.io.watch.paths setting can be used for more than just automatic restart, you can use this setting to monitor for file changes within your production application.
|
Once this is in place to have Gradle automatically restart on any change add run the following command:
./gradlew run --continuous
Every time you make a change to class or resources Gradle will recompile and restart the application.
File Watch and Mac OS X
The native JVM implementation of the WatchService
interface for Mac OS X using polling which is slow. To improve file watch performance add the following dependencies to your build if you are using OS X:
configurations {
developmentOnly
}
dependencies {
// Automatically added with the 'file-watch' feature in the CLi
developmentOnly "io.micronaut:micronaut-runtime-osx"
...
developmentOnly "net.java.dev.jna:jna"
developmentOnly "io.methvin:directory-watcher"
}
run.classpath += configurations.developmentOnly
A custom developmentOnly configuration is used to ensure the dependencies don’t go into the production JAR.
|
Or with Maven:
<dependency>
<groupId>io.methvin</groupId>
<artifactId>directory-watcher</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>net.java.dev.jna</groupId>
<artifactId>jna</artifactId>
<scope>provided</scope>
</dependency>
The provided scope is used to ensure the dependencies don’t go into the production JAR.
|
17.5.2 JRebel
JRebel is a proprietary reloading solution that involves an agent library, as well as sophisticated IDE support. The JRebel documentation includes detailed steps for IDE integration and usage of the tool. In this section, we will simply show how to install and configure the agent for Maven and Gradle projects.
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features jrebel |
Install/configure JRebel Agent
The simplest way to install JRebel is to download the "standalone" installation package from the JRebel download page. Unzip the downloaded file to a convenient location within your user’s directory - for example, ~/bin/jrebel
The installation directory will contain a lib
directory containing the agent files. The appropriate agent based on your operating system, following the table below:
OS | Agent |
---|---|
Windows 64-bit JDK |
|
Windows 32-bit JDK |
|
Mac OS X 64-bit JDK |
|
Mac OS X 32-bit JDK |
|
Linux 64-bit JDK |
|
Linux 32-bit JDK |
|
Note the path to the appropriate agent, and add the value to your project build.
Gradle
Add the path to gradle.properties
(create the file if necessary), as the rebelAgent
property.
#Assuming installation path of ~/bin/jrebel/
rebelAgent= -agentpath:~/bin/jrebel/lib/libjrebel64.dylib
Add the appropriate JVM arg to build.gradle
(not necessary if using the CLI feature)
run.dependsOn(generateRebel)
if (project.hasProperty('rebelAgent')) {
run.jvmArgs += rebelAgent
}
You can start the application with ./gradlew run
, and it will include the agent. See the section on Gradle Reloading or IDE Reloading to set up the recompilation.
Maven
Add the path to pom.xml
as a build profile (if using the CLI feature, the profile jrebel
is already provided - simply update the path to the agent JAR).
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<!-- ... -->
<profiles>
<profile>
<id>jrebel</id>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.6.0</version>
<configuration>
<executable>java</executable>
<arguments>
<argument>-noverify</argument>
<argument>-XX:TieredStopAtLevel=1</argument>
<argument>-agentpath:~/bin/jrebel/lib/jrebel6/lib/libjrebel64.dylib</argument>
<argument>-classpath</argument>
<classpath/>
<argument>${exec.mainClass}</argument>
</arguments>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
17.5.3 Recompiling with Gradle
Gradle supports continuous builds, allowing you to run a task that will be rerun every time the source files change. In order to make use of this with a reloading agent (configured as described above), you will run the application normally (with the agent), and then run a recompilation task in a separate terminal with continuous mode enabled.
$ ./gradlew run
$ ./gradlew -t classes
The classes
task will be rerun every time a source file is modified, allowing the reloading agent to pick up the change.
17.5.4 Recompiling with an IDE
If you are using a build tool such as Maven, which does not support automatic recompilation on file changes, you may choose to use your IDE to recompile classes in combination with a reloading agent (as configured in the above sections).
IntelliJ
IntelliJ unfortunately does not have an automatic rebuild option that works for a running application. However, you can trigger a "rebuild" of the project with CMD-F9
(Mac) or CTRL-F9
(Windows).
Eclipse
Under the Project
menu, check the Build Automatically
option. This will trigger a recompilation of the project whenever file changes are saved to disk.
17.6 Proxy Configuration
To configure the CLI to use an HTTP proxy there are two steps. Configuration options can be passed to the cli through the MN_OPTS
environment variable.
For example on *nix systems:
export MN_OPTS="-Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=3128 -Dhttp.proxyUser=test -Dhttp.proxyPassword=test"
The profile dependencies are resolved over HTTPS so the proxy port and host are configured with https.
, however the user and password are specified with http.
.
For Windows systems the environment variable can be configured under My Computer/Advanced/Environment Variables
.
18 Internationalization
18.1 Resource Bundles
A resource bundle is a Java .properties file that contains locale-specific data.
Given this Resource Bundle:
hello=Hello
hello=Hola
You can use ResourceBundleMessageSource, an implementation of MessageSource which eases accessing Resource Bundles and provides cache functionality, to access the previous messages:
ResourceBundleMessageSource ms = new ResourceBundleMessageSource("io.micronaut.docs.i18n.messages");
assertEquals("Hola", ms.getMessage("hello", MessageSource.MessageContext.of(new Locale("es"))).get());
assertEquals("Hello", ms.getMessage("hello", MessageSource.MessageContext.of(Locale.ENGLISH)).get());
given:
ResourceBundleMessageSource ms = new ResourceBundleMessageSource("io.micronaut.docs.i18n.messages")
expect:
ms.getMessage("hello", MessageSource.MessageContext.of(new Locale("es"))).get() == 'Hola'
and:
ms.getMessage("hello", MessageSource.MessageContext.of(Locale.ENGLISH)).get() == 'Hello'
val ms = ResourceBundleMessageSource("io.micronaut.docs.i18n.messages")
Assertions.assertEquals("Hola", ms.getMessage("hello", MessageSource.MessageContext.of(Locale("es"))).get())
Assertions.assertEquals("Hello", ms.getMessage("hello", MessageSource.MessageContext.of(Locale.ENGLISH)).get())
You should not instantiate a new ResourceBundleMessageSource each time you retrieve a message. Instantiate it once, maybe in a javax.inject.Singleton , and reuse it.
|
19 Appendices
19.1 Frequently Asked Questions (FAQ)
The following section covers frequently asked questions that you may find yourself asking while considering to use or using Micronaut.
Does Micronaut modify my byte code?
No. Your classes are your classes. Micronaut does not transform classes or modify the Java byte code you write. Micronaut at compile will produce an additional set of classes that sit next to your original untouched classes.
Why Doesn’t Micronaut use Spring?
When asking why Micronaut doesn’t use Spring, it is typically in reference to the Spring Dependency Injection container.
The Spring ecosystem is very broad and there are many Spring libraries you can use directly in Micronaut without requiring the Spring container. |
The reason Micronaut features its own native JSR-330 compliant dependency injection is that the cost of these features in Spring (and any reflection based DI/AOP container) is too great in terms of memory consumption and the impact on startup time. In order to support dependency injection at runtime Spring:
-
Reads the byte code of every bean it finds at runtime.
-
Synthesizes new annotations for each annotation on each bean method, constructor, field etc. to support Annotation metadata.
-
Builds Reflective Metadata for each bean for every method, constructor, field etc.
The result is a progressive degradation of startup time and memory consumption as your application incorporates more features.
For Microservices and Serverless functions where it is critical that startup time and memory consumption remain low the above behaviour is an undesirable reality of using the Spring container, hence the designers of Micronaut chose not to use Spring.
Does Micronaut support Scala?
Micronaut supports any JVM language that supports the Annotation Processor API. Scala currently does not support this API. However, Groovy also doesn’t support this API and special support has been built that processes the Groovy AST. It may be technically possible to support Scala in the future if a module similar to inject-groovy
is built, but as of this writing Scala is not supported.
Can Micronaut be used for purposes other than Microservices?
Yes. Micronaut is very modular and you can choose to use just the Dependency Injection and AOP implementation if you want simply by including only the micronaut-inject-java
(or micronaut-inject-groovy
for Groovy) dependency in your application.
In fact Micronaut’s support for Serverless Computing uses this exact approach.
What are the advantages of Micronaut’s Dependency Injection and AOP implementation?
Micronaut processes your classes at compile time and produces all metadata at compile time. This eliminates the need for reflection, cached reflective metadata and the requirement to analyze your classes at runtime all of which leads to slower startup performance and greater memory consumption.
In addition, Micronaut will build AOP proxies at compile time that are completely reflection free, which improves performances, reduces stack trace sizes and reduces memory consumption.
Why does Micronaut have its own Consul and Eureka client implementations?
The majority of Consul and Eureka clients that exist are blocking and include a mountain of external dependencies that inflate your JAR files.
Micronaut’s DiscoveryClient uses Micronaut’s native HTTP client thus greatly reducing the need for external dependencies and providing a reactive API onto both discovery servers.
Why am I encountering a NoSuchMethodError occurs loading my beans (Groovy)?
Groovy by default imports the groovy.lang
package which includes a class called @Singleton
that is an AST transformation that makes your class a singleton (adding a private constructor and static retrieval method). This annotation is easily confused with the javax.inject.Singleton
annotation used to define singleton beans in Micronaut. Make sure you are using the correct annotation in your Groovy classes.
Why is it taking much longer than it should to start the application
Micronaut’s startup time is typically very fast. At the application level, however, it is possible to block startup time so if you are seeing slow startup, review if you have any application startup listeners or @Context
scope beans that are slowing startup.
Some network issues can, also cause slow startup. On the Mac for example misconfiguration of your /etc/hosts
file can cause issues. See the following stackoverflow answer.
19.2 Using Snapshots
Micronaut milestone and stable releases are distributed to Bintray.
The following snippet shows how to use Micronaut BUILD-SNAPSHOT
with Gradle. The latest snapshot will always be the next patch version plus 1 with .BUILD-SNAPSHOT
appended. For example if the latest release is "1.0.1", the current snapshot would be "1.0.2.BUILD-SNAPSHOT".
ext {
micronautVersion = '1.0.2.BUILD-SNAPSHOT'
}
repositories {
jcenter() (1)
maven { url "https://oss.jfrog.org/oss-snapshot-local" } (2)
}
dependencyManagement {
imports {
mavenBom "io.micronaut:micronaut-bom:$micronautVersion"
}
}
1 | Micronaut releases are available on JCenter and Maven Central |
2 | Micronaut snapshots are available on JFrog OSS |
In the case of Maven, edit pom.xml
:
<?xml version="1.0" encoding="UTF-8"?>
...
<properties>
<micronaut.version>1.0.2.BUILD-SNAPSHOT</micronaut.version> (1)
...
</properties>
<repositories>
<repository>
<id>jcenter.bintray.com</id>
<url>https://jcenter.bintray.com</url> (2)
</repository>
<repository>
<id>jfrog-snapshots</id>
<url>https://oss.jfrog.org/oss-snapshot-local</url> (3)
</repository>
</repositories>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-bom</artifactId>
<version>${micronaut.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
...
</project>
1 | Set the snapshot version. |
2 | Micronaut releases are available on JCenter and Maven Central |
3 | Micronaut snapshots are available on JFrog OSS Snapshots |
19.3 Common Problems
The following section covers common problems folks stumble upon when using Micronaut.
Dependency injection is not working
The most common reason that Dependency Injection fails to work is when you either don’t have the appropriate annotation processor configured or your IDE is incorrectly configured. See the section on Language Support for how to get setup in your language.
A NoSuchMethodError occurs loading beans (Groovy)
Groovy by default imports the groovy.lang
package which includes a class called @Singleton
that is an AST transformation that makes your class a singleton (adding a private constructor and static retrieval method). This annotation is easily confused with the javax.inject.Singleton
annotation used to define singleton beans in Micronaut. Make sure you are using the correct annotation in your Groovy classes.
It is taking much longer to start my application than it should (*nix OS)
This is likely due to a bug that has to do with executions of java.net.InetAddress.getLocalHost()
causing a long delay. The solution is to edit your /etc/hosts
file to add an entry that contains your host name. To find your host name, simply enter hostname
in the terminal and the value will be output. Then edit your /etc/hosts
file to add or change entries like the example below, replacing <hostname>
with your host name.
127.0.0.1 localhost <hostname> ::1 localhost <hostname>
To learn more about this issue, see this stackoverflow answer
19.4 Breaking Changes
This section will document breaking changes between Micronaut 1.0 and Micronaut 2.0
Thread Pool Selection Now Manual
In Micronaut 1.x, Micronaut would attempt to automatically deduce the thread pool to use based on the return type of the controller method.
This approach caused some confusion and created a false association between reactive types and blocking operations.
Micronaut 2.x now leaves it up to the user to specify the thread pool to schedule operations on, including blocking operations.
If you are upgrading from Micronaut 1.x and have a controller that executes blocking I/O operations (such as JDBC or JPA) it is recommended that you add the @ExecuteOn annotation to execute the blocking operations on a different thread.
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) (1)
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) (1)
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) (1)
fun byName(name: String): Person {
return personService.findByName(name)
}
}
1 | The @ExecuteOn annotation is used to execute the operation on the I/O thread pool |
If you wish to return to the previous behaviour as defined in Micronaut 1.x you can set micronaut.server.thread-selection to AUTO in configuration.
|
Micronaut Cache Removed from Core
The micronaut-runtime
module in Micronaut 1.x included support for caching AOP with the @Cache
annotation. The core caching library and a default implementation based on caffeine were included.
If you are using the caffeine backed cache support, you must add a dependency to continue doing so. Add io.micronaut.cache:micronaut-cache-caffeine
to your build to maintain the existing functionality. The new caffeine cache module no longer uses the internal shadowed caffeine version and declares its own normal dependency on caffeine. You may need to exclude the transitive dependency in order to prevent conflicts with other versions that may be being pulled in.
The management endpoint for caches is no longer included by default in the micronaut-management
module. If you would like to use the caches endpoint, add a dependency on io.micronaut.cache:micronaut-cache-management
.
Support for RxJava 1.x Removed from Core
RxJava 1.x support is no longer included in core by default. You can re-enable support by adding the following dependency:
implementation("io.micronaut.rxjava1:micronaut-rxjava1")
<dependency>
<groupId>io.micronaut.rxjava1</groupId>
<artifactId>micronaut-rxjava1</artifactId>
</dependency>
Support for Reactor Removed from Core
Reactor support is no longer included in core by default. You can re-enable support by adding the following dependency:
implementation("io.micronaut.reactor:micronaut-reactor")
<dependency>
<groupId>io.micronaut.reactor</groupId>
<artifactId>micronaut-reactor</artifactId>
</dependency>
Loggers Endpoint Modifications Now Sensitive
The method on the loggers endpoint to modify logging is now sensitive by default. To revert to the previous behavior, apply the following configuration:
endpoints:
loggers:
write-sensitive: false
Server Side Content Negotiation May Require Test Changes
The new support for server side content negotiation may require changes to tests. For example a test that that makes a call such as:
String result = client.toBlocking().retrieve(
HttpRequest.GET('/test')
.accept("text/plain"), String
)
If the server implementation does not declare the route as @Produces("text/plain")
the request will be rejected with a NOT_ACCEPTABLE
HTTP status code.
Server Filter Ordering
In Micronaut 1.x almost all built in filters operated on order 0, meaning the order was non deterministic. That caused some compatibility issues with the metrics and security modules. A new class has been added ServerFilterPhase that defines the phases of server filtering and sets an order. Many filters have been updated to now have their order reflect the phase they participate in.
Heartbeat Events No Longer Published if no Discovery Clients present
A HeartbeatEvent is no longer published automatically if there are no DiscoveryClient instances present.
This behaviour can be changed by setting micronaut.heartbeat.enabled
to true
explicitly in configuration.
Several TypeConverters Are No Longer Beans
Many TypeConverter
instances that were previously beans are no longer beans and are deprecated including:
These should not be injected directly but instead used through the ConversionService API.
@Executable No Longer Stereotype of @Around
In Micronaut 1.x the @Executable annotation was a meta-annotation specified on the @Around and @Introduction annotations. This meant that an ExecutableMethod reference was generated for every usage of AOP advice which consumed additional memory unnecessarily.
In Micronaut 2.x and above this is no longer the case and if you need an ExecutableMethod generated you should add the @Executable annotation to any custom AOP advice you specify otherwise the method will not be available via the BeanDefinition interface (using for example the getExecutableMethods method).
Spot Bugs Instead of JSR-305 Nullable/NonNull Annotations
The JSR-305 annotations library (com.google.code.findbugs:jsr305
) is no longer a dependency (replaced by spotbugs-annotations
). If you need this library you will need to add it manually.
Events Renamed
The following events were renamed to avoid confusion with other events of similar names:
Old Name | New Name |
---|---|
|
|
|
New Package for Netty Specific Classes of HTTP Client
The HTTP client implementation classes including DefaultHttpClient (considered internal in Micronaut 1.x) have been moved to a sub-package called io.micronaut.http.client.netty
.
HTTP Clients No Longer Named Beans
HTTP clients declared with micronaut.http.services
(see Manual Service Discovery Configuration) are no longer named beans in the context and cannot be injected with javax.inject.Named
, for example given the configuration:
micronaut:
http:
services:
foo:
urls:
- http://foo1
- http://foo2
You can no longer inject an HTTP client with @Named("foo")
:
@Inject
@Named("foo")
RxHttpClient httpClient;
Instead you should always use @Client:
@Inject
@Client("foo")
RxHttpClient httpClient;
Source Retention Annotations No Longer Retained in Runtime Metadata
In Micronaut 1.x annotations specified as source retention were still retained in the AnnotationMetadata interface. As of Micronaut 2.x this is no longer the case with source retention annotations only available within the compiler APIs.
If you wish to retain a particular source level annotation when upgrading you can write an AnnotationTransformer that alters the RetentionPolicy
of the annotation.
Iterable Beans No Longer Have An Implicit Primary
In Micronaut 1.x injecting a single instance of an iterable bean without qualifiers would inject the first bean. An iterable bean is typically anything annotated with @EachProperty
or @EachBean
. Those beans typically are referenced from configuration. The first bean in this context is the first item in configuration that matches what the annotation expects.
For example if you created a bean with @EachProperty("cars")
, then specified the following in your config:
cars:
ford:
cylinders: 8
subaru:
cylinders: 4
Requesting a single instance of that bean would result in the "ford" instance being injected. Because that behavior is surprising and inconsistent with other types of beans, that is no longer the case and a NonUniqueBeanException
will be thrown.
This change does not apply to an explicit primary defined in the annotation (@EachProperty(value = "cars", primary = "ford") ), nor requesting the instance by a qualifier (@Named("ford") CarConfig carConfig ).
|
No Longer Possible to Return Null to Disable a Bean
It is no longer possible to return null
from a @Factory bean method to disable the bean. You should now throw DisabledBeanException instead.
Invalid Configuration File Locations
Specifying a file with micronaut.config.files
, either through the system property or environment variable, that does not exist or cannot be read will now result in the application failing to startup. In previous versions of Micronaut a warning would be logged and the file would be ignored.
PropertySourceLoader Changes
Some default interface methods are no longer default and require implementation.
Deprecation Removal
Most if not all deprecated classes and methods have been removed.
Map Property Binding
In Micronaut 1.x java.util.Map
properties being bound from config were inconsistently bound as either a nested or flat. Now maps are bound as nested by default and the @MapFormat annotation’s default value for transformation
has been changed to reflect that.
For example given the config:
persons:
joe:
age: 30
sally:
age: 25
A map property injected via @Property(name ="persons")
may have been injected flat or nested depending on a couple factors.
{"joe.age": 30, "sally.age": 25}
{"joe": {"age": 30}, "sally": {"age": 25}}
To bind to a map with flat keys, add the @MapFormat annotation and set the transformation
member.
GraalVM BOM Entry
The no longer used group for Graal is no longer part of the bom. While upgrading if you depend on Graal you may see Could not find com.oracle.substratevm:svm:.
. To resolve the issue, change the dependency group to org.graalvm.nativeimage
.
@Retryable
and @CircuitBreaker
Exception Handling
@Retryable
and @CircuitBreaker
in previous versions of Micronaut resolved includes
and excludes
explicitly. Any exception thrown had to exactly match one of the exceptions specified. This has been changed to now also include subclasses of the exception types specified.
MessageSource API Changes
The semantics of the getMessage
method have been changed to also interpolate the message with any provided variables. In previous versions of Micronaut, the raw message was returned from the bundle. To support reading the raw message, a new method getRawMessage
has been added.
In addition, escaping of messages with single quotes is now implemented in accordance with the standard Java MessageFormat class. Messages that contain a single quote will now need escaping in order for the quote to output as it did previously. For example:
my.message=We love Micronaut's documentation
Would now be output as We love Micronauts documentation
. To achieve the desired result, escape the single quote with another single quote.
my.message=We love Micronaut''s documentation
This change also applies to messages in custom constraint annotations, which interpolate the message via the message source api. |
Environment Order Bugfix
Environments specified through the application context builder have priority over environments deduced or supplied through the MICRONAUT_ENVIRONMENTS environment variable, or the equivalent system property. A bug in the logic however did not change the order of a specified environment if it previously was found or deduced. This issue manifested itself with @MicronautTest(environments = "test")
. The test
environment is already deduced for tests, so it retained the order of other deduced environments, and was able to be overriden by MICRONAUT_ENVIRONMENTS=dev
. In Micronaut 1.x configuration for dev
would have overridden test
. In Micronaut 2.x test
will override dev
.
Introspections and Inner Classes
A bug in Micronaut 1.x caused bean introspections to be generated for inner classes of classes annotated with @Introspected
. That also applies to classes where @Introspection
is a meta annotation, like @Entity
. This may have an impact for GraalVM users that rely on accesses to those classes without using reflection. For example:
@Entity
public class Pet {
...
private PetType type = PetType.DOG;
// getters & setters
public enum PetType {
DOG,
CAT
}
}
Previously a bean introspection would have been generated for PetType
. That is no longer the case. If the type should be introspected, simply add the annotation.
Executable Methods
A bug in Micronaut 1.x caused bean definitions to be created for classes that only declared executable annotations on one or more methods. Classes with executable methods must now be explicitly declared as a bean with a scope annotation in order for a bean definition to be created.
Super interfaces No Longer Searched for Fallbacks
If the @Fallback annotation is used to specify a fallback for a @Client interface, the super interfaces of the client will no longer be traversed to lookup the fallback to invoke.
In this case it may be necessary to specify the api
member of the @Recoverable annotation to ensure the fallback can be looked up. For example:
api
to recover from@Client("/Books")
@Recoverable(api = BookApi)
interface BookClient extends BookApi {
@Override
Book get(Long id);
}
AWS FunctionClient Moved to AWS Module
The AWS based function client has been made part of the Micronaut AWS project. If you need this functionality add the following dependency:
implementation("io.micronaut.aws:micronaut-function-client-aws")
<dependency>
<groupId>io.micronaut.aws</groupId>
<artifactId>micronaut-function-client-aws</artifactId>
</dependency>
LogLevel Enum Moved to io.micronaut.logging
io.micronaut.management.endpoint.loggers.LogLevel
enum has moved to package io.micronaut.logging