Discovery

Overview

In Helidon, discovery is the general process of finding named sets of advertised resources at a moment of an application’s runtime. The advertised resources are often URIs representing microservice endpoints. In some environments, those endpoints might frequently come and go at unpredictable intervals, as microservices are started, stopped, and redeployed. The named applications they represent, however, are relatively static. Discovery helps link such a named application to its transient resources, so that clients can more easily contact it, knowing only its name.

Helidon Discovery is a feature with a vendor- and implementation-independent API backed by vendor-specific implementations of that API known as providers. A developer programs against the Discovery API, and packages a (normally Helidon-supplied) conformant Discovery implementation (a provider) with her application at deployment time. See Providers below.

Maven Coordinates

To enable Helidon Discovery, add the following dependency to your project’s pom.xml (see Managing Dependencies).

<dependencies>
    <dependency>
        <groupId>io.helidon.discovery</groupId>
        <artifactId>helidon-discovery</artifactId>1
    </dependency>
</dependencies>

Discovery is implemented by one or more

discovery providers. Generally you will choose a single provider and include its relevant dependencies on your runtime classpath as well. See the Providers section for more details.

API Usage

To use Helidon Discovery, you acquire an io.helidon.discovery.Discovery object and call its uris(String, URI) method to find resources represented as io.helidon.discovery.DiscoveredUri instances. You supply a discovery name, which is the name under which you expect to find advertised resources, and a default value, which is a URI to use in case the provider does not supply any resources. In general, DiscoveredUris you receive are ordered from more suitable to less suitable, where the definition of suitable is up to the provider. Some providers consider aspects like the health or uptime of an advertised resource when returning results. Others may not. Finally, a DiscoveredUri representing the default value you supply will always be present as the last element in the set of resources you receive.

Discovery Acquisition

Discovery Acquisition Using Helidon Inject

You can acquire a io.helidon.discovery.Discovery object by injecting it into your Helidon application:

Acquiring a Discovery object using Helidon Inject

import java.util.Objects;
import io.helidon.discovery.Discovery;
import io.helidon.service.registry.Service;

public class MyClass {

    private final Discovery discovery;

    @Service.Inject1
    public MyClass(Discovery discovery) {2
        this.discovery = discovery;3
    }
}

Acquiring Discovery Using Service Registry

You can acquire a io.helidon.discovery.Discovery object by using the Helidon Service Registry via the io.helidon.service.registry.Services façade:

Acquiring a Discovery object using the Helidon Service Registry

import io.helidon.discovery.Discovery;
import io.helidon.service.registry.Services;

public class MyOtherClass {

    private final Discovery discovery;

    public MyOtherClass() {
        this.discovery = Services.get(Discovery.class);1
    }

}

Discovering URIs

Discovery uses a discovery name to identify and discover URIs notionally belonging to an application. An application may have several URIs. The discovery name is the name that identifies the application for discovery purposes.

To discover a named application’s URIs, call the Discovery#uris(String, URI) method, passing it the discovery name and a URI to use as a default value. Both values must be non-null. You will receive an immutable SequencedSet of io.helidon.discovery.DiscoveredUri instances representing the URIs, ordered from the most to the least suitable, according to the provider. A DiscoveredUri representing the default value will appear last in the set:

Discovering URIs

import java.net.URI;
import java.util.SequencedSet;
import io.helidon.discovery.DiscoveredUri;
import io.helidon.discovery.Discovery;

SequencedSet<DiscoveredUri> uris =1
    discovery.uris("EXAMPLE",2
        URI.create("http://example.com/"));3
URI uri = uris.getFirst().uri();4

Providers

The Discovery API is implemented at runtime by a Discovery provider.

To use a Discovery provider, include it on your runtime classpath. See the provider’s documentation for details about installing, configuring, and using the provider.

WebClient Integration

Helidon integrates a Discovery provider with Web Client.

Maven Coordinates

To include the Helidon Web Client Discovery integration in your project, add the Web Client Discovery integration dependency (see Managing Dependencies). Any Discovery provider you use must also be present on the runtime classpath.

pom.xml

<dependencies>
    <dependency>
        <groupId>io.helidon.webclient</groupId>
        <artifactId>helidon-webclient-discovery</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>

The behavior of the Web Client Discovery integration is fully specified and documented.

Configuration

The Helidon Web Client Discovery integration can be configured using Helidon Config. Examples shown below are in YAML, but are expressible in any format and any location that Helidon Config supports.

Because the Helidon Web Client Discovery integration is fundamentally a Web Client Service, you configure it under a Web Client’s services configuration node:

webclient:
  services:
    discovery:1

Configuring URIs

To mark URIs requested by a Web Client as subject to discovery, and to use discovery names appropriate for them, you need to configure prefix URIs. URIs that match no prefix will not be subject to discovery:

webclient:
  services:
    discovery:
      prefix-uris:
        EXAMPLE: "https://example.com:443/"1
        TEST: "https://test.example.com:443/"23

Reference

• Discovery Javadoc
• Web Client Discovery Integration Javadoc
• Helidon Web Client