With releases 2.5.5 and 3.1.0, Helidon significantly improves its participation in the OpenAPI ecosystem. You can now take advantage of

• powerful code generation from OpenAPI documents, and
• a convenient user interface for test-driving your application’s operations.

This is in addition to built-in support for OpenAPI which Helidon has included almost from its beginning.

Existing OpenAPI support — a longstanding Helidon feature

Since its early releases, Helidon has had strong support for OpenAPI.

With Helidon SE you can package a static OpenAPI document with your service or even write your own code to build the document at runtime. Helidon then automatically serves the document at /openapi.

Helidon MP (which implements the MicroProfile OpenAPI specification) in addition can automatically derive an OpenAPI document from the JAX-RS endpoints in your application.

New, stronger support in OpenAPITools generators for Helidon

The OpenAPITools generator is an open-source project separate from the Helidon project which generates code for a wide variety of platforms and languages from an OpenAPI document. Starting with release 6.2.1, that project provides much stronger support for generating Helidon SE and MP servers and clients.

The Helidon team has contributed two new generators — java-helidon-server and java-helidon-client — to the OpenAPITools generator project. Each new generator supports two libraries — mp and se — so you can generate code for either flavor of Helidon.

The java-helidon-server generator creates code to implement in a Helidon server the operations declared in an OpenAPI document. The generated code includes skeleton implementations which you then extend with business logic you write yourself. If your OpenAPI document changes, you can regenerate the code without disturbing your customizations.

The java-helidon-client generator creates a library to invoke your operations as implemented in a server. (The server does not have to be generated using the tool; it does need to honor the OpenAPI document you use to generate the client.) Most developers would add a dependency on the generated client library from one or more other projects that need to contact the server.

As a developer, once you have an OpenAPI document which describes your application’s endpoints, you can use the new generators in several ways:

1. Use the OpenAPITools CLI to create an entire new Helidon MP or SE project which contains generated code to implement your operations (for servers) or invoke your operations (for clients).
2. Use the OpenAPITools CLI to update an existing server or client project with revised interfaces or classes that reflect any changes in the OpenAPI document.
3. Invoke the Maven plug-in for the OpenAPITools generator from your project’s pom.xml. Each time you build the project, the plug-in recreates the generated files according to the current version of the OpenAPI document.

Many developers will choose to use the Helidon CLI to create a project, then edit the pom.xml to invoke the OpenAPITools generator Maven plug-in as an automatic part of the build.

To use the generator CLI, first download it using a command similar to this:

curl https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.2.1/openapi-generator-cli-6.2.1.jar \
     -o openapi-generator-cli.jar

Then you can create a Helidon MP project from your OpenAPI document very simply:

mkdir myproject

cd myproject

java -jar ${path-to-generator}/openapi-generator-cli.jar \
  generate \
  --input-spec ${path-to-openapi-document}myAppOpenAPI.yaml \
  --generator-name java-helidon-server \
  --library mp

To create an SE project, change the--library to se. To generate a client, change the --generator-name to java-helidon-client.

The OpenAPITools site describes how to use the tool in general, for all generators and all languages and frameworks. We have added to our own Helidon web site new documentation which explains in detail not only how to use the tool to generate an MP project or an SE project but also how to then work with the generated files to complete your project. We have also added examples which show generated Helidon MP and SE projects along with detailed step-by-step instructions.

Integration with the SmallRye OpenAPI user interface

SmallRye offers an OpenAPI user interface which displays a web page based on your application’s OpenAPI document. Through that UI, users can invoke the operations declared in the document. While not generally suitable for end-users, the OpenAPI UI can be useful for demonstrating and “test driving” your service’s endpoints.

Helidon now includes a new, optional component which plugs the OpenAPI UI into your Helidon SE or MP application very simply. In many cases you can simply add a single runtime dependency to your project:

<dependency>
    <groupId>io.helidon.integrations.openapi-ui</groupId>
    <artifactId>helidon-integrations-openapi-ui</artifactId>
</dependency>

Rebuild and run your project, and then use a browser to access/openapi/ui which launches the UI.

Here is how the UI looks for the Helidon MP QuickStart application:

The screen lists the operations which the MP QuickStart application’s OpenAPI document defines. To run one of the operations:

• Click on the operation.
• Click “Try it out”.
• Fill in any parameters you want to pass to the operation (the first red box in the image below).
• Click “Execute” (red arrow).

The UI sends the request to the operation and displays the response (second red box):

The Helidon documentation contains new sections describing in detail how to add the UI to your MP application and SE application. You can even customize the path where you want the UI to respond.

Next Steps

Take a look at the expanded Helidon documentation describing the new generators and the new UI integration.

• Generating MP applications https://helidon.io/docs/latest/index.html#/mp/openapi/openapi-generator
• Generating SE applications https://helidon.io/docs/latest/index.html#/se/openapi/openapi-generator
• Integrating the OpenAPI UI into MP applications https://helidon.io/docs/latest/index.html#/mp/openapi/openapi-ui
• Integrating the OpenAPI UI into SE applications https://helidon.io/docs/latest/index.html#/se/openapi/openapi-ui

Browse the examples of using the generators:

• Example using the OpenAPI generator for an MP application
  https://github.com/helidon-io/helidon/tree/3.1.0/examples/openapi-tools/quickstart-mp
• Example using the OpenAPI generator for an SE application https://github.com/helidon-io/helidon/tree/3.1.0/examples/openapi-tools/quickstart-se

Then you will be ready to use the generators and the UI in your own projects with your own OpenAPI documents.

Major Improvements with Helidon and OpenAPI was originally published in Helidon on Medium, where people are continuing the conversation by highlighting and responding to this story.

The OpenMetrics (Prometheus) metrics format allows metrics providers like Helidon to add optional strings to the metrics output. These strings describe exemplars — samples that are, in some way, typical of all the samples represented by the metric. In particular, an exemplar string for a metric often identifies a trace for an actual use of a service in the application that triggered an update of that metric.

Beginning with Helidon 2.3.0, you can add exemplars to Helidon OpenMetrics output for histograms, counters, timers, and simple timers by adding a few dependencies to the pom.xml of your Helidon SE or MP application. You do not have to change your application code or your configuration.

In this article, we assume you have an existing Helidon application, such as the Helidon QuickStart application created using the Helidon CLI. You can easily add exemplar support to your application and see it in action:

• Add a few dependencies to your pom.xml.
• Run Zipkin locally.
• Run and access your application.
• Browse the Zipkin traces identified by the new metrics exemplars.

How Helidon implements exemplars

When you enable exemplar support, each time Helidon updates a metric with a data value it also records the trace ID and the current system time for the sample.

Later, when Helidon formats an OpenMetrics (Prometheus) response to a request sent to your application’s/metrics endpoint, it selects one representative sample — one exemplar — for each relevant metric value and adds information about that sample to the output for that metric value. (See the examples below.)

Some metric values, such as min or max, correspond directly to at least one sample and Helidon uses such a sample for the exemplar. Other metric values are aggregates of multiple samples, such as mean. For aggregate metrics, Helidon selects for the exemplar a sample with a value as close as possible to the reported metric value.

In many cases, the exemplar’s value will not be the same as an aggregate metric value. For example, consider a metric that is the mean of samples with values 3, 4, and 8. No sample has a value equal to the mean — 5 — so Helidon would choose as the exemplar for this metric the sample with value 4 because that sample has value closest to the mean.

Adding exemplar support to your application

Update your pom.xml

Add dependencies for exemplar support, tracing support, and Zipkin support:

<dependency>
    <groupId>io.helidon.metrics</groupId>
    <artifactId>helidon-metrics-trace-exemplar</artifactId>
    <scope>runtime</scope>
</dependency>

<dependency>
    <groupId>io.helidon.microprofile.tracing</groupId>
    <artifactId>helidon-microprofile-tracing</artifactId>
    <scope>runtime</scope>
</dependency>

<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-zipkin</artifactId>
    <scope>runtime</scope>
</dependency>

You could add Helidon Jaeger support instead of Zipkin if you prefer.

Start Zipkin

If you do not start Zipkin, your application will still function correctly and Helidon will add exemplars to the metrics output, but Helidon will log a warning message when it cannot connect to the Zipkin server to report the tracing spans (and of course you will be unable to browse the traces in Zipkin).

docker run --name zipkin -d -p 9411:9411 openzipkin/zipkin

Try the revised application

