Micronaut Framework 3 Upgrade Reference

WebSocket ann:websocket.annotation.OnMessage[] methods can now accept a api:websocket.WebSocketPongMessage[] parameter that will receive a WebSocket pong sent as a response to a ping submitted using the new sendPingAsync method on api:websocket.WebSocketSession[].

It is now possible to send resources, e.g. stylesheets required by a HTML page, to the client alongside the request for the page using the HTTP2 server push protocol. See the HTTP/2 documentation for information on how to use this feature.

You can now specify the Jackson @JsonView annotation on @Body parameters to controller methods.

The WebSocket clients now support the ws/wss protocol. To implement this change, the api:websocket.WebSocketClient[] create methods now take a URI instead of a URL. The URL methods have been deprecated.

Note: Should you be calling WebSocketClient.create(null), the method call is now ambiguous. Insert a cast in that case: WebSocketClient.create((URI) null)

The SSL handshake timeout can now be configured using the micronaut.ssl.handshakeTimeout and micronaut.http.client.ssl.handshakeTimeout configurations for the server and client respectively.

Factory Beans can now create beans that are primitive types or primitive array types.

See the section on Primitive Beans and Arrays in the documentation for more information.

Qualifiers can now be repeatable (an annotation annotated with java.lang.annotation.Repeatable) allowing narrowing bean resolution by a complete or partial match of the qualifiers declared on the injection point.

A new ann:context.annotation.InjectScope[] annotation has been added which destroys any beans with no defined scope and injected into a method or constructor annotated with @Inject after the method or constructor completes.

Further build time metadata optimizations have been added included reducing the number and size of the classes generated to support Bean Introspection and including knowledge of repeatable annotations in generated metadata avoiding further reflective calls and optimizing Micronaut’s memory usage, in particular with GraalVM.

Support for Reactive context propagation has been further improved by inclusion of request context information in the Reactor context and documentation on how to effectively propagate the context across reactive flows when using Kotlin coroutines.

The build-time api:inject.ast.Element[] API has been improved in a number of ways:

HTTP filters now support matching URLs by a regular expression. Set the patternStyle member of the annotation to REGEX and the value will be treated as a regular expression.

The way the server binds to random ports has improved and should result in fewer port binding exceptions in tests.

The ann:core.convert.format.Format[] annotation now supports several new values that can be used in conjunction with the declarative HTTP client to support formatting data in several new ways. See the client parameters documentation for more information.

The api:http.multipart.StreamingFileUpload[] API has been improved to support streaming directly to an output stream. As with the other transferTo methods, the write to the stream is offloaded to the IO pool automatically.

The SSL configuration for the Netty server now responds to refresh events. This allows for swapping out certificates without having to restart the server. See the https documentation for information on how to trigger the refresh.

If you wish to programmatically start additional Netty servers on different ports with potentially different configurations, new APIs have been added to do so including a new api:http.server.netty.NettyEmbeddedServerFactory[] interface.

See the documentation on Starting Secondary Servers for more information.

The JAX-RS module now integrated with Micronaut Security allowing binding of the JAX-RS SecurityContext

Micronaut Kubernetes 3.1 introduces new annotation @Informer. By using the annotation on the ResourceEventHandler the Micronaut will instantiate the SharedInformer from the official Kubernetes Java SDK. Then you only need to take care of handling the changes of the watched Kubernetes resource. See more on Kubernetes Informer.

The Micronaut Oracle Coherence module is now out of preview status and includes broad integration with Oracle Coherence including support for caching, messaging and Micronaut Data.

Micronaut 3.0 introduces a new build time metadata format that is more efficient in terms of startup and code size.

The result is significant improvements to startup and native image sizes when building native images with GraalVM Native Image.

It is recommended that users re-compile their applications and libraries with Micronaut 3.0 to benefit from these changes.

Micronaut has been updated to support the latest GraalVM 21.2 release.

The jakarta.inject annotations are now the default injection annotations for Micronaut 3

Using the ann:context.annotation.Import[] annotation it is now possible to import bean definitions into your application where JSR-330 (either javax.inject or jakarta.inject annotations) are used in an external library.

See the documentation on Bean Import for more information.

