Micronaut is a modern, JVM-based, full stack microservices framework designed for building modular, easily testable microservice applications.

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 full-featured microservice applications, including:

At the same time Micronaut aims to avoid the downsides of frameworks like Spring, Spring Boot and Grails by providing:

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

Micronaut 1.1.4 includes the following changes:

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.

The best way to install Micronaut on Unix systems is with SDKMAN which greatly simplifies installing and managing multiple Micronaut versions.

Before updating make sure you have latest version of SDKMAN installed. If not, run

In order to install Micronaut, run following command:

You can also specify the version to the sdk install command.

You can find more information about SDKMAN usage on the SDKMAN Docs

You should now be able to run the Micronaut CLI.

Before installing make sure you have latest Homebrew updates.

In order to install Micronaut, run following command:

You can find more information about Homebrew usage on their homepage.

You should now be able to run the Micronaut CLI.

You should now be able to run the Micronaut CLI from the command prompt as follows:

Clone the repository as follows:

cd into the micronaut-core directory and run the following command:

This created the fatJar for use in the CLI.

In your shell profile (~/.bash_profile if you are using the Bash shell), export the MICRONAUT_HOME directory and add the CLI path to your PATH:

Reload your terminal or source your shell profile with source:

You are now be able to run the Micronaut CLI.

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 previous command will create a new Java application in a directory called hello-world featuring a Gradle a build. The application can be run with ./gradlew run:

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:

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:

The application created in the previous section contains a "main class" located in src/main/java that looks like the following:

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.

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.

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:

To test the HelloClient simply retrieve it from the ApplicationContext associated with the server:

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.

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:

The runnable JAR can also easily be packaged within a Docker container or deployed to any Cloud infrastructure that supports runnable JAR files.

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:

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:

The entry point for IoC is then the ApplicationContext interface, which includes a run method. The following example demonstrates using it:

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:

To perform dependency injection simply run the BeanContext using the run() method and lookup a bean using getBean(Class), as per the following example:

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:

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.

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.

In addition to being able to inject beans Micronaut natively supports injecting the following types:

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.

Micronaut features an extensible bean scoping mechanism based on JSR-330. The following default scopes are supported:

Additional scopes can be added by defining a @Singleton bean that implements the CustomScope interface.

Note that with Micronaut when starting a 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.

The Refreshable scope is a custom scope that allows a bean’s state to be refreshed via:

The following example, illustrates the @Refreshable scope behavior.

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:

Scopes can be defined on Meta annotations that you can then apply to your classes. Consider the following example meta annotation:

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:

If you wish for the scope to be overridable you should instead using the DefaultScope annotation on @Driver which allows a default scope to be specified if none other is present:

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:

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.

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:

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.

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:

In the above example an annotation called RequiresJdbc is defined that can then be used on the JdbcBookService instead:

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.

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 the control how beans override each other.

This strategy leads to difficult to debug problems, for example:

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:

You can define a class in src/test/java that replaces this class just for your tests:

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:

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

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.

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

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:

Where this grouping becomes useful is when the bean configuration is made conditional via the @Requires annotation. For example:

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.

INFO: Java and Kotlin also support this functionality via package-info.java. Kotlin does not support a package-info.kt as of version 1.3.

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.

You can hook into the creation of beans using one of the following interfaces:

The BeanInitializedEventListener interface is commonly used in combination with Factory beans. Consider the following example:

The BeanCreatedEventListener interface is more typically used to decorate or enhance a fully initialized bean by creating a proxy for example.

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.

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:

The above example will find all BeanDefinition 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 a 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:

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

The MicronautBeanProcessor class is a BeanFactoryPostProcessor which will add Micronaut beans to a Spring Application Context. An instance of MicronautBeanProcessor should be added to the Spring Application Context. MicronautBeanProcessor requires a constructor parameter which represents a list of the types of Micronaut beans which should be added the Spring Application Context. The processor may be used in any Spring application. As an example, a Grails 3 application could take advantage of MicronautBeanProcessor to add all of the Micronaut HTTP Client beans to the Spring Application Context with something like the folowing:

Multiple types may be specified:

In a non-Grails application something similar may be specified using any of Spring’s bean definition styles:

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.

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.

