[ + ]

Table of Contents

Micronaut JAX-RS

JAX-RS Support for Micronaut

Version: 4.7.0

1 Introduction

Micronaut JAX-RS adds support for using JAX-RS annotations and types in a Micronaut application with the aim of helping migrate existing JAX-RS applications or support teams who prefer the JAX-RS annotations.

This project is not an implementation of the JAX-RS specification and is designed to allow users familiar with the JAX-RS API to use the most common parts of the API within the context of a Micronaut application.

See the guide for Micronaut JAX-RS to learn more.

2 Breaking Changes

Micronaut JAX-RS 4

Micronaut JAX-RS 4 migrates to Jakarta RESTful Web Services 3.0. Package namespaces are moved from javax.ws.rs to jakarta.ws.rs. Moreover, it uses transitive dependency jakarta.ws.rs:jakarta.ws.rs-api instead of org.jboss.resteasy:jaxrs-api.

As a consequence, annotation mappers found in the io.micronaut.jaxrs.processor package are changed to support jakarta.ws.rs annotations only. Support for the older javax.ws.rs annotations is dropped with this version, and users will need to migrate to the Jakarta versions.

3 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-jaxrs/releases

4 Quick Start

To use this project you to add the following annotation processor to any Micronaut project:

annotationProcessor("io.micronaut.jaxrs:micronaut-jaxrs-processor")
<annotationProcessorPaths>
    <path>
        <groupId>io.micronaut.jaxrs</groupId>
        <artifactId>micronaut-jaxrs-processor</artifactId>
    </path>
</annotationProcessorPaths>

5 Container API

Micronaut JAX-RS supports using JAX-RS annotations to define controllers.

Include the following server dependency:

implementation("io.micronaut.jaxrs:micronaut-jaxrs-server")
<dependency>
    <groupId>io.micronaut.jaxrs</groupId>
    <artifactId>micronaut-jaxrs-server</artifactId>
</dependency>

Supported Annotations

Micronaut JAX-RS works by converting (at compilation time) a JAX-RS annotation definition into the equivalent Micronaut version.

Table 1. Supported JAX-RS Annotations
JAX-RS Annotation Target Annotation Example

@Path

@Controller

@Path("/foo") // on type

@Path

@UriMapping

@Path("/foo") // on method

@HttpMethod

@HttpMethodMapping

@HttpMethod("TRACE")

@GET

@Get

@GET @Path("/foo/bar")

@POST

@Post

@POST @Path("/foo/bar")

@DELETE

@Delete

@DELETE @Path("/foo/bar")

@OPTIONS

@Options

@OPTIONS @Path("/foo/bar")

@HEAD

@Head

@HEAD @Path("/foo/bar")

@Consumes

@Consumes

@Consumes("application/json")

@Produces

@Produces

@Produces("application/json")

@PathParam

@PathVariable

@PathParam("foo")

@CookieParam

@CookieValue

@CookieParam("myCookie")

@HeaderParam

@Header

@HeaderParam("Content-Type")

@QueryParam

@QueryValue

@QueryParam("myParam")

@DefaultValue

@Bindable(defaultValue="..")

@DefaultValue("example")

@Context

No equivalent. Injects a bean in to a parameter.

@Context

Injectable Parameter Types

In addition to the supported JAX-RS annotations you can use the following JAX-RS types as parameter types to resources or client definitions:

You can also use the @Context annotation to inject any bean into a resource type’s method parameter.

Parameter binding to constructor argument of resource types is not supported at this time.

ResourceInfo

ResourceInfo is a JAX-RS context which can be injected to check which resource class and method are about to be invoked. This is supported in the micronaut-jaxrs module via the @RequestScope bean JaxRsResourceInfo.

See the Scope type guide for more information on using RequestScope beans.

Filters

Micronaut JAX-RS supports following JAX-RS container API:

Filters should be defined as beans

Message Body Writers / Readers

Micronaut supports JAX-RS body writers / readers API:

Body handlers should be defined as beans

SecurityContext and Micronaut Security

When injecting the SecurityContext by default the injected instance is not aware of Micronaut Security and methods like isUserInRole always return false.

To integrate the JAX-RS support with Micronaut Security add the following dependency:

implementation("io.micronaut.jaxrs:micronaut-jaxrs-server-security")
<dependency>
    <groupId>io.micronaut.jaxrs</groupId>
    <artifactId>micronaut-jaxrs-server-security</artifactId>
</dependency>

With the above dependency in place the SecurityContext.isUserInRole method will return true if the role is found within Micronaut Security’s Authentication.getRoles() method. See Retrieving the authenticated user for more information.

Supported Return Types

You can also use the following return types from the JAX-RS API in your resource classes:

6 Client API

Micronaut JAX-RS supports Client API jakarta.ws.rs.client.Client created using jakarta.ws.rs.client.ClientBuilder.

Include the following client dependency:

implementation("io.micronaut.jaxrs:micronaut-jaxrs-client")
<dependency>
    <groupId>io.micronaut.jaxrs</groupId>
    <artifactId>micronaut-jaxrs-client</artifactId>
</dependency>

Filters

Micronaut JAX-RS supports following JAX-RS client API:

Filters should be defined as beans.

Message Body Writers / Readers

Micronaut supports JAX-RS body writers / readers API:

7 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-jaxrs