MicroProfile 3.2 and Helidon MP 1.4 — new Maven bundles

The recent 1.4 release of Project Helidon includes support for the new MicroProfile 3.2 release.

The major change in the new MicroProfile release is MicroProfile Metrics 2.2 (which is basically the same as 2.1 but with one incompatible change reverted).

TL;DR — existing Helidon MP apps work with Helidon 1.4

Updating the Helidon version

Your existingpom.xml probably already has a dependency on some Helidon MP bundle. Change the <version> in that dependency to <1.4.0>.

Using the same, earlier MicroProfile release

By simply changing the Helidon version as above, you allow your app to use Helidon 1.4 with whatever earlier MicroProfile release you had been using.

Using MicroProfile 3.2

To use MicroProfile 3.2 in your app remove the MicroProfile release number suffix from your existing bundle dependency:

<dependency>
  <groupId>io.helidon.microprofile.bundles</groupId>
  <artifactId>helidon-microprofile</artifactId>
  <version>1.4.0</version>
</dependency>

There is no Helidon MP bundle artifact with 3.2 in its name. The helidon-microprofile bundle is the MicroProfile 3.2 support in Helidon 1.4.

Looking ahead

You do not have to change anything else, but you might want to make some other changes in your pom.xml file to optimize your app and to prepare for future Helidon releases.

Here’s why.

Moving to a new bundling approach

Background

All Helidon MP releases (including 1.4) have included bundles corresponding to the various MicroProfile releases. For example, in your application’s pom.xml you could include a dependency on io.helidon.microprofile.bundles:helidon-microprofile-2.2 to use the MicroProfile 2.2 API and the Helidon implementation of it. Each numbered bundle contains _all_ of the Helidon MP artifacts for that MicroProfile release.

Technology-focused, not version-focused, bundles

Beginning with Helidon 1.4 we are deprecating those numbered MP bundles. Helidon 1.4 still includes bundles for MP releases up through MP 3.0.¹ But we plan to remove those numbered bundles from releases beyond 1.4.

Instead you will choose one of two Helidon MicroProfile bundles, not related to MicroProfile releases but rather to sets of MicroProfile technologies: a core bundle and a full bundle. In each Helidon release these bundles will support the then-current MicroProfile release. The Helidon release notes always identify which MicroProfile release is supported.

Helidon MP core bundle

The new core bundle includes the bare minimum to run the simplest microservices: the Helidon MP server, JAX-RS, CDI, JSON, and MicroProfile config. Use the core bundle by using this dependency in your application’s pom.xml file:

<dependency>
  <groupId>io.helidon.microprofile.bundles</groupId>
  <artifactId>helidon-microprofile-core</artifactId>
  <version>1.4.0</version>
</dependency>

If your app uses other MicroProfile technologies, add dependencies for those specific Helidon MP modules. For example, to add metrics support beyond what is in core, just add the metrics dependency to the one for the core bundle:²

<dependency>
  <groupId>io.helidon.microprofile.bundles</groupId>
  <artifactId>helidon-microprofile-core</artifactId>
  <version>1.4.0</version>
</dependency>
<dependency>
  <groupId>io.helidon.microprofile.metrics</groupId>
  <artifactId>helidon-microprofile-metrics2</artifactId>
  <version>1.4.0</version>
</dependency>

We expect many developers will start with the core bundle and then add the specific additional dependencies each app requires. This makes very clear exactly what each app depends on and helps minimize its footprint.

Helidon MP full bundle

As an alternative, you can depend on the full bundle which, as with the older-style numbered bundles, includes _all_ the Helidon MP artifacts. You can add this dependency to your pom:

<dependency>
  <groupId>io.helidon.microprofile.bundles</groupId>
  <artifactId>helidon-microprofile</artifactId>
  <version>1.4.0</version>
</dependency>

Note that the artifact ID for the full bundle is just helidon-microprofile — no suffix.

Because the full bundle includes all the Helidon MP artifacts, you will not have to add any other dependencies to use any of the MicroProfile technologies. Although using the full bundle is a little simpler for you as a developer, it does hide exactly what technologies your app actually uses and might result in a bigger Docker image, for example.

How does this help developers?

Under the previous approach, with the numbered artifact IDs for the Helidon MP bundles, developers who wanted to adopt a newer MicroProfile release would have to update their pom.xml files in two ways:

1. the <version> for the Helidon MP bundle (e.g., from 1.3.1 to 1.4.0), and
2. the <artifactId> for the Helidon MP bundle (e.g., from helidon-microprofile-2.2 to helidon-microprofile-3.0).

With Helidon 1.4, and going forward, you will need to update only the Helidon <version> and you will automatically get the APIs and implementations for the corresponding (typically, the then-current) MicroProfile release.

We believe this matches up with how most developers work: when they adopt a new implementation of Helidon they typically also will want to move to the current MicroProfile APIs and technologies.

Any drawbacks?

After Helidon 1.4, to use an older MicroProfile release you must use the corresponding older Helidon release that supports that MicroProfile version. We will not offer a way for you to upgrade Helidon but stay with an older release of MicroProfile.

To the extent that successive MicroProfile releases are backward compatible, applications written to older MicroProfile APIs will continue to work even with newer MP and Helidon releases. But, if and when future MicroProfile releases include incompatible changes, you might need to revise your apps accordingly in order to adopt the latest Helidon releases.

[1] Actually, there is also a bundle for MP 3.1 but don’t use that one because it had to rely on the problematic API change in MP metrics 2.1 mentioned earlier.

[2] By the way, the 2 in the Helidon MP metrics artifact ID is important. Helidon currently supports both MicroProfile Metrics 1 and 2 to ease developers’ transition with the API incompatibilities between those metrics versions.

For Helidon 1.4 be sure to use the metrics2 artifact to bind to the latest metrics API and implementation. In a future major release we plan to retire metrics2 and going forward the metrics artifact will again be the then-current metrics.