Build and run your application:

mvn package
java -jar target/quickstart-mp.jar

Access some of the application’s services (responses in italics):

curl -X GET http://localhost:8080/greet
{"message":"Hello World!"}

curl -X GET http://localhost:8080/greet/Joe
{"message":"Hello Joe!"}

curl -X PUT -H "Content-Type: application/json" -d '{"greeting" : "Hola"}' http://localhost:8080/greet/greeting

curl -X GET http://localhost:8080/greet/Jose
{"message":"Hola Jose!"}

curl -X GET http://localhost:8080/greet          
{"message":"Hola World!"}

Retrieve metrics

Now, retrieve the metrics and note the exemplar that now appears in the output. Exemplars actually appear as comments at the end of metrics output, as prescribed in the OpenMetrics spec:

curl -s -X GET http://localhost:8080/metrics/vendor
# TYPE vendor_requests_count_total counter
# HELP vendor_requests_count_total Each request (regardless of HTTP method) will increase this counter
vendor_requests_count_total 6 # {trace_id="acc807bee31f8b96"} 1 1619637182.784000
...

Each exemplar shows

• the trace ID,
• the value which that sample contributed to the metric (in this case, the count), and
• the time in epoch seconds when Helidon recorded that sample.

Browse the Zipkin Traces

Access Zipkin in your browser athttp://localhost:9411.

Click RUN QUERYto see the scans your Helidon application reported to Zipkin.

Then click EXPAND ALL to reveal the trace IDs.

Find the trace ID listed in the metrics output. Click SHOW in that row to see the trace details.

Explore the details of the selected trace and its various sub-spans.

Bottom Line

Without changing your application code, and by adding just a few dependencies to your project’s pom.xml, you can enable exemplars in your Helidon application’s metrics output.

You can use the trace IDs from the exemplars in the metrics output to identify representative traces for the metric values and use the trace utility (e.g., Zipkin) to find out details about each of those traces.

More Information

Please read the documentation about metrics exemplar support for Helidon SE and Helidon MP applications for more information.

The OpenMetrics spec describes exemplars.

Using Exemplars in Helidon Metrics was originally published in Helidon on Medium, where people are continuing the conversation by highlighting and responding to this story.

Oracle’s Project Helidon simplifies the job of building Java microservices by, among other things, including support for metrics inspired by the MicroProfile Metrics specification. Helidon metrics include some built-in measurements, but also allow app developers to add their own using the same MicroProfile-inspired API.

Helidon release 2.3.0 adds built-in support for Micrometer metrics. You can use the Micrometer API and annotations to create and update your own application meters and make them available via an endpoint Helidon creates. (This does not replace the built-in Helidon metrics features.)

This article shows how to add Micrometer support and your own Micrometer meters to a Helidon SE or MP app. We’ll assume you have used the Helidon CLI to create an SE or MP quick-start Helidon application.

Adding Micrometer support to your SE app

Modify pom.xml

Add the Helidon Micrometer integration dependency:

<dependency>
    <groupId>io.helidon.integrations.micrometer/groupId>
    <artifactId>helidon-integrations-micrometer</artifactId>
</dependency>

Modify Main.java

The main class sets up the Helidon routing for your endpoints and any built-in Helidon features you choose. Change the main class to create and register MicrometerSupport as well.

import io.helidon.integrations.micrometer.MicrometerSupport;
...
MicrometerSupport micrometerSupport = MicrometerSupport.create();
GreetService greetService = 
        new GreetService(config, micrometerSupport.registry());
...
Routing.builder()
    .register(health)
    .register(metrics)
    .register(micrometerSupport)
    .register("/greet", greetService)
    .build();

The new .register invocation exposes Helidon’s built-in Micrometer support /micrometer endpoint to produce Prometheus-formatted output.

Modify GreetService.java

Revise the GreetService class so its constructor accepts the Micrometer registry as a parameter and GET accesses create and update a Micrometer meter.

Add imports:

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;

Declare Micrometer MeterRegistry and Micrometer Counterfields:

private final MeterRegistry meterRegistry;
private final Counter getCounter;

Change the constructor to accept and save the MeterRegistry parameter and create the counter:

GreetService(Config config, MeterRegistry meterRegistry) {
    this.meterRegistry = meterRegistry;
    getCounter = meterRegistry.counter("greeting.get");
    greeting.set(config.get("app.greeting").asString()
        .orElse("Ciao"));
}

Change theupdate methodto add a request handler for every get HTTP operation. This handler updates the Micrometer Counterbefore passing the request off to the next handler without disturbing the other handlers for the service:

public void update(Routing.Rules rules) {
    rules
        .get((req, resp) -> {
            getCounter.increment();
            req.next();
        })
        .get("/", this::getDefaultMessageHandler)
        .get("/{name}", this::getMessageHandler)
        .put("/greeting", this::updateGreetingHandler);
}

Try it

Build and run the revised application:

mvn package
java -jar target/quickstart-se.jar

Access the new endpoint:

% curl http://localhost:8080/micrometer
# HELP greeting_get_total
# TYPE greeting_get_total counter
greeting_get_total 0.0

Retrieve at least one greeting:

% curl http://localhost:8080/greet
{"message":"Hello World!"}

% curl http://localhost:8080/greet/reader
{"message":"Hello reader!"}

Check the Micrometer output again, noting the change in value:

curl http://localhost:8080/micrometer
# HELP greeting_get_total
# TYPE greeting_get_total counter
greeting_get_total 2.0

Add Micrometer support to your MP app

You can use the Micrometer @Counted and @Timedannotations in your Helidon MP application.

Modify pom.xml

Add the dependency for Helidon Micrometer with CDI support:

<dependency>
    <groupId>io.helidon.integrations.micrometer</groupId>
    <artifactId>helidon-integrations-micrometer-cdi</artifactId>
</dependency>

Add Micrometer annotations to GreetResource.java

We use Micrometer annotations to track (by time and invocation count) all GET accesses and to count separately all requests for personalized greetings.

We will use the same @Timedannotation on two GET methods, so first define constants we can reuse:

private static final String GETS_TIMER_NAME = "allGets";
private static final String GETS_TIMER_DESCR = 
        "Tracks all GET operations";

Add

• Micrometer @Timed annotation to both GET methods, and
• Micrometer @Counted annotation to the personalized GET method:

@GET
@Timed(value = GETS_TIMER_NAME, description = GETS_TIMER_DESCR)
@Produces(MediaType.APPLICATION_JSON)
public JsonObject getDefaultMessage() {
    ...
}
...
@Counted(value = "personalizedGets", 
        description = "Counts personalized GET operations")
@Timed(value = GETS_TIMER_NAME, description = GETS_TIMER_DESCR)
@Path("/{name}")
@GET
@Produces(MediaType.APPLICATION_JSON)
public JsonObject getMessage(@PathParam("name") String name) {
    ...
}

Try it

Build and run the revised application:

mvn package
java -jar target/quickstart-mp.jar

Access the Micrometer endpoint:

curl http://localhost:8080/micrometer
# HELP allGets_seconds_max Tracks all GET operations
# TYPE allGets_seconds_max gauge
allGets_seconds_max 0.0
# HELP allGets_seconds Tracks all GET operations
# TYPE allGets_seconds summary
allGets_seconds_count 0.0
allGets_seconds_sum 0.0
# HELP personalizedGets_total Counts personalized GET operations
# TYPE personalizedGets_total counter
personalizedGets_total 0.0

Retrieve at least one greeting:

% curl http://localhost:8080/greet
{"message":"Hello World!"}

% curl http://localhost:8080/greet/reader
{"message":"Hello reader!"}

Check the Micrometer output again, noting the change in values:

curl http://localhost:8080/micrometer
# HELP allGets_seconds_max Tracks all GET operations
# TYPE allGets_seconds_max gauge
allGets_seconds_max 0.003666501
# HELP allGets_seconds Tracks all GET operations
# TYPE allGets_seconds summary
allGets_seconds_count 2.0
allGets_seconds_sum 0.003923641
# HELP personalizedGets_total Counts personalized GET operation
# TYPE personalizedGets_total counter
personalizedGets_total 1.0

Summary

With just a few changes, you can add Micrometer support for your own metrics to your Helidon SE or MP application and make those metrics accessible at the built-in /micrometer endpoint.

Built-in Helidon metrics continue to be available at the/metricsendpoint.

Go to our documentation site to find out more about Micrometer support in Helidon SE and Helidon MP.

Using Micrometer in Helidon Applications was originally published in Helidon on Medium, where people are continuing the conversation by highlighting and responding to this story.

Beginning with newly-released Helidon 2.0 [1], you can easily add CORS support to your application and to Helidon’s built-in services for health, metrics, and OpenAPI.

A same-origin policy [2], implemented in browsers and other well-behaved web clients, restricts a page or app from one origin — URL scheme, host, and port — from accessing resources from other origins.

But, in certain cases, relaxing that restriction makes sense. Cross-origin resource sharing (CORS) [3] is a standard approach using HTTP headers in which web clients ask for and servers grant (or refuse) controlled access to resources from one origin on behalf of a resource in a different origin.

With the recent release of Helidon 2.0, you can easily add CORS support to the endpoints in your own SE [4] and MP [5] applications as well as the endpoints of built-in Helidon services such as health, metrics, and OpenAPI.

The examples below are inspired by the Helidon greeting example app [6, 7]. We’ll assume that you want to permit resources from http://foo.com and http://there.com to have PUT and DELETE access to your app’s resources while granting simple access — GET, HEAD, etc. — to all other origins.

CORS in Helidon SE

Add this dependency to your pom.xml

<dependency>
  <groupId>io.helidon.webserver</groupId>
  <artifactId>helidon-webserver-cors</artifactId>
</dependency>

Create a CorsSupport instance in your code

Build a CorsSupport object to represent the CORS behavior you want for your app’s resources. You use two CrossOriginConfig objects, one for the PUT and DELETE access and a second for all other access:

CorsSupport corsSupport = CorsSupport.builder()
    .addCrossOriginConfig(CrossOriginConfig.builder()
        .allowOrigins("http://foo.com", "http://there.com")
        .allowMethods("PUT", "DELETE")
        .build())
    .addCrossOriginConfig(CrossOriginConfig.create())
        .build();

Use the CorsSupport instance

Use the instance of CorsSupport in the same register call that sets up routing for your application’s path:

return Routing.builder()
    .register(JsonSupport.create())
    .register(health)                  // Health at "/health"
    .register(metrics)                 // Metrics at "/metrics"
    .register("/greet", corsSupport, greetService)
    .build();

Then rebuild and restart your app. That’s it. See below for some simple ways to see the CORS support in action with your app.

CORS in Helidon MP

Add this dependency to your pom.xml

<dependency>
  <groupId>io.helidon.microprofile</groupId>
  <artifactId>helidon-microprofile-cors</artifactId>
</dependency>

Use the @CrossOrigin annotation

In your JAX-RS resource class, add a no-op method for HTTP OPTIONS requests and annotate it:

@OPTIONS
@CrossOrigin(
    allowMethods = {"PUT", "DELETE"}, 
    allowOrigins = {"http://foo.com", "http://there.com"})
public void optionsForGreeting() {}

Then rebuild and restart your app.

Trying it out (SE and MP)

You can use curl to see Helidon’s CORS support in action for your app’s endpoints. The code snippets below highlight the CORS-related headers.

For “simple” operations — GET, HEAD, etc. — CORS simply adds headers to the normal HTTP request.

curl -i -X GET \
   -H "Origin: http://foo.com" -H "Host: here.com" \
   http://localhost:8080/greet

And to the response.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Thu, 30 Apr 2020 17:25:51 -0500
Vary: Origin
connection: keep-alive
content-length: 27

{"greeting":"Hello World!"}

For so-called “non-simple” operations that can change the application’s server-side state, CORS uses a pre-flight request that lets the server “pre-approve” the desired access as declared by the client. Usually a browser sends pre-flight requests (and checks the responses) invisibly, but the followingcurl command simulates this step:

curl -i -X OPTIONS \
    -H "Access-Control-Request-Method: PUT" \
    -H "Origin: http://foo.com" \
    -H "Host: here.com" \
    http://localhost:8080/greet/greeting

The server indicates that it is OK with the requested cross-origin resource sharing:

HTTP/1.1 200 OK
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Origin: http://foo.com
Date: Thu, 30 Apr 2020 17:30:59 -0500
transfer-encoding: chunked
connection: keep-alive

At this point the client issues the desired PUT request, in our example to change the greeting:

curl -i -X PUT \
    -H "Origin: http://foo.com" \
    -H "Host: here.com" \
    -H "Access-Control-Allow-Methods: PUT" \
    -H "Access-Control-Allow-Origin: http://foo.com" \
    -H "Content-Type: application/json" \
    -d "{ \"greeting\" : \"Cheers\" }" \
    http://localhost:8080/greet/greeting

The server responds normally:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://foo.com
Date: Thu, 30 Apr 2020 17:32:55 -0500
Vary: Origin
connection: keep-alive

Bottom Line

With very little extra code, your Helidon SE or MP application’s endpoints can participate in the CORS protocol. And we’ve only hit the high points here. You can use configuration to simplify your CORS-related changes even more.

Further, you can easily turn on and control CORS for Helidon’s built-in services that add endpoints to your application: health, metrics, and OpenAPI.

For complete information, please refer to the documentation ([4], [5]).

References

[1] https://helidon.io
[2] https://www.w3.org/Security/wiki/Same_Origin_Policy
[3] https://www.w3.org/TR/cors/
[4] https://helidon.io/docs/latest/#/se/cors/01_introduction
[5] https://helidon.io/docs/latest/#/mp/cors/01_introduction
[6] https://github.com/oracle/helidon/tree/latest/examples/cors
[7] https://github.com/oracle/helidon/tree/latest/examples/microprofile/cors

Helidon 2.0 and CORS was originally published in Helidon on Medium, where people are continuing the conversation by highlighting and responding to this story.

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.

MicroProfile 3.2 and Helidon MP 1.4 — new maven bundles was originally published in Helidon on Medium, where people are continuing the conversation by highlighting and responding to this story.

Helidon 1.3 has been released, and it includes support for MicroProfile 3.0. Metrics 2.0 is part of that MicroProfile release.

In an earlier article, Santiago has described some of the backward-incompatible changes from MP Metrics 1.1 to 2.0, and how Helidon 1.3 can help insulate you as a developer from those changes if you want.

This post talks about registering, referencing, and reusing metrics. Notably, one aspect of metric reusability has changed from MP Metrics 1.1 to 2.0 and we’ll get to that. There is also some ambiguity in the spec about reusability; this article describes how Helidon handles it.

Registering metrics

Think of registering a metric as recording a place in your app that updates that metric.

This code registers a meter by annotating a JAX-RS endpoint:

As specified by the MP metric naming convention, this metric has the name com.mycorp.myapp.MyEndpoints.greetings (package plus class plus method).

The system registers this meter for you in the application registry and automatically updates the meter as this greet method is invoked.

Or, you can register a metric explicitly in your application code. Here is one way:

Your code needs to declare the meter, instantiate it, register it, and update it. Most developers find using the annotations more convenient.

Referencing (referring to) metrics

In this article, referencing a metric means “get if present, register if absent.” That is, if the metric has been previously registered then get a reference to it; otherwise, register the metric and use a reference to that newly-created one.

You will not find the term “referencing” or “referring to” metrics in the MP Metrics spec. I think it’s helpful to distinguish referencing from registering metrics, because some additional metrics annotations and APIs we are about to look at behave differently from the ones we saw earlier which actually do register a metric.

Here are three ways to reference a metric. There are more variations but these give us plenty to talk about:

1. using @Inject on a Meter field: (both of these @Injects are equivalent)

2. programmatically, by metric name:

3. programmatically, by metadata:

In these three examples, the system cannot automatically update the metric because it does not know what you want to measure with the meter. You would need to write your own code to do that.

Taken by themselves, each of these examples would indeed register the metric, because the “get-if-present” step of the reference would not find an existing metric, so the “register-if-absent” step would kick in.

What if your application combines more than one of the above techniques?

For example, suppose your application used the original @Metered annotation and also example 1? The @Metered annotation would register the metric and the @Inject sites would reference it by getting the already-registered metric.

In fact, if your app uses the original @Metered annotation and all of the examples above, then using our terms all of the example code reference the metric and get the already-registered one; only the @Metered annotation registers the metric.

