Module io.helidon.discovery
Package io.helidon.discovery

Interface Discovery

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
EurekaDiscovery
public interface Discovery extends AutoCloseable
An interface whose implementations discover possibly transient DiscoveredUri instances suitable, at the moment of discovery, for a given discovery name.

To discover URIs, a user of an instance of this interface invokes its uris(String, URI) method, supplying a non-null discovery name and a non-null URI to use, effectively, as a default value. The method returns an immutable, non-determinate discovered set of DiscoveredUri instances suitable for the invocation. If the discovered set would otherwise be empty, it will instead contain at least a DiscoveredUri whose uri() method returns the default value supplied to the invocation of the uris(String, URI) method that produced it. More characteristics and requirements of discovery names, discovered sets, and discovered URIs may be found below.

Acquisition

To acquire a Discovery instance, inject an instance of Discovery, using the Service.Inject annotation. Alternatively, and equivalently, use the static Services.get(Class) method, supplying Discovery.class as its sole argument.

Discovery Names

A discovery name is a name for which a Discovery implementation is capable of furnishing, at a moment in time, zero or more URIs, represented by DiscoveredUri instances.

A Discovery implementation must be prepared to handle names that do not identify any URIs at the moment of invocation, or will never identify any URIs. In either case, a Discovery implementation must return a discovered set that consists solely of a DiscoveredUri that represents the default value supplied to the invocation of the uris(String, URI) method that produced it. Implementations should return a DiscoveredUri in the tail position of the discovered set in all cases.

For maximum portability, a discovery name should comprise only legal hostname characters (to permit DNS-based or DNS-using implementations).

Discovery implementations should treat discovery names case-insensitively.

Since a discovery name is an application-level concern, not a component-level comncern, it is recommended that discovery-using components—which may be included in disparate applications with disparate naming requirements and Discovery implementations—allow an application developer to configure, or otherwise specify at deployment or runtime, any relevant discovery names that they use to account for potential differences in application and component namespaces.

Discovered Sets

Invocations of the uris(String, URI) method return immutable SequencedSets of DiscoveredUris. These are discovered sets. Discovered sets have at least the following characteristics:

  1. They are immutable, following the definition of immutability in the Java Collections Framework. They are thus by definition also safe for concurrent use by multiple threads.
  2. They are stable, in keeping with the contract of an immutable SequencedSet. Note however that the ordering that is preserved is implementation-dependent. Implementations should, as a general rule, add a DiscoveredUri representing the supplied defaultValue as the last element of the discovered set, and must do so if the set would otherwise be empty.
  3. They are non-determinate. That is, it is not guaranteed that two invocations of the uris(String, URI) method will return equal values. This is because a discovered set represents a moment-suitable collection of potentially available distinct resources.
  4. Similarly, discovered sets may or may not represent cached information. Any caching, or lack of it, is a property of the Discovery implementation, not this specification.
  5. They are never empty, since a discovered set will always contain at least one DiscoveredUri representing the defaultValue argument supplied during the invocation of the uris(String, URI) method.
  6. They and their contents are not retained by the Discovery implementation and are free for use by the caller for any purpose.

Discovered URIs

Discovered sets contain discovered URIs, represented by an instance of the DiscoveredUri interface (q. v.). Discovered URIs have the following characteristics:

  1. They are immutable. They are thus by definition also safe for concurrent use by multiple threads.
  2. The URIs they represent are (by definition) immutable. They are thus by definition also safe for concurrent use by multiple threads.
  3. They may bear metadata. The metadata must also be wholly immutable and thus by definition safe for concurrent use by multiple threads.
  4. Two DiscoveredUri implementations are equal if and only if their Classes are equal and the URIs they represent are equal. Notably and deliberately, metadata borne by a DiscoveredUri implementation must not be factored into any equality calculations, since some of it may be time-dependent, among other reasons.
See Also:

  • Method Details

    • close

      default void close()
      Closes any resources used by this Discovery implementation.

      The default implementation of this method does nothing. Overrides are expected and encouraged, particularly by implementations that contact external resources.

      An implementation may or may not permit other operations (such as invocations of its uris(String, URI) method) after an invocation of this method has successfully completed (an implementation of this method may result in a terminal state). An implementation should document whether closing results in such a terminal state.

      Implementations of this method must be idempotent and safe for concurrent use by multiple threads.

      Specified by:
      close in interface AutoCloseable
      See Also:

    • uris

      SequencedSet<DiscoveredUri> uris(String discoveryName, URI defaultValue)
      Returns an immutable, non-empty, SequencedSet (a discovered set) of DiscoveredUri instances suitable for the supplied discovery name.

      Because discovery may involve systems like the DNS, discovery names should contain only legal hostname characters.

      Return values yielded by invocations of implementations of this method are not guaranteed to be determinate: any two invocations of this method with the same discovery name and default value arguments may return non-equal discovered sets.

      The return value of an invocation of an implementation of this method must not be empty. At a minimum it must contain a single DiscoveredUri element representing the supplied defaultValue argument. Normally, this element is located at the tail of the returned SequencedSet.

      The semantics of the order of the returned SequencedSet are strictly speaking undefined (beyond the guarantee of stability offered by all SequencedSet implementations), but implementations are encouraged to place what they consider to be the most suitable DiscoveredUri at the head of the notional queue represented by the returned SequencedSet.

      Any given invocation of an implementation of this method may return a cached value, or a value retrieved at that moment, or a set containing only a representation of the supplied defaultValue URI.

      Implementations of this method must be idempotent and safe for concurrent use by multiple threads.

      Parameters:
      discoveryName - a discovery name ideally comprised only of legal hostname characters; must not be null
      defaultValue - a URI that will be represented as a DiscoveredUri if any kind of error occurs that prevents a normal invocation, or if the return value of an invocation of this method would otherwise be empty; must not be null; may be effectively included or ignored by the implementation if the discovered set would not be empty without it
      Returns:
      a non-null, non-empty, immutable SequencedSet of DiscoveredUri instances
      Throws:
      NullPointerException - if any argument is null
      IllegalArgumentException - if any argument is unsuitable in any way
      IllegalStateException - if the Discovery implementation is closed and does not support subsequent usage, as documented in its documentation of its close() method
      See Also: