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

Interface Provider

All Known Implementing Classes:
AbstractProvider, AbstractTreeBasedProvider, ConfigSourceProvider, EnvironmentVariableProvider, InputStreamJacksonProvider, JacksonProvider, JsonProvider, PropertiesProvider, ProxyingProvider, SystemPropertyProvider, TomlProvider, TypesafeConfigHoconProvider, YamlProvider
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface Provider
A service provider of Values that might be suitable for a Loader implementation to return.

Provider instances are subordinate to DefaultLoader.

Any Provider implementation must have a public constructor that has no arguments.

Author:
Laird Nelson
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Value<?>
    get(Loader<?> requestor, Path<? extends Type> absolutePath)
    Returns a Value suitable for the supplied Loader and Path, or null if there is no such Value now and if there never will be such a Value for the supplied arguments.
    default Type
    lowerBound()
    Returns a Type representing the lower type bound of all possible values supplied by this Provider.

  • Method Details

    • lowerBound

      default Type lowerBound()
      Returns a Type representing the lower type bound of all possible values supplied by this Provider.

      Often the value returned by implementations of this method is no more specific than the lowest possible type, which is null, meaning that the Provider has a chance of producing a Value for any requested type.

      A return value of, for example, String.class indicates that the Provider may satisfy requests for String.class, or any of its supertypes (such as CharSequence or Object), but cannot satisfy requests for Integer.class, for example.

      A return value of Object.class would be extremely unusual and would indicate a maximally opaque type, i.e. only requests for exactly Object.class have the possibility of being satisfied by this Provider. Such a return value is possible, but rarely used, and Provider implementations are urged to consider returning a different Type.

      Note that this method is used solely to help eliminate types from consideration, not permit them. That is, although Provider may indicate via an implementation of this method that a given Type is suitable, it is not thereby obliged to return a Value corresponding to it from its get(Loader, Path) method implementation.

      The default implementation of this method returns null. Many Provider implementations will choose not to override this method.

      Returns:
      a Type representing the lower type bound of all possible values supplied by this Provider, or null to indicate the lowest possible type bound
      Idempotency:
      This method is, and overrides of this method must be, idempotent and deterministic.
      Nullability:
      This method always does, and overrides often may, return null.
      Thread Safety:
      This method is, and overrides of this method must be, safe for concurrent use by multiple threads.

    • get

      Value<?> get(Loader<?> requestor, Path<? extends Type> absolutePath)
      Returns a Value suitable for the supplied Loader and Path, or null if there is no such Value now and if there never will be such a Value for the supplied arguments.

      In addition to the other requirements described here, the following assertions will be (and must be) true when this method is called in the normal course of events:

      • assert absolutePath.isAbsolute();
      • assert absolutePath.startsWith(requestor.absolutePath());
      • assert !absolutePath.equals(requestor.absolutePath());

      If any caller does not honor these requirements, undefined behavior may result.

      Parameters:
      requestor - the Loader seeking a Value; must not be null
      absolutePath - an absolute Path for which the supplied Loader is seeking a value; must not be null
      Returns:
      a Value more or less suitable for the combination of the supplied Loader and Path, or null if there is no such Value now and if there never will be such a Value for the supplied arguments
      Throws:
      NullPointerException - if either requestor or absolutePath is null
      IllegalArgumentException - if absolutePath is not absolute, or if !absolutePath.startsWith(requestor.absolutePath()), or if absolutePath.equals(requestor.absolutePath())
      Idempotency:
      Implementations of this method must be idempotent but are not assumed to be deterministic.
      Nullability:
      Implementations of this method may return null.
      Thread Safety:
      Implementations of this method must be safe for concurrent use by multiple threads.