From 74827d2808a4db73d1402206a8e116b5702d031a Mon Sep 17 00:00:00 2001 From: Ladislav Thon Date: Wed, 29 Jun 2022 17:30:29 +0200 Subject: [PATCH] Clarify ambiguity resolution during dynamic lookup This attempts to clarify the current specification of `Instance.iterator()`, `Instance.stream()` and `Instance.handles()` in presence of dependency ambiguity. My understanding is that this modification is what has always been intended and how current implementations already work. --- .../core/injectionandresolution.asciidoc | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/spec/src/main/asciidoc/core/injectionandresolution.asciidoc b/spec/src/main/asciidoc/core/injectionandresolution.asciidoc index 9a14e3b3..9905f894 100644 --- a/spec/src/main/asciidoc/core/injectionandresolution.asciidoc +++ b/spec/src/main/asciidoc/core/injectionandresolution.asciidoc @@ -649,12 +649,18 @@ The `get()` method must: The `iterator()` method must: * Identify the set of beans that have the required type and required qualifiers and are eligible for injection into the class into which the parent `Instance` was injected, according to the rules of typesafe resolution, as defined in <>, resolving ambiguities according to <>. -* Return an `Iterator`, that iterates over the set of contextual references for the resulting beans and required type, as defined in <>. +* If typesafe resolution results in an unsatisfied dependency, the set of resulting beans is empty. + If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains at least one alternative, the set of resulting beans contains all beans that were not eliminated during ambiguity resolution. + If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains no alternative, the set of resulting beans contains all candidate beans. +* Return an `Iterator`, that iterates over the set of contextual references for the resulting beans, as defined in <>. The `stream()` method must: * Identify the set of beans that have the required type and required qualifiers and are eligible for injection into the class into which the parent `Instance` was injected, according to the rules of typesafe resolution, as defined in <>, resolving ambiguities according to <>. -* Return a `Stream`, that can stream over the set of contextual references for the resulting beans and required type, as defined in <>. +* If typesafe resolution results in an unsatisfied dependency, the set of resulting beans is empty. + If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains at least one alternative, the set of resulting beans contains all beans that were not eliminated during ambiguity resolution. + If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains no alternative, the set of resulting beans contains all candidate beans. +* Return a `Stream`, that can stream over the set of contextual references for the resulting beans, as defined in <>. The methods `isUnsatisfied()`, `isAmbiguous()` and `isResolvable()` must: @@ -671,12 +677,12 @@ An `UnsupportedOperationException` is thrown if the active context object for th The `getHandle()` method must: * Return an initialized contextual reference `Handle` for a bean that has the required type and qualifiers and is eligible for injection. The contextual reference must be resolved lazily, i.e. when first needed. <> is described in a separate paragraph. -* Throw `UnsatisfiedResolutionException` if there is no bean with given type and qualifiers -* Throw `AmbiguousResolutionException` if there is more than one bean given type and qualifiers +* Throw `UnsatisfiedResolutionException` if there is no bean with given type and qualifiers. +* Throw `AmbiguousResolutionException` if there is more than one bean given type and qualifiers. The `handles()` method must: -* Allow iterating over contextual reference handles for all beans that have the required type and required qualifiers and are eligible for injection. +* Allow iterating over contextual reference handles for all beans that would be produced by the `iterator()` (or `stream()`) method. * Return stateless `Iterable`. Therefore, each `Iterable#iterator()` produces a new set of handles. The `handlesStream()` is a `Stream` equivalent of the aforementioned `handles()` method.