[ + ]

Table of Contents

Micronaut JAX-RS

JAX-RS Support for Micronaut

Version: 4.4.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 Jaxrs 4

Micronaut Jaxrs 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 need Micronaut 1.3 or above then 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>

Then the following compile time dependency:

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

5 Supported API

As of this writing Micronaut JAX-RS supports the annotations and types defined within the jakarta.ws.rs package and the jakarta.ws.rs.core subpackage only.

All interfaces, annotations and types contained within the following packages are not supported:

  • jakarta.ws.rs.client

  • jakarta.ws.rs.container

  • jakarta.ws.rs.ext

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.

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 Repository

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

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