The application environment is modelled by the Environment interface, which allows specifying one or many unique environment names when creating an ApplicationContext.

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:

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.

Additional PropertySource instances can be added to the environment prior to initializing the ApplicationContext.

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.

You can inject configuration values into beans with Micronaut using the @Value annotation.

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:

Once you have prepared a type safe configuration it can simply be injected into your objects like any other bean:

Configuration values can then be supplied from one of the PropertySource instances. For example:

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.

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:

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:

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:

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:

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:

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:

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:

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:

Micronaut currently has basic support for JMX. At this time, the support is experimental and subject to change. To get started, simply add a dependency on the configuration.

The configuration will create a bean for the management bean server based on configuration.

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:

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

The most common type of advice you may want to apply is "Around" advice, which essentially allows you to decorate a methods behaviour.

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:

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:

To now use this introduction advice in an application you simply annotate your abstract classes or interfaces with @Stub:

All abstract methods will delegate to the StubIntroduction class to be implemented.

The following test demonstrates the behaviour or StubIntroduction:

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.

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:

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:

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.

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 JSR 380, also known as Bean Validation 2.0.

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.

Hibernate Validator project is a reference implementation for JSR 380. Micronaut ships with a built-in configuration to use Hibernate Validator.

To get started, first add the Hibernate Validator configuration to your application:

Then simply add the Validated annotation to any class that requires validation. For example, consider this trivial service that retrieves books by title:

You can verify the behaviour of the class by writing a test. The following test is written in Groovy and Spock:

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.

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.

Like Spring and Grails, Micronaut features a Scheduled annotation that can be used for scheduling background tasks.

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:

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:

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.

A "Hello World" server application can be seen below:

To run the server simply create an Application class with a static void main method. For example:

To run the application from a unit test you can use the EmbeddedServer interface:

By default the server runs on port 8080. However, you can set the server to run on a specific port:

To run on a random port:

The @Controller annotation used in the previous section is one of several annotations that allow you to control the construction of HTTP routes.

The examples in the previous section demonstrates how Micronaut allows you to bind method parameters from URI path variables.

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:

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:

A Micronaut’s controller action responds with a 200 HTTP status code by default.

If the controller’s action responds a HttpResponse object, you can configure the status code for the response object with the status method.

You can also use the @Status annotation.

or even respond a HttpStatus

A Micronaut’s controller action produces application/json by default. Nonetheless you can change the Content-Type of the response with the @Produces annotation.

A Micronaut’s controller action consumes application/json by default. Nonetheless, you can support other Content-Type with the @Consumes annotation.

As mentioned previously, Micronaut is built on Netty which is designed around an Event loop model and non-blocking I/O.

Although it is recommended to following a non-blocking approach, in particular when making remote calls to other microservices, Micronaut acknowledges the fact that in real world scenarios developers encounter situations where the need arises to interface with blocking APIs and in order to facilitate this features blocking operation detection.

If your controller method returns a non-blocking type such as an RxJava Observable or a CompletableFuture then Micronaut will use the Event loop thread to subscribe to the result.

If however you return any other type then Micronaut will execute your @Controller method in a preconfigured I/O thread pool.

This thread pool by default is a caching, unbound thread pool. However, you may wish to configure the nature of the thread pool. 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 connection model):

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:

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.

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:

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.

Micronaut also uses these types to influence which thread pool to execute the method on. If the request is considered non-blocking (because it returns a non-blocking type) then the Netty event loop thread will be used to execute the method.

If the method is considered blocking then the method is executed on the I/O thread pool, which Micronaut creates at startup.

To summarize, the following table illustrates some common response types and their handling:

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.

It is easy to validate incoming data with Micronaut’s controllers with the Validation Advice.

First, add the Hibernate Validator configuration to your application:

We can validate parameters using javax.validation annotations and the Validated annotation at the class level.

The validation behaviour is shown in the following test:

Often, you may want to use POJOs as controller method parameters.

You need to annotate your controller with Validated. Also, you need to annotate the binding POJO with @Valid.

The validation of POJOs is shown in the following test:

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:

Sometimes with distributing applications, bad things happen. Thus having a good way to handle errors is important.