api:core.annotation.AnnotationMetadata[] inheritance can now be controlled via Java’s @Inherited annotation. If an annotation is not explicitly annotated with @Inherited it will not be included in the metadata. See the Annotation Inheritance section of the documentation for more information.

Micronaut can now resolve the correct bean to inject based on the generic type arguments specified on the injection point:

snippet::io.micronaut.docs.inject.generics.Vehicle[tags="constructor",indent=0]

For more information see the section on Qualifying by Generic Type Arguments.

You can now use annotation members in qualifiers and specify which members should be excluded with the new ann:context.annotation.NonBinding[] annotation.

For more information see the section on Qualifying By Annotation Members.

You can now limit the exposed types of a bean using the typed member of the ann:context.annotation.Bean[] annotation:

snippet::io.micronaut.docs.inject.typed.V8Engine[tags="class",indent=0]

For more information see the section on Limiting Injectable Types.

Beans defined with the ann:context.annotation.Factory[] annotation can now produce beans from public or package protected fields, for example:

snippet::io.micronaut.docs.factories.VehicleMockSpec[tags="class",indent=0]

For more information see the Bean Factories section of the documentation.

The api:context.BeanProvider[] interface has been enhanced with new methods such as iterator() and stream() as well as methods to check for bean existence and uniqueness.

A new ann:context.annotation.Any[] qualifier has been introduced to allow injecting any available instance into an injection point and can be used in combination with the new BeanProvider interface mentioned above to allow more dynamic behaviour.

snippet::io.micronaut.docs.qualifiers.any.Vehicle[tags="imports,clazz", indent=0, title="Using BeanProvider with Any"]

The annotation can also be used on ann:context.annotation.Factory[] methods to allow customization of how objects are injected via the api:inject.InjectionPoint[] API.

Bean introspections on public or package protected fields are now supported:

snippet::io.micronaut.docs.ioc.beans.User[tags="class", indent=0]

For more information see the "Bean Fields" section of the Bean Introspections documentation.

For the performance reasons it’s advised to inject an instance of ApplicationEventPublisher with a generic type parameter - ApplicationEventPublisher<MyEvent>.

It is now possible to intercept bean construction invocations through the api:aop.ConstructorInterceptor[] interface and ann:aop.AroundConstruct[] annotation.

See the section on Bean Life Cycle Advice for more information.

It is now possible to intercept @PostConstruct and @PreDestroy method invocations through the api:aop.MethodInterceptor[] interface and ann:aop.InterceptorBinding[] annotation.

See the section on Bean Life Cycle Advice for more information.

It is now possible to set a max and a range for random numbers in configuration. For example to set an integer between 0 and 9, ${random.int(10)} can be used as the configuration value. See the documentation under "Using Random Properties" for more information.

Micronaut 3 uses internally Project Reactor instead RxJava 2. Project Reactor allows Micronaut 3 to simplify instrumentation, thanks to Reactor’s Context, simplifies conversion login and eases the integration with R2DBC drivers. We recommend users to migrate to Reactor. However, it is possible to continue to use RxJava. See Reactive Programming section.

The Micrometer module has been upgraded and now supports repeated definitions of the @Timed annotation as well as also supporting the @Counted annotation for counters when you add the micronaut-micrometer-annotation dependency to your annotation processor classpath.

Micronaut’s Oracle Cloud Integration has been updated with support for Cloud Monitoring and Tracing.

The Micronaut Cassandra integration now includes support for GraalVM out of the box.

Possibly the most important change in Micronaut 3.0 is how annotations are inherited from parent classes, methods and interfaces.

Micronaut 2.x did not respect the rules defined in the jdk:java.lang.reflect.AnnotatedElement[], and inherited all annotations from parent interfaces and types regardless of the presence of the jdk:java.lang.annotation.Inherited[] annotation.

With Micronaut 3.x and above only annotations that are explicitly meta-annotated with jdk:java.lang.annotation.Inherited[] are now inherited from parent classes and interfaces. This applies to types in the case where one extends another, and methods in the case where one overrides another.

Many of Micronaut’s core annotations have been annotated with @Inherited, so no change will be required, but some annotations that are either outside Micronaut or defined by user code will need changes to code or the annotation.