One interesting point: The exact same lines of code can either register or reference a metric, depending on what else is in your app. Usually this doesn’t matter too much, but it’s noteworthy. In fact, we glossed over this earlier. Example 1, with its two @Inject usages, illustrates this by itself. Internally, one @Inject will register the metric and the other will get a reference to it. We cannot predict which is which and that’s fine because it doesn’t matter; the injections occur before our code runs anyway.

Note that referencing is not what MP Metrics means by metric reuse!

Reusing metrics

Well, then, what is metric reuse?

Metric reuse is multiple registration of the same metric using annotations.

Continuing our earlier example, if your app has more than one @Metered annotation then those injection sites reuse the metric:

Here, the system will register the meter and automatically update it at both annotation sites.

We might write the code this way if we don’t care about measuring the two methods separately, but instead we are interested in the aggregate traffic to our app for retrieving greetings, regardless of the format (plain text or HTML) the client might request.

This is reuse of the metric.

Note that gauges are never reusable, but the other types can be if you declare them to be.

State your intentions

By default, MP Metrics forbids reuse of a metric registered using annotations. This is why we had to add reusable = true to the @Metered annotations above when we wanted to reuse that metric. Without that, the system would throw an exception trying to register the metric the second time because on the annotations the default setting is reusable = false.

Why is this? The MP Metrics spec makes the very valid point that this prevents accidental reuse of a metric due to careless copy-and-paste as you write code. You could inadvertently have one metric collecting data from multiple unrelated points in your application, leaving you with useless data in that metric.

If your application also included example 1, as written, the injected fields would always give your code access to the current values for the single, reused metric.

Remember that annotations like @Metered can convey other metadata as well, as can other injection points using the @Metric annotation. Anywhere you refer to the same metric, all the metadata specified at all annotation sites must agree. That includes the reusability setting.

Metadata and reusability in the API

The earlier examples 2 and 3 show how your code can refer to a metric programmatically by invoking methods on a MetricRegistry object: counter, concurrentGauge, histogram, meter, and timer. (Again, gauges are treated a little differently and there is no such method for those.)

A few important points:

1. The rule about metadata consistency for a metric includes calls into the API. If your application references a metric by passing metadata (as in example 3 above), then the metadata supplied on all the API invocations and on all the annotations referring to that metric must agree.
2. Using the API, if you do not specify the reusability when you build the metadata then in MP Metrics 2.0 the default reusability is true, not false as it is with annotations.
3. You cannot reuse a metric by invoking MetricRegistry.register multiple times for the same metric. The register methods fail if the metric already exists under the same name. Instead, simply invoke MetricRegistry.register once, save the metric in a variable, and then access the variable from multiple places to update the metric.

Change in default reusability in MP Metrics 1.1 vs. 2.0

Here’s the backward-incompatible change in MP Metrics we mentioned at the outset.

If you have been working with MP Metrics 1.1, the default reusability when using the API has changed. In 1.1, reusability always defaulted to false, via the API and annotations. As described earlier, in MP Metrics 2.0 the default reusability via the API is true and remains false in annotations.

Bottom Line

Let’s recap.

We’ve used a meter as an example metric, but the same ideas apply to any metric:

• counters (@Counted)
• concurrent gauges (@ConcurrentGauge )
• gauges ( @Gauge ) — although remember, you cannot reuse gauges
• histograms (no annotation but you can add an @Inject or @Metric annotation to a field of type Histogram for example)
• meters ( @Metered )
• timers ( @Timed )

You can register a metric using one of these annotations and reference it using @Inject or @Metric or the API.

Referencing a metric uses “get if present, register if absent” semantics.

You can reuse a metric (except for gauges) by registering multiple places in your app using the same annotation at each site, explicitly setting reusability = true each time.

Acknowledgements

Thanks to Santiago Pericas-Geertsen who, in private conversations, helped identify some of the ambiguity in the spec and clarify my own thinking about this topic. And to Jan Martiška who, in the MicroProfile Google group, explained some of the original intent about MP metrics reuse.

References

• MicroProfile Metrics 2.0.2 spec
• Project Helidon website

Reusability in MicroProfile Metrics 2.0 and Helidon 1.3 was originally published in Helidon on Medium, where people are continuing the conversation by highlighting and responding to this story.

Here’s how to use OpenAPI in your Helidon SE and MP apps.

Helidon is a collection of Java libraries for writing microservices. Helidon MP supports MicroProfile, and Helidon SE offers a functional-style API, both of which help you write microservices in Java quickly.

Beginning with release 1.1.1, Helidon supports OpenAPI. Helidon MP implements the MicroProfile OpenAPI spec, and you can support OpenAPI in your SE app as well. Our documentation describes all the details for MP and SE, and our GitHub repository includes fully-working example apps with OpenAPI for MP and SE.

This article shows the very simplest way to add OpenAPI support to your applications.

The changes you make depend on whether you use Helidon MP or SE, so there are separate sections for each below. The way you access your app’s OpenAPI document is the same, so that’s described once near the end.

Using OpenAPI in Helidon MP

Update your pom.xml

Build a Jandex index that will be used to speed up scanning for OpenAPI-related annotations. In the <build><plugins> section add:

<plugin>
    <groupId>org.jboss.jandex</groupId>
    <artifactId>jandex-maven-plugin</artifactId>
    <version>1.0.6</version>
    <executions>
      <execution>
          <id>make-index</id>
          <goals>
              <goal>jandex</goal>
          </goals>
      </execution>
    </executions>
</plugin>

Add dependencies so you can use OpenAPI annotations (see below) and so the Helidon OpenAPI runtime (and the rest of Helidon support for MicroProfile 2.2) will be present when your app runs.

<dependency>
    <groupId>org.eclipse.microprofile.openapi</groupId>
    <artifactId>microprofile-openapi-api</artifactId>
    <version>1.1.2</version>
</dependency

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

Annotate the endpoints

Add OpenAPI annotations to your app’s endpoints.

Here’s a simple GET endpoint from the working example, updated for OpenAPI:

@GET
@Operation(
    summary = "Returns a generic greeting",
    description = "Greets the user generically")
@APIResponse(
    description = "Simple JSON containing the greeting",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = GreetingMessage.class)))
@Produces(MediaType.APPLICATION_JSON)
public JsonObject getDefaultMessage() {...}

The @Operation and @APIResponse annotations are new.

Using OpenAPI in Helidon SE

OpenAPI support in SE is basically the same as in MP except for annotation processing. SE does not do annotation processing, so OpenAPI cannot rely on that to gather endpoint information.

Instead, your SE app will typically include a static file containing the OpenAPI document that describes the app’s endpoints.

Follow these steps:

Update your pom.xml

Add this dependency:

<dependency>
     <groupId>io.helidon.openapi</groupId>
     <artifactId>helidon-openapi</artifactId>
     <version>1.1.2</version>
</dependency>

Register OpenAPISupport in your code

Your SE app will already have code similar to this. Just add the line that registers OpenAPISupport:

Config config = Config.create();
...
return Routing.builder()
         .register(JsonSupport.create())
         .register(OpenAPISupport.create(config))
         .register(health)
         .register(metrics)
         .register("/greet", greetService)
         .build();

Add a static OpenAPI document file

Tools such as Swagger let you describe your app’s API and they then generate an OpenAPI document file. Or you can just use an editor and create the file manually.

Once you have the file, add it to your project at META-INF/openapi.yml. The Helidon OpenAPI support will find it automatically.

Access the OpenAPI document

After you make the changes and build your app, run it. Then send a GET request to the automatically-supported/openapi endpoint. You will see a lot of output, including this describing the endpoint in the source code above:

paths:
  /greet:
    get:
      summary: Returns a generic greeting
      description: Greets the user generically
      responses:
        default:
          description: Simple JSON containing the greeting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GreetingMessage'

What next?

We’ve just scratched the surface here. For example, your MP or SE app can contain your own code that programmatically adds to or changes the OpenAPI model of your endpoints: model readers and filters.

In fact, Helidon OpenAPI support combines endpoint information from all of these sources:

• static documents,
• annotations (only for MP),
• configuration settings,
• model reader, and
• filter.

Our documentation at https://helidon.io/docs goes much further. Look for OpenAPI (that’s for SE) and MicroProfile -> OpenAPI in the navigation panel. Here are direct links to the SE and MP OpenAPI doc pages.

And remember the examples in the Helidon GitHub site are ready to build and run: openapi for SE and openapi-basic for MP.

Project Helidon and OpenAPI was originally published in Helidon on Medium, where people are continuing the conversation by highlighting and responding to this story.