- All Superinterfaces:
AutoCloseable
- All Known Subinterfaces:
EurekaDiscovery
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:
- 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.
- 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 aDiscoveredUrirepresenting the supplieddefaultValueas the last element of the discovered set, and must do so if the set would otherwise be empty. - 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. - Similarly, discovered sets may or may not represent cached information. Any caching, or lack of it, is a property
of the
Discoveryimplementation, not this specification. - They are never empty, since a discovered set will always contain at least one
DiscoveredUrirepresenting thedefaultValueargument supplied during the invocation of theuris(String, URI)method. - They and their contents are not retained by the
Discoveryimplementation 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:
- They are immutable. They are thus by definition also safe for concurrent use by multiple threads.
- The URIs they represent are (by definition) immutable. They are thus by definition also safe for concurrent use by multiple threads.
- They may bear metadata. The metadata must also be wholly immutable and thus by definition safe for concurrent use by multiple threads.
- Two
DiscoveredUriimplementations are equal if and only if theirClasses are equal and theURIs they represent are equal. Notably and deliberately, metadata borne by aDiscoveredUriimplementation must not be factored into any equality calculations, since some of it may be time-dependent, among other reasons.
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptiondefault voidclose()Closes any resources used by thisDiscoveryimplementation.Returns an immutable, non-empty,SequencedSet(a discovered set) ofDiscoveredUriinstances suitable for the supplied discovery name.
-
Method Details
-
close
default void close()Closes any resources used by thisDiscoveryimplementation.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:
closein interfaceAutoCloseable- See Also:
-
uris
Returns an immutable, non-empty,SequencedSet(a discovered set) ofDiscoveredUriinstances 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
DiscoveredUrielement representing the supplieddefaultValueargument. Normally, this element is located at the tail of the returnedSequencedSet.The semantics of the order of the returned
SequencedSetare strictly speaking undefined (beyond the guarantee of stability offered by allSequencedSetimplementations), but implementations are encouraged to place what they consider to be the most suitableDiscoveredUriat the head of the notional queue represented by the returnedSequencedSet.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
defaultValueURI.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 benulldefaultValue- aURIthat will be represented as aDiscoveredUriif 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 benull; 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, immutableSequencedSetofDiscoveredUriinstances - Throws:
NullPointerException- if any argument isnullIllegalArgumentException- if any argument is unsuitable in any wayIllegalStateException- if theDiscoveryimplementation is closed and does not support subsequent usage, as documented in its documentation of itsclose()method- See Also:
-