In general, behaviour which you wish to override is not inherited by default in Micronaut 3.x and above including Bean Scopes, Bean Qualifiers, Bean Conditions, Validation Rules and so on.

The following table summarizes the core Micronaut annotations and which are inherited and which are not:

When upgrading an application you may need to take action if you implement an interface or subclass a superclass and override a method.

For example the annotations defined in jakarta.validation are not inherited by default, so they must be defined again in any overridden or implemented methods.

This behaviour grants more flexibility if you need to redefine the validation rules. Note that it is still possible to inherit validation rules through meta-annotations. See the section on Annotation Inheritance for more information.

The default value of jackson.always-serialize-errors-as-list is now true. That means by default the Hateoas JSON errors will always be a list. For example:

To revert to the previous behavior where a singular error was populated in the message field instead of including _embedded.errors, set the configuration setting to false.

It is no longer possible to scan the classpath at runtime using the scan method of the api:context.env.Environment[] interface.

This functionality has not been needed for some time as scanning is implemented at build time through Bean Introspections.

Micronaut now provides the jakarta.inject annotations as a transitive dependency instead of the javax.inject annotations. To continue using the old annotations, add the following dependency.

dependency:javax.inject:javax.inject:1[]

Micronaut no longer exports any third party dependency for nullability annotations. Micronaut now provides its own annotations for this purpose (api:core.annotation.Nullable[] and api:core.annotation.NonNull[]) that are used for our APIs. To continue using other nullability annotations, simply add the relevant dependency.

Internally, Micronaut makes use of a third party annotation that may manifest as a warning in your project:

This warning is harmless and can be ignored. To eliminate this warning, add the following dependency to your project’s compile only classpath:

dependency:com.google.code.findbugs:jsr305[gradleScope="compileOnly"]

In Micronaut 2 server filters could have been called multiple times in the case of an exception being thrown, or sometimes not at all if the error resulted before route execution. This also allowed for filters to handle exceptions thrown from routes. Filters have changed in Micronaut 3 to always be called exactly once for each request, under all conditions. Exceptions are no longer propagated to filters and instead the resulting error response is passed through the reactive stream.

