Module org.microbean.loader
Package org.microbean.loader.spi

Interface AmbiguityHandler

@LoaderFacade(false) public interface AmbiguityHandler
An interface whose implementations handle various kinds of ambiguity that arise when a Loader seeks configured objects by way of various Providers.
Author:
Laird Nelson

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    compatible(Path.Element<?> e1, Path.Element<?> e2)
    Returns true if and only if the second Path.Element is compatible with respect to the first Path.Element.
    default <U> Value<U>
    disambiguate(Loader<?> requestor, Path<? extends Type> absolutePath, Provider p0, Value<U> v0, Provider p1, Value<U> v1)
    Given two Values and some contextual objects, chooses one over the other and returns it, or synthesizes a new Value and returns that, or indicates that disambiguation is impossible by returning null.
    default void
    providerRejected(Loader<?> rejector, Path<? extends Type> absolutePath, Provider provider)
    Called to notify this AmbiguityHandler that a Provider was discarded during the search for a configured object.
    default @org.microbean.development.annotation.Experimental int
    score(Path<? extends Type> absoluteReferencePath, Path<? extends Type> valuePath)
    Returns a score indicating the relative specificity of valuePath with respect to absoluteReferencePath, or Integer.MIN_VALUE if valuePath is wholly unsuitable for further consideration or processing.
    default int
    score(Qualifiers<? extends String,?> referenceQualifiers, Qualifiers<? extends String,?> valueQualifiers)
    Returns a score indicating the relative specificity of valueQualifiers with respect to referenceQualifiers, or Integer.MIN_VALUE if valueQualifiers is wholly unsuitable for further consideration or processing.
    default void
    valueRejected(Loader<?> rejector, Path<? extends Type> absolutePath, Provider provider, Value<?> value)
    Called to notify this AmbiguityHandler that a Value provided by a Provider was discarded during the search for a configured object.

  • Method Details

    • providerRejected

      default void providerRejected(Loader<?> rejector, Path<? extends Type> absolutePath, Provider provider)
      Called to notify this AmbiguityHandler that a Provider was discarded during the search for a configured object.

      The default implementation of this method does nothing.

      Parameters:
      rejector - the Loader that rejected the Provider; must not be null
      absolutePath - the absolute Path for which a configured object is being sought; must not be null
      provider - the rejected Provider, which may be null
      Throws:
      NullPointerException - if either rejector or absolutePath is null

    • valueRejected

      default void valueRejected(Loader<?> rejector, Path<? extends Type> absolutePath, Provider provider, Value<?> value)
      Called to notify this AmbiguityHandler that a Value provided by a Provider was discarded during the search for a configured object.

      The default implementation of this method does nothing.

      Parameters:
      rejector - the Loader that rejected the Provider; must not be null
      absolutePath - the absolute Path for which a configured object is being sought; must not be null
      provider - the Provider providing the rejected value; must not be null
      value - the rejected Value; must not be null
      Throws:
      NullPointerException - if any argument is null

    • score

      default int score(Qualifiers<? extends String,?> referenceQualifiers, Qualifiers<? extends String,?> valueQualifiers)
      Returns a score indicating the relative specificity of valueQualifiers with respect to referenceQualifiers, or Integer.MIN_VALUE if valueQualifiers is wholly unsuitable for further consideration or processing.

      This is not a comparison method.

      Parameters:
      referenceQualifiers - the Qualifiers against which to score the supplied valueQualifiers; must not be null
      valueQualifiers - the Qualifiers to score against the supplied referenceQualifiers; must not be null
      Returns:
      a relative score for valueQualifiers with respect to referenceQualifiers; meaningless on its own unless it is Integer.MIN_VALUE in which case the supplied valueQualifiers will be treated as wholly unsuitable for further consideration or processing
      Throws:
      NullPointerException - if either parameter is null
      See Also:
      Idempotency:
      The default implementation of this method is, and its overrides must be, idempotent and deterministic. Specifically, the same score is and must be returned whenever this method is invoked with the same arguments.
      Thread Safety:
      The default implementation of this method is, and its overrides must be, safe for concurrent use by multiple threads.

    • score

      @Experimental default @org.microbean.development.annotation.Experimental int score(Path<? extends Type> absoluteReferencePath, Path<? extends Type> valuePath)
      Returns a score indicating the relative specificity of valuePath with respect to absoluteReferencePath, or Integer.MIN_VALUE if valuePath is wholly unsuitable for further consideration or processing.

      This is not a comparison method.

      The following preconditions must hold or undefined behavior will result:

      • Neither parameter's value may be null.
      • absoluteReferencePath must be absolute
      • valuePath must be selectable with respect to absoluteReferencePath, where the definition of selectability is described below

      For valuePath to "be selectable" with respect to absoluteReferencePath for the purposes of this method and for no other purpose, true must be returned by a hypothetical invocation of code whose behavior is that of the following:

      absoluteReferencePath.endsWith(valuePath, AmbiguityHandler::compatible);

      If, during scoring, valuePath is found to be wholly unsuitable for further consideration or processing, Integer.MIN_VALUE will be returned to indicate this. Overrides must follow suit or undefined behavior elsewhere in this framework will result.

      In the normal course of events, this method will be called after a call to score(Qualifiers, Qualifiers), and so there is normally no need for an implementation of this method to consult a Path's affiliated Qualifiers.

      Parameters:
      absoluteReferencePath - the Path against which to score the supplied valuePath; must not be null; must adhere to the preconditions above
      valuePath - the Path to score against the supplied absoluteReferencePath; must not be null; must adhere to the preconditions above
      Returns:
      a relative score for valuePath with respect to absoluteReferencePath; meaningless on its own unless it is Integer.MIN_VALUE in which case the supplied valuePath will be treated as wholly unsuitable for further consideration or processing
      Throws:
      NullPointerException - if either parameter is null
      IllegalArgumentException - if certain preconditions have been violated
      See Also:
      Idempotency:
      The default implementation of this method is, and its overrides must be, idempotent and deterministic. Specifically, the same score is and must be returned whenever this method is invoked with the same Paths.
      Thread Safety:
      The default implementation of this method is, and its overrides must be, safe for concurrent use by multiple threads.

    • disambiguate

      default <U> Value<U> disambiguate(Loader<?> requestor, Path<? extends Type> absolutePath, Provider p0, Value<U> v0, Provider p1, Value<U> v1)
      Given two Values and some contextual objects, chooses one over the other and returns it, or synthesizes a new Value and returns that, or indicates that disambiguation is impossible by returning null.
      Type Parameters:
      U - the type of objects the Values in question can supply
      Parameters:
      requestor - the Loader currently seeking a Value; must not be null
      absolutePath - an absolute Path for which a value is being sought; must not be null
      p0 - the Provider that supplied the first Value; must not be null; must not be equal to p1
      v0 - the first Value; must not be null
      p1 - the Provider that supplied the second Value; must not be null; must not be equal to p0
      v1 - the second Value; must not be null
      Returns:
      the Value to use instead; ordinarily one of the two supplied Values but may be null to indicate that disambiguation was impossible, or an entirely different Value altogether
      Throws:
      NullPointerException - if any argument is null
      Idempotency:
      The default implementation of this method is, and its overrides must be, idempotent. The default implementation of this method is deterministic, but its overrides need not be.
      Nullability:
      The default implementation of this method and its overrides may return null.
      Thread Safety:
      The default implementation of this method is, and its overrides must be, safe for concurrent use by multiple threads.

    • compatible

      static boolean compatible(Path.Element<?> e1, Path.Element<?> e2)
      Returns true if and only if the second Path.Element is compatible with respect to the first Path.Element.

      This method returns true unless one of the following conditions holds:

      Parameters:
      e1 - the first Path.Element; must not be null
      e2 - the second Path.Element; must not be null
      Returns:
      true if and only if the second Path.Element is compatible with the first
      Throws:
      NullPointerException - if either argument is null
      Idempotency:
      This method is idempotent and deterministic.
      Thread Safety:
      This method is safe for concurrent use by multiple threads.