In the case of a response being created as a result of an exception, the original cause is now stored as a response attribute (api:http.HttpAttributes#EXCEPTION[]). That attribute can be read by filters to have context for the error HTTP response.

The api:http.filter.OncePerRequestHttpServerFilter[] class is now deprecated and will be removed in the next major release. The api:http.filter.OncePerRequestHttpServerFilter[] stores a request attribute when the filter is executed and some functionality may rely on that attribute existing. The class will still create the attribute but it is recommended to instead create a custom attribute in your filter class and use that instead of the one created by api:http.filter.OncePerRequestHttpServerFilter[].

There is also a minor behavior change in when the response gets written. Any modifications to the response after the underlying onNext call is made will not have any effect as the response has already been written.

Compile time validation of HTTP related classes has been moved to its own module. To continue validating controllers, websocket server classes add http-validation to the annotation processor classpath.

dependency:io.micronaut:micronaut-http-validation[gradleScope="annotationProcessor"]

For many cases, one common one being introspections, getter names like getXForwarded() would result in the bean property being XForwarded. The name will now be xForwarded. This can affect many areas of the framework where names like XForwarded are used.

Previously the default order value for the @Order annotation was the lowest precedence. It is now 0.

Classes, constructors, etc. that have been deprecated in previous versions of Micronaut have been removed.

In several places in Micronaut, it is required to get a map representation of your object. In previous versions, a reflection based strategy was used to retrieve that information if the class was not annotated with @Introspected. That functionality has been removed and it is now required to annotate classes with @Introspected that are being used in this way. Any class may be affected if it is passed as an argument or returned from any controller or client, among other use cases.

Previously the secure configuration for cookies was only respected if the request was determined to be sent over https. Due to a number of factors including proxies, HTTPS requests can be presented to the server as if they are HTTP. In those cases the setting was not having any effect. The setting is now respected regardless of the status of the request. If the setting is not set, cookies will be secure if the request is determined to be HTTPS.

Previously if a route could not be satisfied, or an HttpStatusException was thrown, routes for the relevant HTTP status was searched before routes that handled the specific exception. In Micronaut 3 routes that handle the exception will be searched first, then routes that handle the HTTP status.

Status error routes will now default to produce responses with the same HTTP status as specified in the @Error annotation. In previous versions a 200 OK response was created. For example:

The above method will result in a response of HTTP status 415 with a body of "not supported". Previously it would have been a response of HTTP status 200 with a body of "not supported". To specify the desired response status, either annotate the method with @Status or return an HttpResponse.

In Micronaut 2.x it was possible to inject a List<javax.inject.Provider>, although this was undocumented behaviour. In Micronaut 3.x injecting a list of Provider instances is no longer possible and you should instead use the api:context.BeanProvider[] API which provides stream() and iterator() methods to provide the same functionality.

In previous versions of Micronaut it was possible to inject an ExecutorService without any qualifiers and the default Netty event loop group would be injected. Because the event loop should not be used for general purpose use cases, the injection will now fail by default with a non unique bean exception. The injection point should be qualified for which executor service is desired.

It is no longer possible to inject the internal implementation type from beans produced via factories. The type returned from the factory or any of its super types are able to be injected.

For example:

In the above case, if the ExecutorService had been already been retrieved from the context in previous logic, a call to context.getBean(ForkJoinPool.class) would locate the already created bean. This behaviour was inconsistent because if the bean had not yet been created then this lookup would not work. In Micronaut 3 for consistency this is no longer possible.

You can however restore the behaviour by changing the factory to return the implementation type:

In previous versions of Micronaut it was possible to define AOP advice to a factory method that returned a class that featured constructor arguments. This could lead to undefined behaviour since the argument of the generated proxy which would be dependency injected by the framework may be different from manually constructed proxy target.

The following definition is now invalid in Micronaut 3 and above and will lead to a compilation error:

In Micronaut 2.x if you defined a bean that implemented the javax.inject.Provider interface then the return type of the get method also automatically became a bean.

For example:

In the above example a bean of type A would automatically be exposed by Micronaut. This behaviour is no longer supported and instead the ann:context.annotation.Factory[] annotation should be used to express the same behaviour. For example:

Previous versions of Micronaut specified the ann:context.annotation.Executable[] annotation as a meta-annotation on the ann:http.annotation.Controller[], ann:http.annotation.Filter[] and ann:messaging.annotation.MessageListener[] annotations. This resulted in generating executable method all non-private methods of classes annotated with these annotations.

In Micronaut 3.x and above the ann:context.annotation.Executable[] has been moved to a meta-annotation of ann:http.annotation.HttpMethodMapping[] and ann:messaging.annotation.MessageMapping[] instead to reduce memory consumption and improve efficiency.

If you were relying on the presence of these executable methods you must explicitly annotate methods in your classes with ann:context.annotation.Executable[] to restore this behaviour.

In previous versions of Micronaut annotating a class with @Introspected automatically added it to the GraalVM reflect-config.json file. The original intended usage of the annotation is to generate Bean Introspection Metadata so Micronaut can instantiate the class and call getters and setters without using reflection.

Starting in Micronaut 3.x, the @Introspected annotation doesn’t add the class to the GraalVM reflect-config.json file anymore because, in most cases, it is not necessary. If you need to declare a class to be accessed by reflection, use the @ReflectiveAccess annotation instead.

Another change is regarding the GraalVM resources created at compile-time. In previous versions of Micronaut adding a dependency on io.micronaut:micronaut-graal triggered the generation of the GraalVM resource-config.json that included all the resources in src/main/resources so they were included in the native image. Starting in Micronaut 3.x that is done in either the Gradle or Maven plugins.

The classes in Micronaut Cassandra have been moved from io.micronaut.configuration.cassandra to io.micronaut.cassandra package.

Many of the APIs in the Micronaut Security module have undergone changes. Please see the Micronaut Security documentation for the details.

In the previous version, a missing property wouldn’t set the field value to null as it would for the Java code. In version 3, it should behave in the same way.

Please refactor to use the default value in the @Value annotation: